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:
BaseModelOne 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:
BaseModelOne 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:
BaseModelP10/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:
BaseModelFixed 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:
ValueErrorRaised 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:
BaseModelSummary 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:
BaseModelOne 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.