Optimization backend (corneto.backend)#

Optimization backends and the runtime-selected defaults.

class corneto.backend.Backend(default_solver=None, sparse_class=<class 'scipy.sparse._csr.csr_array'>)#

Bases: ABC

Parameters:
is_available()#
Return type:

bool

version()#
Return type:

str

static get_symbols(expressions)#
Parameters:

expressions (Iterable[CExpression])

Return type:

Set[CSymbol]

abstractmethod available_solvers()#
Return type:

List[str]

abstractmethod Constant(value, name=None)#
Parameters:

  • value (Any)

  • name (str | None)

Return type:

CSymbol

abstractmethod Variable(name=None, shape=None, lb=None, ub=None, vartype=VarType.CONTINUOUS)#

Create a variable for optimization.

This method defines an optimization variable with optional bounds, type, and additional graph-related properties.

Parameters:

  • name (Optional[str]) – The name of the variable. Defaults to None.

  • shape (Optional[Tuple[int, ...]]) – The shape of the variable as a tuple. Defaults to None.

  • lb (Optional[Union[float, np.ndarray]]) – The lower bound of the variable. Can be a scalar or an array. Defaults to None.

  • ub (Optional[Union[float, np.ndarray]]) – The upper bound of the variable. Can be a scalar or an array. Defaults to None.

  • vartype (VarType) – The type of the variable (e.g., continuous, integer). Defaults to VarType.CONTINUOUS.

Returns:

The created variable symbol, to be used in further expressions or constraints.

Return type:

CSymbol

abstractmethod Parameter(name=None, shape=None, value=None)#
Parameters:
Return type:

CSymbol

Problem(constraints=None, objectives=None, expressions=None, weights=None, direction=Direction.MIN)#
Parameters:

  • constraints (CExpression | List[CExpression] | None)

  • objectives (CExpression | List[CExpression] | None)

  • expressions (Dict[str, CExpression] | None)

  • weights (float | List[float] | None)

  • direction (Direction)

Return type:

ProblemDef

abstractmethod build(p)#
Parameters:

p (ProblemDef)

Return type:

Any

solve(p, solver=None, max_seconds=None, warm_start=False, verbosity=0, **options)#
Parameters:

  • p (ProblemDef)

  • solver (str | Solver | None)

  • max_seconds (int | None)

  • warm_start (bool)

  • verbosity (int)

Flow(g, lb=0, ub=10, n_flows=1, values=False, shared_bounds=False, varname='_flow', create_nonzero_indicators=False, alias_flow='flow', alias_flow_ipos='positive_flow', alias_flow_ineg='negative_flow', alias_nonzero_flow='with_flow', indicator_tolerance=0.0001, force_matrix=False)#
Parameters:
Return type:

ProblemDef

Acyclic0(g, P, indicator_positive_var_name=None, indicator_negative_var_name=None, acyclic_var_name='_dag_layer', max_parents=None, vertex_lb_dist=None, vertex_ub_dist=None)#

Create Acyclicity Constraint.

This function creates acyclicity constraints, ensuring that the selected edges form an acyclic graph, meaning there are no cycles on the given property. Acyclicity can be applied, for example, over flow constraints or signal properties.

Parameters:

  • g (BaseGraph) – The graph that defines the problem.

  • P (ProblemDef) – The problem definition.

  • indicator_positive_var_name (str) – The name of the indicator variable, i.e., which edges are selected. Default is EXPR_NAME_FLOW_IPOS.

  • indicator_negative_var_name (str, optional) – The name of the indicator variable for negative flows. Default is None. If a negative flow appears, the source and target nodes of the edge are reversed. For example, A->B with positive flow implies order(B) > order(A), with negative flow it implies order(A) > order(B).

  • acyclic_var_name (str, optional) – The name of the acyclic variable. Default is VAR_DAG.

  • max_parents (Optional[Union[int, Dict[Any, int]]], optional) – The maximum number of parents per node. If an integer is provided, the maximum number of parents is the same for all nodes. If a dictionary is provided, the maximum number of parents can be different for each node. Default is None.

  • Returns

  • -------

  • ProblemDef – The problem definition with acyclic constraints.

  • Raises

  • ------

  • NotImplementedError – If hyperedges are used.

  • vertex_lb_dist (List[Dict[Any, int]] | None)

  • vertex_ub_dist (List[Dict[Any, int]] | None)

