Skip to content

Container Assignment API Reference

Data

Data model for Container Assignment use case.

Container

Bases: BaseModel

A single freight container with transport cost and route information.

Attributes:

  • name (str) –

    Identifier for this container.

  • barge_cost (float) –

    Cost of transporting this container by barge.

  • truck_cost (float) –

    Cost of transporting this container by truck.

  • routes (NumPyArray) –

    Binary indicator list. routes[j] == 1 if this container uses track j when shipped by barge.

ContainerAssignmentData

Bases: UcData

Data for the Container Assignment (CA) use case.

The Container Assignment Problem involves assigning freight containers to transportation modes to minimize costs while meeting delivery deadlines. This problem is critical in logistics for optimizing the use of multimodal transport networks, which include various transportation modes like trucks and barges.

Each container must be transported either by barge or by truck. Barges share tracks with limited capacity; if a track is full the container must go by truck. The formulation creates a QUBO matrix of size (N + M*K) x (N + M*K) with N containers, M tracks, and K slack variables per track. Instances can be constructed directly, via :meth:from_costs_and_routes, or from a list of :class:Container objects using :meth:from_containers.

Attributes:

  • name (Literal['container_assignment']) –

    Identifier for this data type.

  • barge_costs (NumPyArray) –

    Cost of transporting each container by barge.

  • truck_costs (NumPyArray) –

    Cost of transporting each container by truck.

  • track_capacities (dict[str, int]) –

    Mapping from track name to its barge capacity.

  • routes (NumPyArray) –

    Binary indicator matrix (containers x tracks). routes[i][j] == 1 if container i uses track j when shipped by barge.

  • container_names (list[str]) –

    Identifiers for each container. Auto-generated as Con_0, Con_1, etc. when not provided.

References

Transformation <https://arxiv.org/pdf/2007.01730>_

from_costs_and_routes(barge_costs: list[float], truck_costs: list[float], routes: np.ndarray | list[list[int]], track_capacities: dict[str, int] | list[int] | None = None, container_names: list[str] | None = None) -> ContainerAssignmentData classmethod

Create data from cost lists and a routes matrix.

Track names and capacities are auto-generated when not provided.

Parameters:

  • barge_costs (list[float]) –

    Cost of transporting each container by barge.

  • truck_costs (list[float]) –

    Cost of transporting each container by truck.

  • routes (ndarray | list[list[int]]) –

    Binary indicator matrix (containers x tracks).

  • track_capacities (dict[str, int] | list[int] | None, default: None ) –

    Track capacities. When a list is given, track names are auto-generated as track_0, track_1, etc. When None, each track capacity defaults to the number of containers.

  • container_names (list[str] | None, default: None ) –

    Identifiers for each container. Auto-generated when None.

Returns:

from_containers(containers: list[Container], track_capacities: dict[str, int] | list[int] | None = None) -> ContainerAssignmentData classmethod

Create data from a list of :class:Container objects.

Parameters:

  • containers (list[Container]) –

    Each container carries its own name, barge/truck cost, and route.

  • track_capacities (dict[str, int] | list[int] | None, default: None ) –

    Track capacities. When a list is given, track names are auto-generated as track_0, track_1, etc. When None, each track capacity defaults to the number of containers.

Returns:

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

Plot barge vs truck costs and track capacity constraints.

The left panel shows barge vs truck costs per container. The right panel shows, for each track, how many containers could use it (from the routes matrix) compared to the track capacity.

Parameters:

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

    Matplotlib axes to draw on. When None a new two-panel figure is created. When provided, only the cost panel is drawn on it.

Returns:

  • Axes –

    The axes with the cost plot (left panel).

to_string() -> str

Return a string describing the data.

generate_random(n_containers: int = 5, n_tracks: int = 3, seed: int | None = None) -> ContainerAssignmentData staticmethod

Generate a random Container Assignment instance.

Parameters:

  • n_containers (int, default: 5 ) –

    Number of containers, by default 5.

  • n_tracks (int, default: 3 ) –

    Number of tracks, by default 3.

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

    Random seed for reproducibility, by default None.

Returns:

Formulation

Formulation for Container Assignment use case.

ContainerAssignmentFormulation

Bases: UcFormulation[ContainerAssignmentData, ContainerAssignmentSolution]

Constraint-based formulation for Container Assignment.

Mathematical Formulation

Decision Variables: x[i] binary -- 1 if container i uses truck, 0 for barge

Objective: minimize sum_i truck_costs[i]x[i] + barge_costs[i](1-x[i]) = minimize sum_i (truck_costs[i] - barge_costs[i])*x[i] + const

Constraints: For each track j: sum_i routes[i][j] * (1 - x[i]) <= capacity[j] i.e. barge containers using track j must not exceed capacity

to_string(data: ContainerAssignmentData) -> str staticmethod

Return a string describing the formulation.

formulate(data: ContainerAssignmentData) -> Model staticmethod

Formulate the Container Assignment problem.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: ContainerAssignmentData) -> ContainerAssignmentSolution staticmethod

Extract solution from solver result.

Parameters:

Returns:

Solution

Solution model for Container Assignment use case.

ContainerAssignmentSolution

Bases: UcSolution

Solution for the Container Assignment (CA) use case.

Attributes:

  • name (Literal['container_assignment']) –

    Identifier for this solution type.

  • truck_containers (NumPyArray) –

    Indices of containers assigned to trucks.

  • barge_containers (NumPyArray) –

    Indices of containers assigned to barges.

  • total_cost (float) –

    Total transportation cost.

  • is_valid (bool) –

    Whether the solution satisfies all constraints.

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

Plot the assignment result with cost breakdown and track utilization.

The left panel shows two stacked bars (Barge / Truck) with each container's cost contribution. The right panel shows, for every track, how many barge containers actually use it compared to the track capacity, making it clear where the capacity constraint is binding.

Parameters:

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

    Problem data used to look up per-container costs and names.

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

    Matplotlib axes to draw on. When None a new two-panel figure is created. When provided, only the cost panel is drawn on it.

Returns:

  • Axes –

    The axes with the cost plot (left panel).

to_string() -> str

Return a string describing the solution.

Instance

Instance model for ContainerAssignment use case.

ContainerAssignmentInstance

Bases: UcInstance[ContainerAssignmentData, ContainerAssignmentFormulation, ContainerAssignmentSolution]

Instance combining data and formulation for ContainerAssignment.

Collection

Collection of Container Assignment instances.

ContainerAssignmentCollection

Bases: UcInstanceCollection[ContainerAssignmentInstance]

Collection of Container Assignment instances.

from_random(min_containers: int, max_containers: int, n_tracks: int = 3, num_instances: int = 1, *, seed: int | None = None) -> ContainerAssignmentCollection classmethod

Generate random Container Assignment instances.

Parameters:

  • min_containers (int) –

    Minimum number of containers.

  • max_containers (int) –

    Maximum number of containers.

  • n_tracks (int, default: 3 ) –

    Number of tracks, by default 3.

  • num_instances (int, default: 1 ) –

    Number of instances per container count, by default 1.

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

    Random seed for reproducibility, by default None.

Returns: