brushline.optimization.formulation

The optimization variable, option, period, segment, span, constraint, and objective models, plus the stable formulation builder and validator.

Optimization formulation: variables, options, constraints, and objectives.

The formulation is the stable boundary between Brushline and Fresh Solutions. A variable index maps to one segment/period or span/period; an option index maps to no action or one treatment/monitoring option. The evaluator, operators, archive, and adapter all use these indices.

class brushline.optimization.formulation.ConstraintSpec(*, constraint_id: Annotated[str, MinLen(min_length=1)], kind: str, scope: str, target_id: Annotated[str, MinLen(min_length=1)], period_id: str | None = None, value: Annotated[float, Ge(ge=0)], unit: Annotated[str, MinLen(min_length=1)], hard: bool = True, description: str = '')[source]

Bases: BaseModel

One hard or soft constraint.

Parameters:
  • constraint_id (str) – Stable id.

  • kind (str) – Constraint kind.

  • scope (str) – global, period, segment, or span.

  • target_id (str) – Target id.

  • period_id (str or None) – Period id, when relevant.

  • value (float) – Limit or target value.

  • unit (str) – Unit.

  • hard (bool) – Whether violation is infeasible.

  • description (str) – Human description.

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

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

class brushline.optimization.formulation.Formulation(*, schema_version: ~typing.Literal['brushline.optimization-formulation.v1'] = 'brushline.optimization-formulation.v1', formulation_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], currency: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], periods: ~typing.Annotated[list[~brushline.optimization.formulation.PeriodSpec], ~annotated_types.MinLen(min_length=1)], segments: ~typing.Annotated[list[~brushline.optimization.formulation.SegmentSpec], ~annotated_types.MinLen(min_length=1)], spans: list[~brushline.optimization.formulation.SpanSpec] = <factory>, treatment_options: list[~brushline.optimization.formulation.TreatmentOption] = <factory>, monitoring_options: list[~brushline.optimization.formulation.MonitoringOption] = <factory>, variables: ~typing.Annotated[list[~brushline.optimization.formulation.Variable], ~annotated_types.MinLen(min_length=1)], constraints: list[~brushline.optimization.formulation.ConstraintSpec] = <factory>, objectives: ~typing.Annotated[list[~brushline.model.archive.Objective], ~annotated_types.MinLen(min_length=1)], created_utc: ~datetime.datetime)[source]

Bases: BaseModel

The complete optimization formulation.

Parameters:
  • schema_version ({"brushline.optimization-formulation.v1"}) – Schema version.

  • formulation_id (str) – Formulation id.

  • currency (str) – Currency.

  • periods (list of PeriodSpec) – Planning periods.

  • segments (list of SegmentSpec) – Segments.

  • spans (list of SpanSpec) – Monitoring spans.

  • treatment_options (list of TreatmentOption) – Treatment options.

  • monitoring_options (list of MonitoringOption) – Monitoring options.

  • variables (list of Variable) – Stable variables.

  • constraints (list of ConstraintSpec) – Constraints.

  • objectives (list of Objective) – Objective vector.

  • created_utc (datetime) – Creation time.

model_config = {'extra': 'forbid'}

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

property variable_count: int

Return the variable count.

Returns:

int – Number of decision variables.

option_count(variable_index: int) → int[source]

Return the option count for one variable.

Parameters:

variable_index (int) – Variable index.

Returns:

int – Number of options.

option_at(variable_index: int, option_index: int) → str[source]

Return the option id at an index.

Parameters:
  • variable_index (int) – Variable index.

  • option_index (int) – Option index.

Returns:

str – Option id.

initial_assignment() → dict[int, int][source]

Return the no-action assignment.

Returns:

dict of int to int – All variables at option 0.

exception brushline.optimization.formulation.FormulationError[source]

Bases: ValueError

Raised when a formulation is inconsistent.

class brushline.optimization.formulation.MonitoringOption(*, option_id: Annotated[str, MinLen(min_length=1)], sensor: Literal['lidar', 'uav_lidar', 'imagery', 'field', 'inspection', 'other'], sampling_intensity: Annotated[float, Ge(ge=0), Le(le=1)], cost_per_span: Annotated[float, Ge(ge=0)], label: str = '')[source]

Bases: BaseModel

One selectable monitoring option.

Parameters:
  • option_id (str) – Stable option id.

  • sensor (str) – Sensor.

  • sampling_intensity (float) – Sampling intensity from 0 to 1.

  • cost_per_span (float) – Cost per span.

  • label (str) – Human label.

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

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

