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:
BaseModelSite, 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:
BaseModelSite, 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:
ValueErrorRaised 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:
BaseModelGrowth 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:
BaseModelA 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:
BaseModelThe 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, orunknown.years (int) – Growth step.
previous (StateDistribution) – Previous distribution.
next (StateDistribution or None) – Next distribution, or
Nonewhen 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.