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:
BaseModelOne hard or soft constraint.
- Parameters:
constraint_id (str) – Stable id.
kind (str) – Constraint kind.
scope (str) –
global,period,segment, orspan.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:
BaseModelThe 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.
- exception brushline.optimization.formulation.FormulationError[source]
Bases:
ValueErrorRaised 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:
BaseModelOne 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:
BaseModelOne 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:
BaseModelOne 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:
BaseModelOne 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:
BaseModelOne 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:
BaseModelOne stable decision variable.
- Parameters:
index (int) – Stable variable index.
kind (str) –
treatmentormonitoring.target_id (str) – Segment or span id.
period_id (str) – Period id.
option_ids (list of str) – Option ids with
nonefirst.
- 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.