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

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

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

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

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

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

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

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

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