Plugins

Plugins are the per-step loop hook that runs first each step, before flows are computed. Use them to reroute vehicles, gate/close links, run dispatchers, or implement access policies. ReroutingPlugin is the minimal rerouting form. See Plugins.

Plugin

Plugin(state: NetworkState | None = None)

Base class for per-step simulation plugins (the loop's extension point).

Subclass and override :meth:run_step to inspect the live :class:NetworkState (self.state) and act on the simulation before the node models resolve flows for the same step. Actions take effect immediately; for example, mutating vehicle.route on any in-network vehicle reroutes it, because vehicles carry and follow their own route (see the module docstring).

Attributes:

Name	Type	Description
state		The network state view, or None until Network.compile wires it in.

Create a plugin.

Parameters:

Name	Type	Description	Default
state	NetworkState | None	Optional network state to read during run_step; normally left None and attached automatically by Network.compile.	None

start

start(time_step: float, total_time: float) -> None

Record timing parameters at the start of the simulation.

run_step

run_step(t: int) -> None

Run the plugin for step t (override in subclasses).

FunctionPlugin

FunctionPlugin(fn: Callable[[int, NetworkState], None], state: NetworkState | None = None)

Bases: Plugin

Adapter turning a plain function into a plugin.

Parameters:

Name	Type	Description	Default
fn	Callable[[int, NetworkState], None]	Callable invoked each step as fn(t, state); it may act on the simulation, e.g. mutate vehicle.route on any in-network vehicle to reroute it, or flip an external flag a routing cost reads.	required
state	NetworkState | None	The network state passed to fn. May be omitted (None); Network.compile wires in the compiled network's state.	None

run_step

run_step(t: int) -> None

Invoke the wrapped function as fn(t, state).

ReroutingPlugin

ReroutingPlugin(reroute: RerouteFn | None = None, state: NetworkState | None = None)

Bases: Plugin

The simplest routing plugin: return only the routes you want to change.

Each step you are handed a snapshot of every vehicle currently travelling on a real link — its location (current link), its destination, and the remaining real-link route — together with the read-only network state. You return a mapping {vehicle: new_real_link_route} containing only the vehicles whose route should change; every vehicle you omit keeps its current route.

Correctness of an update: the returned route is a list of real link ids that the vehicle should follow from its current link onward, starting with the link it is on now (that is exactly how :attr:VehicleView.route is presented, so "return the view's route with a different tail" is always valid). The plugin re-attaches the destination's access connector and resynchronises the vehicle's position pointer via :meth:NetworkState.set_route, so the vehicle continues seamlessly onto the new route at its next node. A route that does not start with the vehicle's current link is rejected (see set_route), which prevents silently stranding a vehicle.

Use it either by passing a reroute function or by subclassing and overriding :meth:reroute.

Create a rerouting plugin.

Parameters:

Name	Type	Description	Default
reroute	RerouteFn | None	Optional reroute(t, state, vehicles) -> {vehicle: route} callback. If omitted, override :meth:reroute in a subclass.	None
state	NetworkState | None	Network state; normally attached by Network.compile.	None

reroute

reroute(t: int, state: NetworkState, vehicles: list[VehicleView]) -> dict[Vehicle, list[int]]

Return {vehicle: new_real_link_route} for the vehicles to change.

Override in a subclass, or pass a reroute callable to the constructor.

run_step

run_step(t: int) -> None

Collect in-network vehicles, ask for route updates, and apply them.