Traffic Flow API Reference
Data
Data model for Traffic Flow use case.
TrafficFlowData
Bases: UcData
Data for the Traffic Flow (TF) use case.
Each car has several possible routes through a road network. The goal is to choose one route per car so that total congestion (sum of squared loads on every road segment) is minimised.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['traffic_flow']
|
Identifier for this data type. |
car_routes |
list[list[list[int]]]
|
|
plot(*, ax: Axes | None = None) -> Axes
Plot the route structure for each car.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Matplotlib axes to draw on. Creates a new figure if |
None
|
Returns:
| Type | Description |
|---|---|
Axes
|
The axes with the plot. |
to_string() -> str
Return a string describing the data.
from_values(car_routes: list[list[list[int]]]) -> TrafficFlowData
staticmethod
Create a TrafficFlowData instance from explicit values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
car_routes
|
list[list[list[int]]]
|
|
required |
Returns:
| Type | Description |
|---|---|
TrafficFlowData
|
A TrafficFlowData instance with the given values. |
generate_random(n_cars: int = 3, n_routes_per_car: int = 2, n_segments: int = 5, seed: int | None = None) -> TrafficFlowData
staticmethod
Generate a random Traffic Flow instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_cars
|
int
|
Number of cars, by default 3. |
3
|
n_routes_per_car
|
int
|
Number of route options per car, by default 2. |
2
|
n_segments
|
int
|
Total number of road segments, by default 5. |
5
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
Returns:
| Type | Description |
|---|---|
TrafficFlowData
|
A randomly generated instance. |
Formulation
Formulation for Traffic Flow use case.
TrafficFlowFormulation
Bases: UcFormulation[TrafficFlowData, TrafficFlowSolution]
Constraint-based formulation for Traffic Flow.
Mathematical Formulation
Notation:
c -- car index
r -- route index for car c
s -- road segment index
load_s -- number of cars using segment s
Decision Variables:
y[c,r] in {0,1} -- 1 if car c takes route r, 0 otherwise
Objective:
minimize sum_s load_s^2
where load_s = sum_{(c,r) using s} y[c,r]
Minimizing the sum of squared loads distributes traffic evenly
across segments and penalizes heavily used segments more strongly.
Constraints:
Each car takes exactly one route:
sum_r y[c,r] == 1 for all c
to_string(data: TrafficFlowData) -> str
staticmethod
Return a string describing the formulation.
formulate(data: TrafficFlowData) -> Model
staticmethod
Formulate the Traffic Flow problem.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
TrafficFlowData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
Model
|
A LunaModel ready to be solved. |
interpret(solution: Solution, data: TrafficFlowData) -> TrafficFlowSolution
staticmethod
Extract solution from solver result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solution
|
Solution
|
The solver solution. |
required |
data
|
TrafficFlowData
|
The problem data. |
required |
Returns:
| Type | Description |
|---|---|
TrafficFlowSolution
|
Structured solution with route selections and metrics. |
Solution
Solution model for Traffic Flow use case.
TrafficFlowSolution
Bases: UcSolution
Solution for the Traffic Flow (TF) use case.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
Literal['traffic_flow']
|
Identifier for this solution type. |
selected_routes |
NumPyArray
|
1D arraya with route index chosen for each car. |
total_congestion |
int
|
Total congestion (sum of squared segment loads). |
is_valid |
bool
|
Whether the solution satisfies all constraints. |
plot(data: TrafficFlowData | None = None, *, ax: Axes | None = None) -> Axes
Plot the selected routes per car with congestion visualization.
to_string() -> str
Return a string describing the solution.
Instance
Instance model for TrafficFlow use case.
TrafficFlowInstance
Bases: UcInstance[TrafficFlowData, TrafficFlowFormulation, TrafficFlowSolution]
Instance combining data and formulation for TrafficFlow.
Collection
Collection of Traffic Flow instances.
TrafficFlowCollection
Bases: UcInstanceCollection[TrafficFlowInstance]
Collection of Traffic Flow instances.
from_random(min_cars: int | None = None, max_cars: int | None = None, n_routes_per_car: int = 2, n_segments: int = 5, num_instances: int = 1, *, sizes: Sequence[int] | None = None, seed: int | None = None) -> TrafficFlowCollection
classmethod
Generate random Traffic Flow instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_cars
|
int | None
|
Minimum number of cars. |
None
|
max_cars
|
int | None
|
Maximum number of cars. |
None
|
n_routes_per_car
|
int
|
Routes per car, by default 2. |
2
|
n_segments
|
int
|
Total road segments, by default 5. |
5
|
num_instances
|
int
|
Number of instances per car count, by default 1. |
1
|
seed
|
int | None
|
Random seed for reproducibility, by default None. |
None
|
sizes
|
Sequence[int] | None
|
Explicit sizes to generate, e.g. |
None
|
Returns:
| Type | Description |
|---|---|
TrafficFlowCollection
|
Collection containing generated instances. |
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: |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |