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 Type Description
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:

Name Type Description Default
ax Axes | None

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

 None

Returns:

Type Description
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:

Name Type Description Default
constraint_matrix ndarray

The m x n constraint matrix.

 required
rhs list[float]

Right-hand side vector of length m.

 required
objective_coeffs list[float]

Coefficients for the linear objective function.

 required
constraint_senses list[Literal['==', '<=', '>=']] | None

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

 None

Returns:

Type Description
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:

Name Type Description Default
n_vars int

Number of binary variables. Default is 5.

 5
n_constraints int

Number of constraints. Default is 3.

 3
size int | None

If provided, overrides n_vars for collection compatibility.

 None
seed int | None

Random seed for reproducibility. Default is None.

 None

Returns:

Type Description
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:

Name Type Description Default
data BilpData

The BILP problem data.

 required

Returns:

Type Description
str

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

formulate(data: BilpData) -> Model staticmethod

Formulate the general BILP as an optimization model.

Parameters:

Name Type Description Default
data BilpData

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

 required

Returns:

Type Description
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:

Name Type Description Default
solution Solution

The solver's solution object.

 required
data BilpData

The problem data.

 required

Returns:

Type Description
BilpSolution

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

Raises:

Type Description
NoSolutionFoundError

If the solver did not return any solution.

Solution

Solution model for BILP use case.

BilpSolution

Bases: UcSolution

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

Attributes:

Name Type Description
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:

Name Type Description Default
data BilpData | 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.

 None
ax Axes | None

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

 None

Returns:

Type Description
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:

Type Description
NotImplementedError

Always raised.

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:

Name Type Description Default
max_runtime float

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

 3600
quiet bool

Suppress the SCIP solver output.

 True

Returns:

Type Description
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:

Type Description
ValueError

If max_runtime is not positive.