Stateful coordination API
Lagrangian budget and crew-hour coordination across spatial clusters.
Cluster subproblems remove the annual budget and crew-hour constraints and add non-negative shadow prices to their objectives. Subgradient updates raise or lower those prices. The maximum priced-cluster minimum is a lower bound for the original clustered problem.
- exception brushline.strategic.coordination.CoordinationError[source]
Bases:
ValueErrorRaised when coordination inputs or prices are invalid.
- class brushline.strategic.coordination.CoordinationResult(*, schema_version: Literal['brushline.stateful-coordination.v1'] = 'brushline.stateful-coordination.v1', instance_id: str, cluster_count: Annotated[int, Ge(ge=1)], max_segments_per_cluster: Annotated[int, Ge(ge=1)], baseline_objective: float, dual_bound: float, absolute_gap: float, relative_gap: float, iterations: Annotated[list[PriceIteration], MinLen(min_length=1)], best_iteration: Annotated[int, Ge(ge=0)], best_cost_price: Annotated[float, Ge(ge=0)], best_hours_price: Annotated[float, Ge(ge=0)], created_utc: datetime)[source]
Bases:
BaseModelLagrangian coordination evidence.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.coordination.PriceIteration(*, iteration: Annotated[int, Ge(ge=0)], cost_price: Annotated[float, Ge(ge=0)], hours_price: Annotated[float, Ge(ge=0)], dual_bound: float, spend: Annotated[float, Ge(ge=0)], hours: Annotated[float, Ge(ge=0)], cluster_seconds: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne Lagrangian price iteration.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.strategic.coordination.coordinate_stateful(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], baseline: StatefulPlan, max_segments_per_cluster: int = 150, iterations: int = 12, initial_step: float = 0.5, max_seconds_per_cluster: float = 30.0, created_utc: datetime | None = None) CoordinationResult[source]
Run a Lagrangian subgradient bound for the clustered stateful problem.
- Parameters:
instance_id (str) – Instance id.
segments (list) – Full stateful problem.
methods (list) – Full stateful problem.
periods (list) – Full stateful problem.
baseline (StatefulPlan) – Feasible primal plan used for the gap.
max_segments_per_cluster (int, optional) – Maximum cluster size.
iterations (int, optional) – Number of subgradient iterations.
initial_step (float, optional) – Initial price step.
max_seconds_per_cluster (float, optional) – Exact MILP limit per cluster per iteration.
created_utc (datetime, optional) – Creation time.
- Returns:
CoordinationResult – Iteration prices and the best dual lower bound.
- Raises:
CoordinationError – If inputs are invalid or no priced subproblem can be solved.