Return type:

ProblemDef

Acyclic(g, P, indicator_positive_var_name=None, indicator_negative_var_name=None, acyclic_var_name='_dag_layer', max_parents=None, vertex_lb_dist=None, vertex_ub_dist=None)#

Create Acyclicity Constraint.

This function creates acyclicity constraints, ensuring that the selected edges form an acyclic graph, meaning there are no cycles on the given property. Acyclicity can be applied, for example, over flow constraints or signal properties.

Parameters:

  • g (BaseGraph) – The graph that defines the problem.

  • P (ProblemDef) – The problem definition.

  • indicator_positive_var_name (str) – The name of the indicator variable, i.e., which edges are selected. Default is EXPR_NAME_FLOW_IPOS.

  • indicator_negative_var_name (str, optional) – The name of the indicator variable for negative flows. Default is None. If a negative flow appears, the source and target nodes of the edge are reversed. For example, A->B with positive flow implies order(B) > order(A), with negative flow it implies order(A) > order(B).

  • acyclic_var_name (str, optional) – The name of the acyclic variable. Default is VAR_DAG.

  • max_parents (Optional[Union[int, Dict[Any, int]]], optional) – The maximum number of parents per node. If an integer is provided, the maximum number of parents is the same for all nodes. If a dictionary is provided, the maximum number of parents can be different for each node. Default is None.

  • vertex_lb_dist (Optional[List[Dict[Any, int]]], optional) – A list (one entry per experiment) of dictionaries that assign a lower bound (minimum layer/distance) for each vertex.

  • vertex_ub_dist (Optional[List[Dict[Any, int]]], optional) – A list (one entry per experiment) of dictionaries that assign an upper bound (maximum layer/distance) for each vertex.

  • Returns

  • -------

  • ProblemDef – The problem definition with acyclic constraints.

  • Raises

  • ------

  • NotImplementedError – If hyperedges are used.

Return type:

ProblemDef

AcyclicFlow(g, lb=0, ub=10, values=False, max_parents=None, vertex_lb_dist=None, varname='_flow', alias_flow='flow', alias_flow_ipos='positive_flow', alias_flow_ineg='negative_flow', alias_nonzero_flow='with_flow', indicator_tolerance=0.0001)#
Parameters:
Return type:

ProblemDef

Indicator(V, indexes=None, suffix='_i', name=None)#
Parameters:
Return type:

ProblemDef

ExactSupport(V, *, selected=None, indexes=None, epsilon=1.0, nonnegative=False, name=None, positive_name=None, negative_name=None)#

Link a bounded value to binary structural support with a gap.

selected == 0 forces the value to zero. selected == 1 forces its magnitude to be at least epsilon. For nonnegative values this uses one binary per entry. Signed values use mutually exclusive positive and negative binaries and expose their sum as selected.

epsilon may be a scalar or an array explicitly broadcastable to the selected value shape. “Exact” refers to this mathematical minimum-magnitude gap; it is not a solver-tolerance guarantee, and values smaller than the requested gap may still be returned by a numerically inaccurate solve and should be checked by the caller.

An existing binary selector symbol can be supplied to avoid introducing a redundant binary variable, which is useful when a method already has a shared structural edge-selection variable. An arbitrary selector expression is linked to an auxiliary binary selector, so fractional expression values make the model infeasible instead of relaxing the support constraints.

Parameters:
Return type:

ProblemDef

SelectedFlow(g, *, lb=0, ub=10, n_flows=1, edge_indices=None, flow_blocks=None, selector_groups=None, epsilon=1.0, exact_support=True, selected=None, acyclic_graph=None, max_parents=None, flow_name='flow', selected_by_flow_name='selected_by_flow', selected_by_group_name=None, selected_any_name='selected_any', dag_name='_dag_layer')#

Create bounded flows with exact per-flow and shared support.

Flow conservation is imposed on g. Exact support binaries are created only for edge_indices so boundary edges do not consume unnecessary integer variables. Rows whose selected flow bounds are nonnegative use one binary per flow; rows that permit negative flow automatically use mutually exclusive positive and negative binaries. Set exact_support=False to use one bounded indicator per entry: nonzero flow still implies selection, but a selected entry may carry zero flow. This smaller formulation is suitable when a minimizing objective makes such false selections unattractive and flow direction is not otherwise required.

