Stateful strategic MILP API
Stateful multi-period strategic optimization.
This is a linearized mixed-integer formulation. Risk is the decision state; each treatment reduces risk immediately, and untreated risk grows between periods. The model is exact for that linear state definition and is independently replayed after the solve.
- class brushline.strategic.stateful.StatefulAction(*, segment_id: str, year: int, method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], cost: Annotated[float, Ge(ge=0)], hours: Annotated[float, Ge(ge=0)], risk_before: Annotated[float, Ge(ge=0), Le(le=0.95)], risk_after: Annotated[float, Ge(ge=0), Le(le=0.95)])[source]
Bases:
BaseModelOne selected segment-period treatment.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.stateful.StatefulConfig(*, risk_weight: Annotated[float, Ge(ge=0)] = 1.0, cost_weight: Annotated[float, Ge(ge=0)] = 0.0, hours_weight: Annotated[float, Ge(ge=0)] = 0.0, growth_per_year: Annotated[float, Ge(ge=0), Le(le=0.5)] = 0.03, max_mean_risk: Annotated[float | None, Ge(ge=0), Le(le=0.95)] = None, max_seconds: Annotated[float, Gt(gt=0)] = 60.0)[source]
Bases:
BaseModelObjective and state-growth settings.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.strategic.stateful.StatefulError[source]
Bases:
ValueErrorRaised when a stateful strategic instance cannot be solved.
- class brushline.strategic.stateful.StatefulMethod(*, method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], cost_per_ha: Annotated[float, Ge(ge=0)], hours_per_ha: Annotated[float, Ge(ge=0)], risk_reduction: Annotated[float, Ge(ge=0), Le(le=0.95)])[source]
Bases:
BaseModelOne treatment method and its linear state effect.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.stateful.StatefulPeriod(*, year: Annotated[int, Ge(ge=1900), Le(le=2200)], budget: Annotated[float, Ge(ge=0)], capacity_hours: Annotated[float, Ge(ge=0)])[source]
Bases:
BaseModelOne annual period and its constraints.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.stateful.StatefulPlan(*, schema_version: ~typing.Literal['brushline.stateful-strategic.v1'] = 'brushline.stateful-strategic.v1', instance_id: str, status: ~typing.Literal['optimal', 'feasible', 'infeasible'], solver_status: int, solver_message: str, solver: str, objective: float, total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], total_hours: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], mean_risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=0.95)], mean_service: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], actions: list[~brushline.strategic.stateful.StatefulAction], years: list[~brushline.strategic.stateful.StatefulYear], replay_ok: bool, search: dict[str, str | int | float | bool] = <factory>, created_utc: ~datetime.datetime)[source]
Bases:
BaseModelA solved and replayed stateful strategic plan.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.stateful.StatefulSegment(*, segment_id: Annotated[str, MinLen(min_length=1)], span_id: Annotated[str, MinLen(min_length=1)], length_m: Annotated[float, Gt(gt=0)], area_ha: Annotated[float, Gt(gt=0)], initial_risk: Annotated[float, Ge(ge=0), Le(le=0.95)])[source]
Bases:
BaseModelOne segment in the stateful problem.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.stateful.StatefulYear(*, year: int, cost: Annotated[float, Ge(ge=0)], hours: Annotated[float, Ge(ge=0)], risk: Annotated[float, Ge(ge=0), Le(le=0.95)], service: Annotated[float, Ge(ge=0), Le(le=1)], actions: Annotated[int, Ge(ge=0)])[source]
Bases:
BaseModelOne year’s results.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.strategic.stateful.build_stateful_plan(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], config: StatefulConfig | None = None, robust_factors: list[list[tuple[int, float, float, float]]] | None = None, chance_factors: list[list[tuple[int, float, float, float]]] | None = None, max_budget_violations: int | None = None, max_capacity_violations: int | None = None, created_utc: datetime | None = None) StatefulPlan[source]
Solve the linearized stateful strategic MILP and replay the result.
- Parameters:
instance_id (str) – Instance id.
segments (list of StatefulSegment) – Segments and initial risk.
methods (list of StatefulMethod) – Treatment methods.
periods (list of StatefulPeriod) – Annual budgets and capacity.
config (StatefulConfig, optional) – Objective weights and state growth.
robust_factors (list of list of tuple, optional) – Scenario paths for budget/capacity robustness. Each tuple is
(year, cost_factor, hours_factor, capacity_factor).chance_factors (list of list of tuple, optional) – Paths used for a sampled budget chance constraint. Each tuple is
(year, cost_factor, hours_factor, capacity_factor).max_budget_violations (int, optional) – Maximum number of chance paths allowed to exceed budget in each period.
max_capacity_violations (int, optional) – Maximum number of chance paths allowed to exceed capacity in each period.
created_utc (datetime, optional) – Creation time.
- Returns:
StatefulPlan – Selected actions, annual outcomes, and replay status.
- Raises:
StatefulError – If the instance is empty, duplicate, or infeasible.
- brushline.strategic.stateful.replay_stateful_choices(segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], config: StatefulConfig, selected: dict[tuple[int, int, int], bool]) tuple[list[StatefulAction], list[StatefulYear], float, float, float][source]
Replay the solved choices with the same linear state equations.