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:
BaseModelOne 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:
BaseModelA 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:
ValueErrorRaised 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.