Skip to content

Bin Packing Problem (BPP) API Reference

Data

Data model for Bpp use case.

BppData

Bases: UcData

Data for the Bin Packing Problem (BPP) use case.

This class encapsulates all necessary information to define and solve a BPP instance. The BPP is a classic optimization problem where the goal is to pack all items into the minimum number of bins while respecting capacity constraints.

The Bin Packing Problem is NP-hard and highly relevant for logistics, resource allocation, and various industrial applications such as container loading, memory allocation, and cutting stock problems.

Attributes:

  • name (Literal['bin_packing_problem']) –

    A constant identifier for this data type, always set to "bin_packing_problem". Used for registration and type identification in the use case registry.

  • item_weights (NumPyArray) –

    A 1D NumPy array containing the weight of each item to be packed. The length of this array determines the number of items. Example: np.array([4.5, 2.3, 6.1, 3.8])

  • bin_capacity (float) –

    The maximum capacity of each bin. All bins have the same capacity. Example: 10.0

  • item_names ((list[str | int] | None, optional)) –

    Optional list of item identifiers (strings or integers) for better readability and tracking. If None, items will be identified by their index. Example: ["item_A", "item_B", "item_C"] or [0, 1, 2]

Examples:

Create a simple 4-item BPP instance:

>>> bpp = BppData(
...     name="bin_packing_problem",
...     item_weights=np.array([4.5, 2.3, 6.1, 3.8]),
...     bin_capacity=10.0,
...     item_names=["A", "B", "C", "D"],
... )

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

Plot item weights as a horizontal bar chart.

Parameters:

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

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

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the BPP data.

from_weights(item_weights: np.ndarray, bin_capacity: float, item_names: list[str | int] | None = None) -> BppData staticmethod

Create BppData from item weights and bin capacity.

generate_random(n_items: int, bin_capacity: float, weight_max: float | None = None, *, seed: int | None = None) -> BppData staticmethod

Generate a random BPP instance.

Parameters:

  • n_items (int) –

    Number of items.

  • bin_capacity (float) –

    Capacity of each bin.

  • weight_max (float | None, default: None ) –

    Maximum item weight. Defaults to bin_capacity.

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

    Random seed.

Returns:

  • BppData –

    Randomly generated instance.

Formulation

Formulation for Bpp use case.

BppFormulation

Bases: UcFormulation[BppData, BppSolution]

Constraint-based formulation for the Bin Packing Problem (BPP).

This class provides the mathematical formulation to solve BPP using optimization. The formulation uses binary variables to represent item-to-bin assignments and minimizes the number of bins used.

Mathematical Formulation

Decision Variables: x_ij ∈ {0,1}: 1 if item i is packed in bin j, 0 otherwise y_j ∈ {0,1}: 1 if bin j is used, 0 otherwise

Objective: minimize Σ_j y_j (minimize the number of bins used)

Constraints: 1. Each item in exactly one bin: Σ_j x_ij = 1 ∀i 2. Capacity constraint: Σ_i (weight_i * x_ij) ≤ capacity * y_j ∀j 3. Bin usage linking: y_j ≥ x_ij ∀i,j

to_string(data: BppData) -> str staticmethod

Return a string describing the formulation.

formulate(data: BppData) -> Model staticmethod

Formulate the Bin Packing Problem as a constraint-based model.

Creates a formulation for the Bin Packing Problem where we minimize the number of bins used while ensuring all items are packed and capacity constraints are satisfied.

Parameters:

  • data (BppData) –

    The BPP instance data containing item weights and bin capacity.

Returns:

  • Model –

    An optimization model ready to be solved.

interpret(solution: Solution, data: BppData) -> BppSolution staticmethod

Interpret the solution.

Extracts the bin assignments from the solution and computes solution metrics like number of bins used, bin loads, and validity.

Parameters:

  • solution (Solution) –

    The solution containing variable assignments.

  • data (BppData) –

    The original BPP instance data.

Returns:

  • BppSolution –

    A structured solution object with bin assignments and metrics.

Solution

Solution model for Bpp use case.

BppSolution

Bases: UcSolution

Solution for the Bin Packing Problem (BPP) use case.

This class represents a solution to a BPP instance, containing the assignment of items to bins and metrics about the solution quality.

Attributes:

  • name (Literal['bin_packing_problem']) –

    A constant identifier for this solution type, always set to "bin_packing_problem".

  • bin_assignments (list[list[str | int]]) –

    A list of bins, where each bin is represented as a list of item identifiers (names or indices) that are packed into that bin. Example: [["item_A", "item_B"], ["item_C"], ["item_D", "item_E"]] represents 3 bins with different items.

  • num_bins_used (int) –

    The total number of bins used in this solution. This is also the objective value that we want to minimize.

  • bin_loads (list[float]) –

    The total weight in each bin. Useful for verifying that capacity constraints are satisfied. Example: [6.8, 6.1, 8.3] for the bin assignments above.

  • is_valid (bool) –

    Whether the solution satisfies all constraints: - All items are assigned to exactly one bin - No bin exceeds its capacity - All bins have at least one item (no empty bins)

Examples:

A valid solution for 5 items packed into 3 bins:

>>> solution = BppSolution(
...     name="bin_packing_problem",
...     bin_assignments=[["A", "B"], ["C"], ["D", "E"]],
...     num_bins_used=3,
...     bin_loads=[6.8, 6.1, 8.3],
...     is_valid=True,
... )

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

Plot the bin packing solution as a stacked horizontal bar chart.

Parameters:

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

    Problem data. When provided, bar widths reflect item weights and a capacity line is drawn.

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

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

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the solution.

Instance

Instance model for Bpp use case.

BppInstance

Bases: UcInstance[BppData, BppFormulation, BppSolution]

Instance combining data and formulation for Bpp.

Collection

Collection of Bpp instances.

BppCollection

Bases: UcInstanceCollection[BppInstance]

Collection of Bpp instances.

from_random(min_num_items: int, max_num_items: int, bin_capacity: float = 10.0, num_instances: int = 1, *, seed: int | None = None) -> BppCollection classmethod

Generate random bin packing instances.

Parameters:

  • min_num_items (int) –

    Minimum number of items.

  • max_num_items (int) –

    Maximum number of items.

  • bin_capacity (float, default: 10.0 ) –

    Bin capacity for all instances.

  • num_instances (int, default: 1 ) –

    Instances per size.

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

    Random seed.

Returns: