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 Luna Model 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, max_cars: int, n_routes_per_car: int = 2, n_segments: int = 5, num_instances: int = 1, *, seed: int | None = None) -> TrafficFlowCollection
classmethod
Generate random Traffic Flow instances.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
min_cars
|
int
|
Minimum number of cars. |
required |
max_cars
|
int
|
Maximum number of cars. |
required |
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
|
Returns:
| Type | Description |
|---|---|
TrafficFlowCollection
|
Collection containing generated instances. |