Skip to content

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 (Literal['traffic_flow']) –

    Identifier for this data type.

  • car_routes (list[list[list[int]]]) –

    car_routes[c][r] is a list of segment IDs used by route r of car c.

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

Plot the route structure for each car.

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 data.

from_values(car_routes: list[list[list[int]]]) -> TrafficFlowData staticmethod

Create a TrafficFlowData instance from explicit values.

Parameters:

  • car_routes (list[list[list[int]]]) –

    car_routes[c][r] is a list of segment IDs used by route r of car c.

Returns:

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:

  • n_cars (int, default: 3 ) –

    Number of cars, by default 3.

  • n_routes_per_car (int, default: 2 ) –

    Number of route options per car, by default 2.

  • n_segments (int, default: 5 ) –

    Total number of road segments, by default 5.

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

    Random seed for reproducibility, by default None.

Returns:

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:

Returns:

  • Model –

    A Luna Model ready to be solved.

interpret(solution: Solution, data: TrafficFlowData) -> TrafficFlowSolution staticmethod

Extract solution from solver result.

Parameters:

  • solution (Solution) –

    The solver solution.

  • data (TrafficFlowData) –

    The problem data.

Returns:

Solution

Solution model for Traffic Flow use case.

TrafficFlowSolution

Bases: UcSolution

Solution for the Traffic Flow (TF) use case.

Attributes:

  • 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:

  • min_cars (int) –

    Minimum number of cars.

  • max_cars (int) –

    Maximum number of cars.

  • n_routes_per_car (int, default: 2 ) –

    Routes per car, by default 2.

  • n_segments (int, default: 5 ) –

    Total road segments, by default 5.

  • num_instances (int, default: 1 ) –

    Number of instances per car count, by default 1.

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

    Random seed for reproducibility, by default None.

Returns: