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 | Type | Description |
|---|---|---|
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. |
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 | Type | Description |
|---|---|---|
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).
|
container_names |
list[str]
|
Identifiers for each container. Auto-generated as |
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:
| Name | Type | Description | Default |
|---|---|---|---|
barge_costs
|
list[float]
|
Cost of transporting each container by barge. |
required |
truck_costs
|
list[float]
|
Cost of transporting each container by truck. |
required |
routes
|
ndarray | list[list[int]]
|
Binary indicator matrix (containers x tracks). |
required |
track_capacities
|
dict[str, int] | list[int] | None
|
Track capacities. When a |
None
|
container_names
|
list[str] | None
|
Identifiers for each container. Auto-generated when |
None
|
Returns:
| Type | Description |
|---|---|
ContainerAssignmentData
|
A new data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
containers
|
list[Container]
|
Each container carries its own name, barge/truck cost, and route. |
required |
track_capacities
|
dict[str, int] | list[int] | None
|
Track capacities. When a |
None
|
Returns:
| Type | Description |
|---|---|
ContainerAssignmentData
|
A new data instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. When |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
n_containers
|
int
|
Number of containers, by default 5. |
5
|
n_tracks
|
int
|
Number of tracks, by default 3. |
3
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
ContainerAssignmentData
|
A randomly generated instance. |
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ContainerAssignmentData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A Luna Model ready to be solved. |
interpret(solution: Solution, data: ContainerAssignmentData) -> ContainerAssignmentSolution
staticmethod
Extract solution from solver result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The solver solution. |
required |
data
|
ContainerAssignmentData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
ContainerAssignmentSolution
|
Structured solution with assignments and metrics. |
Solution
Solution model for Container Assignment use case.
ContainerAssignmentSolution
Bases: UcSolution
Solution for the Container Assignment (CA) use case.
Attributes:
| Name | Type | Description |
|---|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
ContainerAssignmentData | None
|
Problem data used to look up per-container costs and names. |
None
|
ax
|
Axes | None
|
Matplotlib axes to draw on. When |
None
|
Returns:
| Type | Description |
|---|---|
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:
| Name | Type | Description | Default |
|---|---|---|---|
min_containers
|
int
|
Minimum number of containers. |
required |
max_containers
|
int
|
Maximum number of containers. |
required |
n_tracks
|
int
|
Number of tracks, by default 3. |
3
|
num_instances
|
int
|
Number of instances per container count, by default 1. |
1
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
ContainerAssignmentCollection
|
Collection containing generated instances. |