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

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

    Minimum number of cars.

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

    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.

  • sizes (Sequence[int] | None, default: None ) –

    Explicit sizes to generate, e.g. [10, 50, 100], instead of a range. Mutually exclusive with min_cars/max_cars, by default None.

Returns:

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:

  • max_runtime (float, default: 3600 ) –

    SCIP time limit per instance in seconds. Must be positive. Defaults to 3600 seconds.

  • quiet (bool, default: True ) –

    Suppress the SCIP solver output.

Returns:

  • list[bool] –

    Feasibility mask over the instances as they were before filtering, in that order: True where the instance was kept, False where it was removed.

Raises: