brushline.strategic.portfolio
The strategic option, segment, period, constraint, period-summary, and portfolio models plus the deterministic builder.
Strategic network portfolio selection.
The portfolio chooses at most one strategic option for each segment and period under period budgets, method capacities, a service-level target, a risk target, and a spatial-continuity preference. It uses a deterministic service-repair pass followed by budget-preserving improvement and local swaps.
- class brushline.strategic.portfolio.PeriodSummary(*, period_id: str, cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], capacity_used: dict[str, float] = <factory>, service_attainment: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], selected_count: ~typing.Annotated[int, ~annotated_types.Ge(ge=0)])[source]
Bases:
BaseModelOne period’s portfolio totals.
- Parameters:
period_id (str) – Period.
cost (float) – Selected cost.
budget (float) – Period budget.
capacity_used (dict of str to float) – Capacity used by method.
service_attainment (float) – Length-weighted service.
risk (float) – Length-weighted risk.
uncertainty (float) – Length-weighted uncertainty.
selected_count (int) – Selected options.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.PortfolioConfig(*, service_target: Annotated[float, Ge(ge=0), Le(le=1)] = 0.5, risk_target: Annotated[float, Ge(ge=0), Le(le=1)] = 1.0, service_weight: Annotated[float, Ge(ge=0)] = 1.0, risk_weight: Annotated[float, Ge(ge=0)] = 1.0, uncertainty_weight: Annotated[float, Ge(ge=0)] = 0.5, cost_weight: Annotated[float, Ge(ge=0)] = 0.001, continuity_weight: Annotated[float, Ge(ge=0)] = 0.1, max_steps: Annotated[int, Ge(ge=1), Le(le=10000)] = 100, seed: int = 1)[source]
Bases:
BaseModelPortfolio weights and targets.
- Parameters:
service_target (float) – Hard aggregate service target.
risk_target (float) – Soft aggregate risk target.
service_weight (float) – Objective weight.
risk_weight (float) – Objective weight.
uncertainty_weight (float) – Objective weight.
cost_weight (float) – Objective weight per cost unit.
continuity_weight (float) – Penalty for missing adjacent treatment pairs.
max_steps (int) – Maximum improvement steps.
seed (int) – Deterministic scenario seed.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- exception brushline.strategic.portfolio.PortfolioError[source]
Bases:
ValueErrorRaised when portfolio data or constraints are inconsistent.
- class brushline.strategic.portfolio.PortfolioOption(*, option_id: Annotated[str, MinLen(min_length=1)], segment_id: Annotated[str, MinLen(min_length=1)], period_id: Annotated[str, MinLen(min_length=1)], action_id: Annotated[str, MinLen(min_length=1)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'] | None = None, cost: Annotated[float, Ge(ge=0)], capacity_units: Annotated[float, Ge(ge=0)] = 0, service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], risk: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]
Bases:
BaseModelOne selectable segment-period option.
- Parameters:
option_id (str) – Stable option id.
segment_id (str) – Segment id.
period_id (str) – Period id.
action_id (str) – Strategic action id.
method (str or None) – Treatment method.
cost (float) – Cost.
capacity_units (float) – Capacity consumption.
service_attainment (float) – Service outcome.
risk (float) – Risk outcome.
uncertainty (float) – Uncertainty outcome.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.PortfolioPeriod(*, period_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], start_year: ~typing.Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], capacity_by_method: dict[str, float] = <factory>)[source]
Bases:
BaseModelOne strategic period.
- Parameters:
period_id (str) – Period id.
start_year (int) – Year.
budget (float) – Treatment budget.
capacity_by_method (dict of str to float) – Capacity units by method.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.PortfolioSegment(*, segment_id: Annotated[str, MinLen(min_length=1)], span_id: Annotated[str, MinLen(min_length=1)], sequence: Annotated[int, Ge(ge=0)], length_m: Annotated[float, Gt(gt=0)], base_service: Annotated[float, Ge(ge=0), Le(le=1)], base_risk: Annotated[float, Ge(ge=0), Le(le=1)], base_uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]
Bases:
BaseModelOne segment in a strategic portfolio.
- Parameters:
segment_id (str) – Segment id.
span_id (str) – Span id.
sequence (int) – Position within the span.
length_m (float) – Segment length.
base_service (float) – No-treatment service attainment.
base_risk (float) – No-treatment risk.
base_uncertainty (float) – No-treatment uncertainty.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.PortfolioSelection(*, option_id: str, segment_id: str, period_id: str, action_id: str, cost: Annotated[float, Ge(ge=0)], service_attainment: Annotated[float, Ge(ge=0), Le(le=1)], risk: Annotated[float, Ge(ge=0), Le(le=1)], uncertainty: Annotated[float, Ge(ge=0), Le(le=1)])[source]
Bases:
BaseModelOne selected option.
- Parameters:
option_id (str) – Option id.
segment_id (str) – Segment id.
period_id (str) – Period id.
action_id (str) – Action id.
cost (float) – Cost.
service_attainment (float) – Service outcome.
risk (float) – Risk outcome.
uncertainty (float) – Uncertainty outcome.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.PortfolioViolation(*, code: Annotated[str, MinLen(min_length=1)], message: Annotated[str, MinLen(min_length=1)], period_id: str | None = None, segment_id: str | None = None)[source]
Bases:
BaseModelOne named portfolio violation.
- Parameters:
code (str) – Violation code.
message (str) – Human explanation.
period_id (str or None) – Period.
segment_id (str or None) – Segment.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class brushline.strategic.portfolio.StrategicPortfolio(*, schema_version: ~typing.Literal['brushline.strategic-portfolio.v1'] = 'brushline.strategic-portfolio.v1', portfolio_id: str, instance_id: str, config: ~brushline.strategic.portfolio.PortfolioConfig, selections: list[~brushline.strategic.portfolio.PortfolioSelection], period_summary: list[~brushline.strategic.portfolio.PeriodSummary], total_cost: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], service_attainment: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_service: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_risk: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], baseline_uncertainty: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], continuity_score: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], objective: float, feasible: bool, violations: list[~brushline.strategic.portfolio.PortfolioViolation] = <factory>, soft_violations: list[~brushline.strategic.portfolio.PortfolioViolation] = <factory>, created_utc: ~datetime.datetime)[source]
Bases:
BaseModelA solved strategic portfolio.
- Parameters:
schema_version ({"brushline.strategic-portfolio.v1"}) – Schema version.
portfolio_id (str) – Portfolio id.
instance_id (str) – Instance id.
config (PortfolioConfig) – Weights and targets.
selections (list of PortfolioSelection) – Selected options.
period_summary (list of PeriodSummary) – Period totals.
total_cost (float) – Total cost.
service_attainment (float) – Aggregate service.
risk (float) – Aggregate risk.
uncertainty (float) – Aggregate uncertainty.
baseline_service (float) – No-treatment service.
baseline_risk (float) – No-treatment risk.
baseline_uncertainty (float) – No-treatment uncertainty.
continuity_score (float) – Share of adjacent pairs with both treatments selected.
objective (float) – Weighted portfolio objective.
feasible (bool) – Hard constraints satisfied.
violations (list of PortfolioViolation) – Hard violations.
soft_violations (list of PortfolioViolation) – Soft violations.
created_utc (datetime) – Timezone-aware creation time.
- model_config = {'extra': 'forbid', 'frozen': True}
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- brushline.strategic.portfolio.build_strategic_portfolio(*, portfolio_id: str, instance_id: str, segments: list[PortfolioSegment], periods: list[PortfolioPeriod], options: list[PortfolioOption], config: PortfolioConfig | None = None, created_utc: datetime | None = None) StrategicPortfolio[source]
Build and improve a strategic portfolio.
- Parameters:
portfolio_id (str) – Portfolio id.
instance_id (str) – Instance id.
segments (list of PortfolioSegment) – Segments.
periods (list of PortfolioPeriod) – Periods.
options (list of PortfolioOption) – Selectable options.
config (PortfolioConfig, optional) – Targets and weights.
created_utc (datetime, optional) – Creation time.
- Returns:
StrategicPortfolio – Selected portfolio and report.
- Raises:
PortfolioError – When inputs are invalid.
- brushline.strategic.portfolio.validate_portfolio_inputs(segments: list[PortfolioSegment], periods: list[PortfolioPeriod], options: list[PortfolioOption]) ContractValidation[source]
Validate segment/period references, option uniqueness, and non-negativity.
- Parameters:
segments (list of PortfolioSegment) – Segments.
periods (list of PortfolioPeriod) – Periods.
options (list of PortfolioOption) – Options.
- Returns:
ContractValidation – Errors and counts.