Stateful decomposition API

Spatial cluster decomposition for large stateful strategic problems.

The decomposition allocates each annual budget and crew-hour capacity across connected segment clusters, solves each cluster with the exact stateful MILP, and replays the aggregate plan. It is a feasible spatial decomposition, not a proof of global optimality.

class brushline.strategic.decomposition.ClusterResult(*, cluster_id: str, segment_ids: Annotated[list[str], MinLen(min_length=1)], budget_total: Annotated[float, Ge(ge=0)], capacity_total: Annotated[float, Ge(ge=0)], status: Literal['optimal', 'feasible', 'infeasible'], objective: float | None, total_cost: Annotated[float, Ge(ge=0)], total_hours: Annotated[float, Ge(ge=0)], mean_risk: float | None, seconds: Annotated[float, Ge(ge=0)], actions: Annotated[int, Ge(ge=0)])[source]

Bases: BaseModel

One solved spatial cluster.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class brushline.strategic.decomposition.DecomposedPlan(*, schema_version: Literal['brushline.stateful-decomposition.v1'] = 'brushline.stateful-decomposition.v1', instance_id: str, cluster_count: Annotated[int, Ge(ge=1)], max_segments_per_cluster: Annotated[int, Ge(ge=1)], plan: StatefulPlan, clusters: Annotated[list[ClusterResult], MinLen(min_length=1)], gap_to_baseline: float | None, created_utc: datetime)[source]

Bases: BaseModel

A replayed aggregate plan assembled from independently solved clusters.

model_config = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception brushline.strategic.decomposition.DecompositionError[source]

Bases: ValueError

Raised when cluster inputs are inconsistent.

brushline.strategic.decomposition.decompose_stateful(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], config: StatefulConfig | None = None, max_segments_per_cluster: int = 150, baseline: StatefulPlan | None = None, created_utc: datetime | None = None) → DecomposedPlan[source]

Solve cluster MILPs under risk-weighted annual budget allocations.

Parameters:
  • instance_id (str) – Instance id.

  • segments (list) – Full stateful problem.

  • methods (list) – Full stateful problem.

  • periods (list) – Full stateful problem.

  • config (StatefulConfig, optional) – Objective and state settings.

  • max_segments_per_cluster (int, optional) – Maximum segments per exact cluster MILP.

  • baseline (StatefulPlan, optional) – Heuristic or other baseline for gap reporting.

  • created_utc (datetime, optional) – Creation time.

Returns:

DecomposedPlan – Cluster results and the replayed aggregate plan.

Raises:

DecompositionError – If the instance is empty or no cluster can be solved.

brushline.strategic.decomposition.repair_stateful_clusters(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], baseline: StatefulPlan, config: StatefulConfig | None = None, max_segments_per_cluster: int = 150, created_utc: datetime | None = None) → DecomposedPlan[source]

Repair a baseline plan one budget-preserving spatial cluster at a time.

Each cluster receives exactly the annual budget and crew-hours consumed by the baseline in that cluster, then is solved with the exact stateful MILP. The baseline remains the fallback if a cluster solve fails. This is fix-and-optimize; it does not reallocate the global budget.