class brushline.optimization.formulation.PeriodSpec(*, 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)], end_year: ~typing.Annotated[int, ~annotated_types.Ge(ge=1900), ~annotated_types.Le(le=2200)], budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], monitoring_budget: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 0, capacity_by_method: dict[str, float] = <factory>, season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'] = 'any')[source]

Bases: BaseModel

One planning period and its resource limits.

Parameters:
  • period_id (str) – Stable period id.

  • start_year (int) – First year.

  • end_year (int) – Last year.

  • budget (float) – Treatment budget.

  • monitoring_budget (float) – Monitoring budget.

  • capacity_by_method (dict of str to float) – Capacity by method, in hectares.

  • season (str) – Dominant season.

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

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

class brushline.optimization.formulation.SegmentSpec(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], corridor_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], length_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], treatment_unit_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], service_standard_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], max_height_m: ~typing.Annotated[float, ~annotated_types.Gt(gt=0)], min_clearance_m: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)], allowed_methods: list[~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other']] = <factory>, inaccessible_period_ids: list[str] = <factory>)[source]

Bases: BaseModel

One optimization segment.

Parameters:
  • segment_id (str) – Segment id.

  • corridor_id (str) – Corridor id.

  • length_m (float) – Segment length.

  • treatment_unit_id (str) – Treatment unit.

  • service_standard_id (str) – Service standard.

  • max_height_m (float) – Service maximum height.

  • min_clearance_m (float) – Service minimum clearance.

  • allowed_methods (list of str) – Allowed treatment methods. Empty means all.

  • inaccessible_period_ids (list of str, optional) – Periods with no access.

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

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

class brushline.optimization.formulation.SpanSpec(*, span_id: Annotated[str, MinLen(min_length=1)], corridor_id: Annotated[str, MinLen(min_length=1)], segment_ids: Annotated[list[str], MinLen(min_length=1)], monitoring_allowed: bool = True)[source]

Bases: BaseModel

One monitoring span.

Parameters:
  • span_id (str) – Span id.

  • corridor_id (str) – Corridor id.

  • segment_ids (list of str) – Segments in the span.

  • monitoring_allowed (bool) – Whether monitoring is allowed.

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

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

class brushline.optimization.formulation.TreatmentOption(*, option_id: Annotated[str, MinLen(min_length=1)], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], intensity: Annotated[float, Ge(ge=0), Le(le=1)], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], cost_per_ha: Annotated[float, Ge(ge=0)], fixed_cost: Annotated[float, Ge(ge=0)] = 0, label: str = '')[source]

Bases: BaseModel

One selectable treatment option.

Parameters:
  • option_id (str) – Stable option id.

  • method (str) – Treatment method.

  • intensity (float) – Intensity from 0 to 1.

  • season (str) – Season.

  • cost_per_ha (float) – Variable cost.

  • fixed_cost (float) – Fixed cost.

  • label (str) – Human label.

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

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

class brushline.optimization.formulation.Variable(*, index: Annotated[int, Ge(ge=0)], kind: str, target_id: Annotated[str, MinLen(min_length=1)], period_id: Annotated[str, MinLen(min_length=1)], option_ids: Annotated[list[str], MinLen(min_length=1)])[source]

Bases: BaseModel

One stable decision variable.

Parameters:
  • index (int) – Stable variable index.

  • kind (str) – treatment or monitoring.

  • target_id (str) – Segment or span id.

  • period_id (str) – Period id.

  • option_ids (list of str) – Option ids with none first.

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

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

brushline.optimization.formulation.build_formulation(*, formulation_id: str, periods: list[PeriodSpec], segments: list[SegmentSpec], spans: list[SpanSpec], treatment_options: list[TreatmentOption], monitoring_options: list[MonitoringOption], currency: str = 'CAD', created_utc: datetime | None = None) → Formulation[source]

Build a stable formulation with variables and constraints.

Parameters:
  • formulation_id (str) – Formulation id.

  • periods (list of PeriodSpec) – Periods.

  • segments (list of SegmentSpec) – Segments.

  • spans (list of SpanSpec) – Spans.

  • treatment_options (list of TreatmentOption) – Treatment options.

  • monitoring_options (list of MonitoringOption) – Monitoring options.

  • currency (str, optional) – Currency. Defaults to CAD.

  • created_utc (datetime, optional) – Creation time.

Returns:

Formulation – Stable variables, constraints, and objectives.

Raises:

FormulationError – When the generated formulation is invalid.

brushline.optimization.formulation.validate_formulation(formulation: Formulation) → ContractValidation[source]

Validate variable indices, references, options, constraints, and objectives.

Parameters:

formulation (Formulation) – Formulation to validate.

Returns:

ContractValidation – Errors, warnings, and counts.