Skip to content

Binary Integer Linear Programming (BILP) API Reference

Data

Data model for general Binary Integer Linear Programming (BILP) use case.

BilpData

Bases: UcData

Data container for general Binary Integer Linear Programming (BILP).

A BILP is an optimization problem with: - Binary decision variables (0 or 1) - Linear objective function - Linear constraints (equality or inequality)

Attributes:

  • name (Literal['binary_integer_linear_programming']) –

    Constant identifier for this data type.

  • constraint_matrix (NumPyArray) –

    An m x n constraint matrix S where m is the number of constraints and n is the number of variables.

  • rhs (list[float]) –

    Right-hand side vector b of length m.

  • objective_coeffs (list[float]) –

    Coefficient vector c of the linear objective function of length n.

  • constraint_senses (list[Literal['==', '<=', '>=']]) –

    List of constraint types for each row in constraint_matrix. Defines whether the constraint is equality, <=, or >=.

__post_init__() -> None

Ensure constraint_senses is set; default to equality if None.

plot(*, ax: Axes | None = None) -> Axes

Visualize the BILP data with a constraint matrix heatmap and constraint types.

Parameters:

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    Axes with the plot.

to_string() -> str

Return a string describing the data instance.

from_arrays(constraint_matrix: np.ndarray, rhs: list[float], objective_coeffs: list[float], constraint_senses: list[Literal['==', '<=', '>=']] | None = None) -> BilpData staticmethod

Create a BilpData instance from numpy arrays.

Parameters:

  • constraint_matrix (ndarray) –

    The m x n constraint matrix.

  • rhs (list[float]) –

    Right-hand side vector of length m.

  • objective_coeffs (list[float]) –

    Coefficients for the linear objective function.

  • constraint_senses (list[Literal['==', '<=', '>=']] | None, default: None ) –

    Constraint types for each row. Defaults to equality if None.

Returns:

  • BilpData –

    A populated BilpData instance.

generate_random(n_vars: int = 5, n_constraints: int = 3, size: int | None = None, seed: int | None = None) -> BilpData staticmethod

Generate a random feasible BILP instance.

Ensures feasibility by first generating a random binary solution and computing the RHS from it. Constraint types are chosen randomly.

Parameters:

  • n_vars (int, default: 5 ) –

    Number of binary variables. Default is 5.

  • n_constraints (int, default: 3 ) –

    Number of constraints. Default is 3.

  • size (int | None, default: None ) –

    If provided, overrides n_vars for collection compatibility.

  • seed (int | None, default: None ) –

    Random seed for reproducibility. Default is None.

Returns:

  • BilpData –

    A randomly generated BILP instance.

Formulation

Formulation for general Binary Integer Linear Programming (BILP) use case.

BilpFormulation

Bases: UcFormulation[BilpData, BilpSolution]

Formulation class for general Binary Integer Linear Programming (BILP).

This class translates a BilpData instance into an optimization model suitable for solvers. Supports equality and inequality constraints.

Mathematical Formulation 
Decision Variables:
    x_i in {0,1} for i = 0, ..., n-1

Objective Function:
    maximize sum_i c_i * x_i

Constraints:
    For each constraint j:
        sum_i S[j,i] * x[i] {==, <=, >=} b[j]
    Where the type is defined in data.constraint_senses[j].

to_string(data: BilpData) -> str staticmethod

Return a detailed string describing the formulation.

Parameters:

  • data (BilpData) –

    The BILP problem data.

Returns:

  • str –

    Multi-line description of the variables, objective, and constraints.

formulate(data: BilpData) -> Model staticmethod

Formulate the general BILP as an optimization model.

Parameters:

  • data (BilpData) –

    Problem data containing the constraint matrix, RHS, objective coefficients, and constraint senses.

Returns:

  • Model –

    An optimization model ready to be solved by a solver.

Notes
  • Supports equality (==, default), less-than-or-equal (<=), and greater-than-or-equal (>=) constraints.
  • All decision variables are binary.

interpret(solution: Solution, data: BilpData) -> BilpSolution staticmethod

Interpret the solver's solution and convert it to a BilpSolution.

Parameters:

  • solution (Solution) –

    The solver's solution object.

  • data (BilpData) –

    The problem data.

Returns:

  • BilpSolution –

    Structured solution containing: - solution vector - objective value - validity flag (all constraints satisfied)

Raises:

Solution

Solution model for BILP use case.

BilpSolution

Bases: UcSolution

Solution for the Binary Integer Linear Programming (BILP) use case.

Attributes:

  • name (Literal['binary_integer_linear_programming']) –

    Identifier for this solution type.

  • solution_vector (list[int]) –

    Binary solution vector x.

  • objective_value (float) –

    Objective value c^T x.

  • is_valid (bool) –

    Whether all equality constraints S x == b are satisfied.

plot(data: BilpData | None = None, *, ax: Axes | None = None) -> Axes | list[Axes]

Visualize the BILP solution with a variable bar chart and optional constraint heatmap.

Parameters:

  • data (BilpData | None, default: None ) –

    Problem data providing the constraint matrix and senses. If provided, a heatmap showing which constraints are activated by the solution is displayed below the solution bar chart.

  • ax (Axes | None, default: None ) –

    Matplotlib axes or array of axes to draw on. If None, a new figure with two subplots (bars + heatmap) is created.

Returns:

  • Axes | list[Axes] –

    The axes containing the plot(s). Returns a single Axes if only one subplot is used, otherwise a list of two Axes [bar_chart, heatmap].

to_string() -> str

Return a string describing the solution.

Instance

Instance model for Bilp use case.

BilpInstance

Bases: UcInstance[BilpData, BilpFormulation, BilpSolution]

Instance combining data and formulation for Bilp.

Collection

Collection of BILP instances.

BilpCollection

Bases: UcInstanceCollection[BilpInstance]

Collection of BILP instances.

from_random(min_size: int, max_size: int, num_instances: int = 1, *, seed: int | None = None) -> BilpCollection classmethod

Not implemented for BILP.

Random generation cannot reliably produce feasible BILP instances with mixed constraint types, as there is no efficient way to guarantee that a valid binary solution exists for arbitrary constraint matrices and right-hand sides.

Raises:

filter_infeasible(max_runtime: float = 3600, *, quiet: bool = True) -> list[bool]

Drop the instances of this collection that have no feasible solution.

Every instance is formulated and handed to SCIP, which stops as soon as it finds the first feasible solution. An instance is removed from the collection when SCIP proves the model infeasible, when no solution turns up within max_runtime, or when formulating it fails altogether. This keeps randomly generated instances from breaking a downstream pipeline.

Parameters:

  • max_runtime (float, default: 3600 ) –

    SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds.

  • quiet (bool, default: True ) –

    Suppress the SCIP solver output.

Returns:

  • list[bool] –

    Feasibility mask over the instances as they were before filtering, in that order: True where the instance was kept, False where it was removed.

Raises: