Uncertainty API

Execution uncertainty around a fixed tactical plan.

The sampler varies treatment cost, productive hours, and contractor capacity around a fixed plan. It does not re-optimize the plan per sample; this is execution sensitivity, not a full adaptive stochastic program.

class brushline.strategic.uncertainty.SensitivityCase(*, name: str, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)], total_cost: Annotated[float, Ge(ge=0)], total_hours: Annotated[float, Ge(ge=0)], budget_exceeded: Annotated[float, Ge(ge=0)], capacity_shortfall_hours: Annotated[float, Ge(ge=0)], contractor_shortfall_hours: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

One deterministic one-at-a-time sensitivity case.

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

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

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

Bases: BaseModel

P10/P50/P90 band for one metric.

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

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

class brushline.strategic.uncertainty.UncertaintyConfig(*, samples: Annotated[int, Ge(ge=1), Le(le=10000)] = 500, seed: int = 7, cost_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.18, hours_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.15, capacity_sigma: Annotated[float, Ge(ge=0), Le(le=1)] = 0.15)[source]

Bases: BaseModel

Distribution settings for the execution sampler.

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

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

exception brushline.strategic.uncertainty.UncertaintyError[source]

Bases: ValueError

Raised when uncertainty inputs are inconsistent.

class brushline.strategic.uncertainty.UncertaintyResult(*, schema_version: Literal['brushline.uncertainty.v1'] = 'brushline.uncertainty.v1', instance_id: str, samples: Annotated[int, Ge(ge=1)], seed: int, annual_budget: Annotated[float, Ge(ge=0)], annual_capacity_hours: Annotated[float, Ge(ge=0)], baseline_cost: Annotated[float, Ge(ge=0)], baseline_hours: Annotated[float, Ge(ge=0)], cost_band: UncertaintyBand, hours_band: UncertaintyBand, budget_exceeded_band: UncertaintyBand, capacity_shortfall_band: UncertaintyBand, contractor_shortfall_band: UncertaintyBand, probability_budget_exceeded: Annotated[float, Ge(ge=0), Le(le=1)], probability_capacity_shortfall: Annotated[float, Ge(ge=0), Le(le=1)], probability_contractor_shortfall: Annotated[float, Ge(ge=0), Le(le=1)], sensitivity: list[SensitivityCase], samples_detail: list[UncertaintySample], created_utc: datetime)[source]

Bases: BaseModel

Sampled execution bands and deterministic sensitivities.

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

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

class brushline.strategic.uncertainty.UncertaintySample(*, cost_factor: Annotated[float, Gt(gt=0)], hours_factor: Annotated[float, Gt(gt=0)], capacity_factor: Annotated[float, Gt(gt=0)], total_cost: Annotated[float, Ge(ge=0)], total_hours: Annotated[float, Ge(ge=0)], budget_exceeded: Annotated[float, Ge(ge=0)], capacity_shortfall_hours: Annotated[float, Ge(ge=0)], contractor_shortfall_hours: Annotated[float, Ge(ge=0)])[source]

Bases: BaseModel

One sampled execution outcome.

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

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

brushline.strategic.uncertainty.evaluate_uncertainty(*, instance_id: str, actions: list[TacticalAction], periods: list[StatefulPeriod], profiles: list[ContractorProfile], config: UncertaintyConfig | None = None, created_utc: datetime | None = None) → UncertaintyResult[source]

Sample cost, hours, and contractor capacity around a fixed plan.

Parameters:
  • instance_id (str) – Instance id.

  • actions (list of TacticalAction) – Fixed tactical plan.

  • periods (list of StatefulPeriod) – Annual budgets and crew-hour capacities.

  • profiles (list of ContractorProfile) – Contractor capacities.

  • config (UncertaintyConfig, optional) – Sampler settings.

  • created_utc (datetime, optional) – Creation time.

Returns:

UncertaintyResult – Percentile bands, shortfall probabilities, and one-at-a-time sensitivities.