Rolling policy API

Rolling-horizon policy simulation for the stateful network plan.

The policy observes the current year’s cost, productivity, and capacity factors, assumes those conditions persist over the remaining horizon, re-solves the stateful MILP, and commits only the current year’s actions. Annual factors are independent across years. This is an executable persistence-forecast heuristic, not a stochastic dynamic program or a hindsight optimum.

class brushline.strategic.rolling_policy.AnnualFactors(*, year: int, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)])[source]

Bases: BaseModel

One year’s observed conditions.

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

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

class brushline.strategic.rolling_policy.RollingAction(*, segment_id: str, unit_id: str, method: str, 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 committed segment treatment in a rolling-policy year.

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

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

class brushline.strategic.rolling_policy.RollingBand(*, p10: float, p50: float, p90: float, mean: float)[source]

Bases: BaseModel

P10/P50/P90 band for a rolling-policy metric.

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

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

class brushline.strategic.rolling_policy.RollingEpisode(*, index: Annotated[int, Ge(ge=0)], factors: list[AnnualFactors], fixed_cost: Annotated[float, Ge(ge=0)], fixed_hours: Annotated[float, Ge(ge=0)], fixed_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], fixed_budget_exceeded: Annotated[float, Ge(ge=0)], fixed_capacity_shortfall: Annotated[float, Ge(ge=0)], fixed_objective: float, rolling_cost: Annotated[float, Ge(ge=0)], rolling_hours: Annotated[float, Ge(ge=0)], rolling_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], rolling_budget_exceeded: Annotated[float, Ge(ge=0)], rolling_capacity_shortfall: Annotated[float, Ge(ge=0)], rolling_objective: float, regret: float, years: list[RollingYear])[source]

Bases: BaseModel

Fixed versus rolling-policy outcomes for one annual-factor episode.

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

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

exception brushline.strategic.rolling_policy.RollingPolicyError[source]

Bases: ValueError

Raised when a rolling-policy simulation cannot proceed.

class brushline.strategic.rolling_policy.RollingPolicyResult(*, schema_version: Literal['brushline.rolling-policy.v1'] = 'brushline.rolling-policy.v1', instance_id: str, policy: Literal['persistence-forecast-v1'] = 'persistence-forecast-v1', solver: Literal['exact', 'heuristic'], lookahead_years: Annotated[int, Ge(ge=1)], episodes: Annotated[int, Ge(ge=1)], seed: int, total_budget: Annotated[float, Ge(ge=0)], total_capacity_hours: Annotated[float, Ge(ge=0)], mean_fixed_objective: float, mean_rolling_objective: float, mean_regret: float, p90_regret: float, probability_rolling_improves: Annotated[float, Ge(ge=0), Le(le=1)], fixed_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], rolling_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], fixed_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], rolling_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], fixed_cost_band: RollingBand, rolling_cost_band: RollingBand, fixed_hours_band: RollingBand, rolling_hours_band: RollingBand, fixed_risk_band: RollingBand, rolling_risk_band: RollingBand, episodes_detail: list[RollingEpisode], created_utc: datetime)[source]

Bases: BaseModel

Summary of a rolling-horizon policy experiment.

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

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

class brushline.strategic.rolling_policy.RollingYear(*, year: int, actions: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)], action_details: list[~brushline.strategic.rolling_policy.RollingAction] = <factory>, cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], hours: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=0.95)], budget_exceeded: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], capacity_shortfall: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], status: ~typing.Literal['optimal', 'feasible', 'infeasible'])[source]

Bases: BaseModel

One committed year in a rolling-policy episode.

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

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

brushline.strategic.rolling_policy.simulate_rolling_policy(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], fixed: StatefulPlan, config: StatefulConfig | None = None, episodes: int = 30, lookahead_years: int | None = None, solver: Literal['exact', 'heuristic'] = 'exact', heuristic_iterations: int = 100, seed: int = 7, cost_sigma: float = 0.18, hours_sigma: float = 0.15, capacity_sigma: float = 0.15, max_seconds_per_solve: float = 30.0, created_utc: datetime | None = None) → RollingPolicyResult[source]

Simulate a persistence-forecast rolling-horizon policy.

At each year the policy sees that year’s multiplicative factors, assumes they persist over the remaining horizon, re-solves the stateful MILP, and commits only that year’s actions. It does not observe future annual factors.

Parameters:
  • instance_id (str) – Instance id.

  • segments (list) – Nominal stateful problem.

  • methods (list) – Nominal stateful problem.

  • periods (list) – Nominal stateful problem.

  • fixed (StatefulPlan) – Fixed nominal plan used as the comparison policy.

  • config (StatefulConfig, optional) – Objective weights and growth.

  • episodes (int, optional) – Number of simulated annual-factor episodes.

  • lookahead_years (int, optional) – Number of years in each re-solve. The current year is always committed; the default solves the remaining horizon. A shorter window is faster and more myopic.

  • solver ({"exact", "heuristic"}, optional) – Use the exact MILP or the Fresh Solutions feasible heuristic for each annual re-solve.

  • heuristic_iterations (int, optional) – Local-search iterations when solver="heuristic".

  • seed (int, optional) – Deterministic sampler seed.

  • cost_sigma (float, optional) – Lognormal sigmas.

  • hours_sigma (float, optional) – Lognormal sigmas.

  • capacity_sigma (float, optional) – Lognormal sigmas.

  • max_seconds_per_solve (float, optional) – MILP limit per annual re-solve.

  • created_utc (datetime, optional) – Creation time.

Returns:

RollingPolicyResult – Fixed and rolling outcomes, bands, and regret.

Raises:

RollingPolicyError – If inputs are empty, an episode fails to solve, or an annual solve is infeasible.