flow_blocks can map multiple rectangular regions of the flow matrix to the same logical edge ordering. selector_groups can then map block columns to shared selector columns. This supports layouts such as forward and reversed edge blocks without indicators on the unused off-diagonal blocks. Set selected_any_name=None when a union across selector columns is not needed.

The union across flows can be linked to an existing shared selector. With signed acyclic flows, direction-specific unions are used so a negative flow orders the edge in reverse. No redundant structural-union binary is created in that case.

Parameters:
Return type:

ProblemDef

NonZeroIndicator(V, *args, indexes=None, suffix_pos='_ipos', suffix_neg='_ineg', tolerance=0.001)#
Parameters:
Return type:

ProblemDef

linear_or(x, axis=None, varname='or', ignore_type=False)#
Parameters:

  • x (CExpression)

  • axis (int | None)

Return type:

ProblemDef

linear_and(x, axis=None, varname='and')#
Parameters:

  • x (CExpression)

  • axis (int | None)

Return type:

ProblemDef

linear_xor(x, axis=None, varname='xor', ignore_type=False)#
Parameters:

  • x (CExpression)

  • axis (int | None)

Return type:

ProblemDef

vstack(arg_list)#
Parameters:

arg_list (Iterable[CExpression])

Return type:

CExpression

hstack(arg_list)#
Parameters:

arg_list (Iterable[CExpression])

Return type:

CExpression

zero_function()#
Return type:

CExpression

class corneto.backend.CvxpyBackend(default_solver=None, sparse_class=<class 'scipy.sparse._csr.csr_array'>)#

Bases: Backend

Parameters:
available_solvers()#
Return type:

List[str]

Constant(value, name=None)#
Parameters:

  • value (Any)

  • name (str | None)

Return type:

CSymbol

Variable(name=None, shape=None, lb=None, ub=None, vartype=VarType.CONTINUOUS)#

Create a variable for optimization.

This method defines an optimization variable with optional bounds, type, and additional graph-related properties.

Parameters:

  • name (Optional[str]) – The name of the variable. Defaults to None.

  • shape (Optional[Tuple[int, ...]]) – The shape of the variable as a tuple. Defaults to None.

  • lb (Optional[Union[float, np.ndarray]]) – The lower bound of the variable. Can be a scalar or an array. Defaults to None.

  • ub (Optional[Union[float, np.ndarray]]) – The upper bound of the variable. Can be a scalar or an array. Defaults to None.

  • vartype (VarType) – The type of the variable (e.g., continuous, integer). Defaults to VarType.CONTINUOUS.

Returns:

The created variable symbol, to be used in further expressions or constraints.

Return type:

CSymbol

Parameter(name=None, shape=None, value=None)#
Parameters:
Return type:

CSymbol

build(p)#
Parameters:

p (ProblemDef)

Return type:

Any

class corneto.backend.PicosBackend(default_solver=None)#

Bases: Backend

Parameters:

default_solver (str | None)

available_solvers()#
Return type:

List[str]

build(p)#
Parameters:

p (ProblemDef)

Return type:

Any

Constant(value, name=None)#
Parameters:

  • value (Any)

  • name (str | None)

Return type:

CSymbol

Variable(name=None, shape=None, lb=None, ub=None, vartype=VarType.CONTINUOUS, variable=True)#

Create a variable for optimization.

This method defines an optimization variable with optional bounds, type, and additional graph-related properties.

Parameters:

  • name (Optional[str]) – The name of the variable. Defaults to None.

  • shape (Optional[Tuple[int, ...]]) – The shape of the variable as a tuple. Defaults to None.

  • lb (Optional[Union[float, np.ndarray]]) – The lower bound of the variable. Can be a scalar or an array. Defaults to None.

  • ub (Optional[Union[float, np.ndarray]]) – The upper bound of the variable. Can be a scalar or an array. Defaults to None.

  • vartype (VarType) – The type of the variable (e.g., continuous, integer). Defaults to VarType.CONTINUOUS.

  • variable (bool)

Returns:

The created variable symbol, to be used in further expressions or constraints.

Return type:

CSymbol

Parameter(name=None, shape=None, value=None)#
Parameters:
Return type:

CSymbol

class corneto.backend.VarType(value)#

Bases: str, Enum

INTEGER = 'integer'#
CONTINUOUS = 'continuous'#
BINARY = 'binary'#
corneto.backend.available_backends()#

Return the installed and usable optimization backends.