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

Raised 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: BaseModel

Lagrangian 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: BaseModel

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