brushline.vegetation.treatment

Method- and season-specific treatment parameters, the immediate top-kill and cover reduction, the resprouting and delay rules, the post-delay growth trajectory, cost hooks, and the treatment validator.

Method-specific low-vegetation treatment transitions.

A treatment is a transition, not a reset to zero. The model records the immediate top-kill and cover reduction, a density change from resprouting, a regrowth delay, and a post-delay trajectory through the P4.2 growth model. The efficacy parameters are priors; P4.4 calibrates them.

class brushline.vegetation.treatment.TreatmentConfig(*, min_residual_height_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 0.05, min_residual_cover_pct: Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=100)] = 1.0, season_factors: dict[str, float]=<factory>, growth_config: GrowthConfig = <factory>, state_space: StateSpaceConfig = <factory>, max_regrowth_years: Annotated[int, ~annotated_types.Ge(ge=0)] = 20, model_card_id: str = 'brushline.low-vegetation.prototype.v0')[source]

Bases: BaseModel

Residual, season, growth, and cost rules.

Parameters:
  • min_residual_height_m (float, optional) – Minimum height after treatment. Defaults to 0.05.

  • min_residual_cover_pct (float, optional) – Minimum cover after treatment. Defaults to 1.

  • season_factors (dict of str to float, optional) – Season multipliers.

  • growth_config (GrowthConfig, optional) – Post-treatment growth rules.

  • state_space (StateSpaceConfig, optional) – Discretization rules.

  • max_regrowth_years (int, optional) – Maximum post-treatment trajectory. Defaults to 20.

  • model_card_id (str, optional) – Model card id.

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

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

exception brushline.vegetation.treatment.TreatmentError[source]

Bases: ValueError

Raised when a treatment request is internally inconsistent.

class brushline.vegetation.treatment.TreatmentParameters(*, method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], efficacy: Annotated[float, Ge(ge=0), Le(le=1)], selectivity: Annotated[float, Ge(ge=0), Le(le=1)], top_kill: Annotated[float, Ge(ge=0), Le(le=1)], resprout_factor: Annotated[float, Ge(ge=0), Le(le=1)], regrowth_delay_years: Annotated[int, Ge(ge=0), Le(le=20)], cost_per_ha: Annotated[float, Ge(ge=0)], fixed_cost: Annotated[float, Ge(ge=0)] = 0, currency: str = 'CAD', notes: str = '')[source]

Bases: BaseModel

Base parameters for one treatment method.

Parameters:
  • method (str) – Treatment method.

  • efficacy (float) – Base efficacy.

  • selectivity (float) – Preserved non-target fraction from 0 to 1.

  • top_kill (float) – Height-reduction share from 0 to 1.

  • resprout_factor (float) – Density increase from resprouting from 0 to 1.

  • regrowth_delay_years (int) – Delay before regrowth.

  • cost_per_ha (float) – Variable cost per hectare.

  • fixed_cost (float) – Fixed cost per action.

  • currency (str) – Currency.

  • notes (str) – Caveat.

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

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

class brushline.vegetation.treatment.TreatmentRequest(*, segment_id: ~typing.Annotated[str, ~annotated_types.MinLen(min_length=1)], functional_group: ~typing.Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], current: ~brushline.vegetation.state_space.StateDistribution, method: ~typing.Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: ~typing.Literal['spring', 'summer', 'fall', 'winter', 'any'], intensity: ~typing.Annotated[float, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=1)], quantity_ha: ~typing.Annotated[float, ~annotated_types.Ge(ge=0)] = 1.0, regrowth_years: ~typing.Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=20)] = 0, environment: ~brushline.vegetation.growth.GrowthEnvironment = <factory>)[source]

Bases: BaseModel

One treatment transition request.

Parameters:
  • segment_id (str) – Segment id.

  • functional_group (str) – Functional group.

  • current (StateDistribution) – Current distribution.

  • method (str) – Treatment method.

  • season (str) – Treatment season.

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

  • quantity_ha (float, optional) – Treated area for cost. Defaults to 1.

  • regrowth_years (int, optional) – Post-treatment trajectory length. Defaults to 0.

  • environment (GrowthEnvironment, optional) – Growth environment after the delay.

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

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

class brushline.vegetation.treatment.TreatmentResult(*, schema_version: Literal['brushline.treatment.v1'] = 'brushline.treatment.v1', segment_id: str, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], method: Literal['manual', 'mechanical', 'chemical', 'mowing', 'grazing', 'prescribed_fire', 'other'], season: Literal['spring', 'summer', 'fall', 'winter', 'any'], status: str, previous: StateDistribution, immediate: StateDistribution | None = None, next: StateDistribution | None = None, immediate_state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'] | None = None, next_state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'] | None = None, efficiency: float = 0.0, height_reduction_m: float | None = None, cover_reduction_pct: float | None = None, density_change_per_ha: float | None = None, cost: Annotated[float, Ge(ge=0)] = 0, currency: str = 'CAD', regrowth_delay_years: int = 0, regrowth_years: int = 0, environment: GrowthEnvironment, reason: str = '', model_card_id: str = 'brushline.low-vegetation.prototype.v0')[source]

Bases: BaseModel

The result of one treatment transition.

Parameters:
  • schema_version ({"brushline.treatment.v1"}) – Result schema version.

  • segment_id (str) – Segment id.

  • functional_group (str) – Functional group.

  • method (str) – Method.

  • season (str) – Season.

  • status (str) – applied, out_of_domain, or unknown.

  • previous (StateDistribution) – Pre-treatment distribution.

  • immediate (StateDistribution or None) – Immediate post-treatment distribution.

  • next (StateDistribution or None) – Distribution at the end of the requested regrowth horizon.

  • immediate_state_class (str or None) – Immediate class.

  • next_state_class (str or None) – Trajectory class.

  • efficiency (float) – Effective efficacy after season and intensity.

  • height_reduction_m (float or None) – Immediate height reduction.

  • cover_reduction_pct (float or None) – Immediate cover reduction.

  • density_change_per_ha (float or None) – Immediate density change.

  • cost (float) – Treatment cost.

  • currency (str) – Cost currency.

  • regrowth_delay_years (int) – Delay before regrowth.

  • regrowth_years (int) – Requested trajectory length.

  • environment (GrowthEnvironment) – Growth environment.

  • reason (str) – Result reason.

  • model_card_id (str) – Model card.

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

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

to_vegetation_state(state_year: int) → VegetationState[source]

Convert the trajectory distribution to a state contract.

Parameters:

state_year (int) – Output state year.

Returns:

VegetationState – The next or immediate state.

Raises:

TreatmentError – When no post-treatment distribution exists.

brushline.vegetation.treatment.apply_treatment(request: TreatmentRequest, config: TreatmentConfig | None = None) → TreatmentResult[source]

Apply one method-specific treatment transition.

Parameters:
  • request (TreatmentRequest) – Current distribution and treatment context.

  • config (TreatmentConfig, optional) – Residual, season, growth, and cost rules.

Returns:

TreatmentResult – Immediate and trajectory distributions, cost, and reason.

Raises:

TreatmentError – When a regrowth horizon exceeds the configured maximum.

brushline.vegetation.treatment.validate_treatment_result(result: TreatmentResult) → ContractValidation[source]

Validate a treatment result and its transition invariants.

Parameters:

result (TreatmentResult) – Result to validate.

Returns:

ContractValidation – Errors, warnings, and counts.