Scenario optimization API

Scenario-optimized versus fixed stateful plans.

The comparison re-solves the exact stateful MILP under sampled cost, productivity, and capacity assumptions, then measures the fixed-plan regret. It is a value-of-adaptivity experiment, not a stochastic dynamic program.

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

Bases: BaseModel

P10/P50/P90 band for a scenario metric.

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

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

exception brushline.strategic.scenario_optimization.ScenarioOptimizationError[source]

Bases: ValueError

Raised when scenario inputs are inconsistent.

class brushline.strategic.scenario_optimization.ScenarioOptimizationResult(*, schema_version: Literal['brushline.scenario-optimization.v1'] = 'brushline.scenario-optimization.v1', instance_id: str, scenarios: Annotated[int, Ge(ge=1)], seed: int, nominal_fixed_objective: float, mean_fixed_objective: float, mean_adaptive_objective: float, mean_regret: float, p90_regret: float, probability_adaptation_improves: Annotated[float, Ge(ge=0), Le(le=1)], fixed_budget_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], fixed_capacity_violation_probability: Annotated[float, Ge(ge=0), Le(le=1)], fixed_cost_band: ScenarioBand, adaptive_cost_band: ScenarioBand, fixed_hours_band: ScenarioBand, adaptive_hours_band: ScenarioBand, fixed_risk_band: ScenarioBand, adaptive_risk_band: ScenarioBand, outcomes: list[ScenarioOutcome], created_utc: datetime)[source]

Bases: BaseModel

Scenario-optimized planning summary.

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

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

class brushline.strategic.scenario_optimization.ScenarioOutcome(*, index: Annotated[int, Ge(ge=0)], cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)], fixed_cost: Annotated[float, Ge(ge=0)], fixed_hours: Annotated[float, Ge(ge=0)], fixed_budget_exceeded: Annotated[float, Ge(ge=0)], fixed_capacity_shortfall: Annotated[float, Ge(ge=0)], fixed_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], adaptive_cost: Annotated[float, Ge(ge=0)], adaptive_hours: Annotated[float, Ge(ge=0)], adaptive_risk: Annotated[float, Ge(ge=0), Le(le=0.95)], adaptive_status: Literal['optimal', 'feasible', 'infeasible'], fixed_objective: float, adaptive_objective: float, regret: float)[source]

Bases: BaseModel

Fixed versus adaptive outcomes in one scenario.

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

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

brushline.strategic.scenario_optimization.optimize_scenarios(*, instance_id: str, segments: list[StatefulSegment], methods: list[StatefulMethod], periods: list[StatefulPeriod], fixed: StatefulPlan, config: StatefulConfig | None = None, scenarios: int = 30, seed: int = 7, cost_sigma: float = 0.18, hours_sigma: float = 0.15, capacity_sigma: float = 0.15, max_seconds_per_solve: float = 60.0, created_utc: datetime | None = None) → ScenarioOptimizationResult[source]

Re-solve the exact stateful plan under sampled scenarios.

Parameters:
  • instance_id (str) – Instance id.

  • segments (list) – Nominal stateful problem.

  • methods (list) – Nominal stateful problem.

  • periods (list) – Nominal stateful problem.

  • fixed (StatefulPlan) – Fixed plan being tested.

  • config (StatefulConfig, optional) – Objective weights.

  • scenarios (int, optional) – Number of sampled scenarios.

  • 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 scenario.

  • created_utc (datetime, optional) – Creation time.

Returns:

ScenarioOptimizationResult – Fixed and adaptive outcomes, bands, and regret.

Raises:

ScenarioOptimizationError – If inputs are empty or a scenario cannot be solved.