brushline.vegetation.growth

The functional-group growth parameters, site/climate/competition environment, saturating growth step, result conversion, and growth validator.

Fast segment-level low-vegetation growth.

The growth model uses saturating height and cover curves per functional group, with site, climate, and competition modifiers. It preserves uncertainty and age, flags out-of-domain environments instead of extrapolating, and does not apply a treatment transition. It is deterministic and cheap enough for the P5 search loop.

class brushline.vegetation.growth.GrowthConfig(*, site_index_reference_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 20.0, site_factor_min: Annotated[float, ~annotated_types.Gt(gt=0)] = 0.5, site_factor_max: Annotated[float, ~annotated_types.Gt(gt=0)] = 1.5, site_index_min_m: Annotated[float, ~annotated_types.Ge(ge=0)] = 0.0, site_index_max_m: Annotated[float, ~annotated_types.Gt(gt=0)] = 40.0, climate_factor_min: Annotated[float, ~annotated_types.Gt(gt=0)] = 0.5, climate_factor_max: Annotated[float, ~annotated_types.Gt(gt=0)] = 1.5, max_years: Annotated[int, ~annotated_types.Ge(ge=1)] = 20, model_card_id: str = 'brushline.low-vegetation.prototype.v0', state_space: StateSpaceConfig = <factory>)[source]

Bases: BaseModel

Site, climate, and uncertainty rules for growth.

Parameters:
  • site_index_reference_m (float, optional) – Reference site index. Defaults to 20.

  • site_factor_min (float, optional) – Minimum site modifier. Defaults to 0.5.

  • site_factor_max (float, optional) – Maximum site modifier. Defaults to 1.5.

  • site_index_min_m (float, optional) – Lower site-index domain. Defaults to 0.

  • site_index_max_m (float, optional) – Upper site-index domain. Defaults to 40.

  • climate_factor_min (float, optional) – Lower climate modifier domain. Defaults to 0.5.

  • climate_factor_max (float, optional) – Upper climate modifier domain. Defaults to 1.5.

  • max_years (int, optional) – Maximum step length. Defaults to 20.

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

  • state_space (StateSpaceConfig, optional) – Discretization rules.

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

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

class brushline.vegetation.growth.GrowthEnvironment(*, site_index_m: Annotated[float | None, Ge(ge=0)] = None, climate_factor: Annotated[float, Gt(gt=0)] = 1.0, competition: Annotated[float, Ge(ge=0), Le(le=1)] = 0.0, in_domain: bool = True, domain_reason: str = '')[source]

Bases: BaseModel

Site, climate, competition, and domain context.

Parameters:
  • site_index_m (float or None) – Site index, when known.

  • climate_factor (float, optional) – Climate modifier. Defaults to 1.

  • competition (float, optional) – Competition from 0 to 1. Defaults to 0.

  • in_domain (bool, optional) – Whether the environment is inside the model domain. Defaults to True.

  • domain_reason (str, optional) – Why the environment is outside the domain.

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

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

exception brushline.vegetation.growth.GrowthError[source]

Bases: ValueError

Raised when a growth request is internally inconsistent.

class brushline.vegetation.growth.GrowthParameters(*, group: str, height_max_m: Annotated[float, Gt(gt=0)], height_rate: Annotated[float, Gt(gt=0)], cover_max_pct: Annotated[float, Gt(gt=0), Le(le=100)], cover_rate: Annotated[float, Gt(gt=0)], density_max_per_ha: Annotated[float, Ge(ge=0)] = 0, density_rate: Annotated[float, Ge(ge=0)] = 0, height_sd_m: Annotated[float, Ge(ge=0)] = 0, cover_sd_pct: Annotated[float, Ge(ge=0)] = 0, competition_sensitivity: Annotated[float, Ge(ge=0), Le(le=1)] = 0, notes: str = '')[source]

Bases: BaseModel

Growth parameters for one functional group.

Parameters:
  • group (str) – Functional group.

  • height_max_m (float) – Height asymptote.

  • height_rate (float) – Height saturation rate per year.

  • cover_max_pct (float) – Cover asymptote.

  • cover_rate (float) – Cover saturation rate per year.

  • density_max_per_ha (float) – Density asymptote, or zero when density is not modelled.

  • density_rate (float) – Density saturation rate per year.

  • height_sd_m (float) – Annual height uncertainty.

  • cover_sd_pct (float) – Annual cover uncertainty.

  • competition_sensitivity (float) – Competition effect from 0 to 1.

  • notes (str) – Short caveat.

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

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

class brushline.vegetation.growth.GrowthRequest(*, 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, years: ~typing.Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=50)], environment: ~brushline.vegetation.growth.GrowthEnvironment = <factory>)[source]

Bases: BaseModel

A growth step for one segment.

Parameters:
  • segment_id (str) – Segment id.

  • functional_group (str) – Functional group.

  • current (StateDistribution) – Current distribution.

  • years (int) – Growth step in years.

  • environment (GrowthEnvironment) – Site, climate, and competition context.

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

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

class brushline.vegetation.growth.GrowthResult(*, schema_version: Literal['brushline.growth.v1'] = 'brushline.growth.v1', segment_id: str, functional_group: Literal['unknown', 'shrub', 'deciduous_sprout', 'conifer', 'grass_herb'], status: str, years: int, previous: StateDistribution, next: StateDistribution | None = None, next_state_class: Literal['unknown', 'partial', 'grass_herb', 'shrub', 'young_tree', 'mixed', 'mature_edge'] | None = None, environment: GrowthEnvironment, height_change_m: float | None = None, cover_change_pct: float | None = None, reason: str = '', model_card_id: str = 'brushline.low-vegetation.prototype.v0')[source]

Bases: BaseModel

The result of one growth step.

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

  • segment_id (str) – Segment id.

  • functional_group (str) – Functional group.

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

  • years (int) – Growth step.

  • previous (StateDistribution) – Previous distribution.

  • next (StateDistribution or None) – Next distribution, or None when the step is blocked.

  • next_state_class (str or None) – Class implied by the grown distribution.

  • environment (GrowthEnvironment) – Environment context.

  • height_change_m (float or None) – Height change.

  • cover_change_pct (float or None) – Cover change.

  • reason (str) – Why the step is blocked or how it grew.

  • 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 grown distribution to a state contract.

Parameters:

state_year (int) – Output state year.

Returns:

VegetationState – The grown state.

Raises:

GrowthError – When the growth step did not produce a next distribution.

brushline.vegetation.growth.grow(request: GrowthRequest, config: GrowthConfig | None = None) → GrowthResult[source]

Grow one segment by a fixed number of years.

Parameters:
  • request (GrowthRequest) – Current distribution, group, years, and environment.

  • config (GrowthConfig, optional) – Growth rules.

Returns:

GrowthResult – The grown distribution or an explicit blocked status.

Raises:

GrowthError – When the step length exceeds the configured maximum.

brushline.vegetation.growth.validate_growth_result(result: GrowthResult) → ContractValidation[source]

Validate a growth result and its bounds.

Parameters:

result (GrowthResult) – Result to validate.

Returns:

ContractValidation – Errors, warnings, and counts.