Source code for brushline.vegetation.growth

"""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.
"""

from __future__ import annotations

import math
from typing import Literal

from pydantic import BaseModel, ConfigDict, Field, model_validator

from brushline.model.state import FunctionalGroup, StateClass, Uncertainty, VegetationState
from brushline.model.validation import ContractValidation
from brushline.vegetation.state_space import (
    StateDistribution,
    StateSpaceConfig,
    classify_state,
)

GROWTH_SCHEMA_VERSION: Literal["brushline.growth.v1"] = "brushline.growth.v1"
GROWTH_STATUSES: tuple[str, ...] = ("grown", "out_of_domain", "unknown")
GROWTH_MODEL_CARD = "brushline.low-vegetation.prototype.v0"


[docs] class GrowthError(ValueError): """Raised when a growth request is internally inconsistent."""
[docs] class GrowthParameters(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 = ConfigDict(extra="forbid", frozen=True) group: str height_max_m: float = Field(gt=0) height_rate: float = Field(gt=0) cover_max_pct: float = Field(gt=0, le=100) cover_rate: float = Field(gt=0) density_max_per_ha: float = Field(default=0, ge=0) density_rate: float = Field(default=0, ge=0) height_sd_m: float = Field(default=0, ge=0) cover_sd_pct: float = Field(default=0, ge=0) competition_sensitivity: float = Field(default=0, ge=0, le=1) notes: str = ""
GROWTH_PARAMETERS: tuple[GrowthParameters, ...] = ( GrowthParameters( group="shrub", height_max_m=4.0, height_rate=0.35, cover_max_pct=90, cover_rate=0.35, density_max_per_ha=5000, density_rate=0.3, height_sd_m=0.35, cover_sd_pct=8, competition_sensitivity=0.35, notes="Low woody vegetation; cutting can increase density.", ), GrowthParameters( group="deciduous_sprout", height_max_m=10.0, height_rate=0.25, cover_max_pct=95, cover_rate=0.3, density_max_per_ha=3000, density_rate=0.25, height_sd_m=0.5, cover_sd_pct=10, competition_sensitivity=0.45, notes="Resprouting hardwood.", ), GrowthParameters( group="conifer", height_max_m=20.0, height_rate=0.12, cover_max_pct=90, cover_rate=0.2, density_max_per_ha=2000, density_rate=0.2, height_sd_m=0.6, cover_sd_pct=10, competition_sensitivity=0.3, notes="Young conifer or mature edge.", ), GrowthParameters( group="grass_herb", height_max_m=0.6, height_rate=0.9, cover_max_pct=100, cover_rate=0.8, density_max_per_ha=0, density_rate=0, height_sd_m=0.1, cover_sd_pct=12, competition_sensitivity=0.1, notes="Herbaceous layer; not a woody cover class.", ), GrowthParameters( group="unknown", height_max_m=1, height_rate=0.01, cover_max_pct=1, cover_rate=0.01, density_max_per_ha=0, density_rate=0, notes="No growth for an unknown state.", ), )
[docs] class GrowthConfig(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 = ConfigDict(extra="forbid", frozen=True) site_index_reference_m: float = Field(default=20.0, gt=0) site_factor_min: float = Field(default=0.5, gt=0) site_factor_max: float = Field(default=1.5, gt=0) site_index_min_m: float = Field(default=0.0, ge=0) site_index_max_m: float = Field(default=40.0, gt=0) climate_factor_min: float = Field(default=0.5, gt=0) climate_factor_max: float = Field(default=1.5, gt=0) max_years: int = Field(default=20, ge=1) model_card_id: str = GROWTH_MODEL_CARD state_space: StateSpaceConfig = Field(default_factory=StateSpaceConfig) @model_validator(mode="after") def _ordered_ranges(self) -> GrowthConfig: if self.site_factor_min >= self.site_factor_max: raise ValueError("site factor range must increase") if self.site_index_min_m >= self.site_index_max_m: raise ValueError("site-index domain must increase") if self.climate_factor_min >= self.climate_factor_max: raise ValueError("climate factor range must increase") return self
[docs] class GrowthEnvironment(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 = ConfigDict(extra="forbid", frozen=True) site_index_m: float | None = Field(default=None, ge=0) climate_factor: float = Field(default=1.0, gt=0) competition: float = Field(default=0.0, ge=0, le=1) in_domain: bool = True domain_reason: str = "" @model_validator(mode="after") def _domain_reason(self) -> GrowthEnvironment: if not self.in_domain and not self.domain_reason.strip(): raise ValueError("an out-of-domain environment needs a reason") return self
[docs] class GrowthRequest(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 = ConfigDict(extra="forbid", frozen=True) segment_id: str = Field(min_length=1) functional_group: FunctionalGroup current: StateDistribution years: int = Field(ge=1, le=50) environment: GrowthEnvironment = Field(default_factory=GrowthEnvironment)
[docs] class GrowthResult(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 = ConfigDict(extra="forbid", frozen=True) schema_version: Literal["brushline.growth.v1"] = GROWTH_SCHEMA_VERSION segment_id: str functional_group: FunctionalGroup status: str years: int previous: StateDistribution next: StateDistribution | None = None next_state_class: StateClass | None = None environment: GrowthEnvironment height_change_m: float | None = None cover_change_pct: float | None = None reason: str = "" model_card_id: str = GROWTH_MODEL_CARD
[docs] def to_vegetation_state(self, state_year: int) -> VegetationState: """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. """ if self.next is None or self.next_state_class is None: raise GrowthError("no grown distribution is available") return VegetationState( segment_id=self.segment_id, state_year=state_year, functional_group=self.functional_group, state_class=self.next_state_class, height_m=self.next.height_m, cover_pct=self.next.cover_pct, density_per_ha=self.next.density_per_ha, age_years=self.next.age_years, uncertainty=Uncertainty( height_m_sd=self.next.height_sd, cover_pct_sd=self.next.cover_sd, density_sd=self.next.density_sd, confidence=self.next.confidence, ), source="brushline.vegetation.growth", source_version="p4.2", model_card_id=self.model_card_id, )
[docs] def grow( request: GrowthRequest, config: GrowthConfig | None = None, ) -> GrowthResult: """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. """ rules = config or GrowthConfig() if request.years > rules.max_years: raise GrowthError(f"years {request.years} exceeds the configured maximum {rules.max_years}") reason = _domain_reason(request.environment, rules) if reason: return GrowthResult( segment_id=request.segment_id, functional_group=request.functional_group, status="out_of_domain", years=request.years, previous=request.current, environment=request.environment, reason=reason, model_card_id=rules.model_card_id, ) if request.functional_group == "unknown": return GrowthResult( segment_id=request.segment_id, functional_group=request.functional_group, status="unknown", years=request.years, previous=request.current, environment=request.environment, reason="an unknown functional group has no growth model", model_card_id=rules.model_card_id, ) parameters = _parameters(request.functional_group) modifier = _modifier(request.environment, parameters, rules) current = request.current height = _saturate( current.height_m, parameters.height_max_m, parameters.height_rate, modifier, request.years, ) cover = _saturate( current.cover_pct, parameters.cover_max_pct, parameters.cover_rate, modifier, request.years, ) density = ( _saturate( current.density_per_ha or 0, parameters.density_max_per_ha, parameters.density_rate, modifier, request.years, ) if current.density_per_ha is not None and parameters.density_max_per_ha > 0 else current.density_per_ha ) age = current.age_years + request.years if current.age_years is not None else None state_class = classify_state( height, cover, request.functional_group, rules.state_space, ) if state_class == "unknown": state_class = "partial" probabilities = { state_class: 0.8, "unknown": 0.2, } next_distribution = StateDistribution( class_probabilities=probabilities, height_m=height, height_sd=math.hypot( current.height_sd, parameters.height_sd_m * request.years, ), cover_pct=cover, cover_sd=math.hypot( current.cover_sd, parameters.cover_sd_pct * request.years, ), density_per_ha=density, density_sd=( math.hypot( current.density_sd, parameters.density_rate * request.years, ) if density is not None else 0.0 ), age_years=age, confidence=max(0.0, current.confidence - 0.02 * request.years), ) return GrowthResult( segment_id=request.segment_id, functional_group=request.functional_group, status="grown", years=request.years, previous=current, next=next_distribution, next_state_class=state_class, environment=request.environment, height_change_m=height - current.height_m, cover_change_pct=cover - current.cover_pct, reason="saturating growth with site, climate, and competition modifiers", model_card_id=rules.model_card_id, )
[docs] def validate_growth_result(result: GrowthResult) -> ContractValidation: """Validate a growth result and its bounds. Parameters ---------- result : GrowthResult Result to validate. Returns ------- ContractValidation Errors, warnings, and counts. """ errors: list[str] = [] warnings: list[str] = [] if result.status not in GROWTH_STATUSES: errors.append(f"GROWTH-STATUS: unknown status {result.status!r}") if result.status != "grown": if result.next is not None: errors.append("GROWTH-NEXT: a blocked result has a next distribution") if not result.reason.strip(): errors.append("GROWTH-REASON: a blocked result has no reason") else: if result.next is None or result.next_state_class is None: errors.append("GROWTH-NEXT: a grown result has no next distribution") else: parameters = _parameters(result.functional_group) if result.next.height_m < result.previous.height_m - 1e-9: errors.append("GROWTH-MONOTONE: height decreased during growth") if result.next.cover_pct < result.previous.cover_pct - 1e-9: errors.append("GROWTH-MONOTONE: cover decreased during growth") if result.next.height_m > parameters.height_max_m + 1e-9: errors.append("GROWTH-BOUND: height exceeds the asymptote") if result.next.cover_pct > parameters.cover_max_pct + 1e-9: errors.append("GROWTH-BOUND: cover exceeds the asymptote") if result.next.class_probabilities.get(result.next_state_class, 0) <= 0: errors.append("GROWTH-PROBABILITY: next class has no probability") if ( result.next.age_years is not None and result.previous.age_years is not None and result.next.age_years != result.previous.age_years + result.years ): errors.append("GROWTH-AGE: age did not advance by the step") counts: dict[str, int | float] = { "segments": 1, "years": result.years, "status": 1 if result.status == "grown" else 0, } return ContractValidation(tuple(errors), tuple(warnings), counts)
def _parameters(group: FunctionalGroup) -> GrowthParameters: for parameters in GROWTH_PARAMETERS: if parameters.group == group: return parameters raise GrowthError(f"no growth parameters for {group!r}") def _domain_reason(environment: GrowthEnvironment, config: GrowthConfig) -> str: if not environment.in_domain: return environment.domain_reason if environment.site_index_m is not None and not ( config.site_index_min_m <= environment.site_index_m <= config.site_index_max_m ): return "site index is outside the growth applicability domain" if not (config.climate_factor_min <= environment.climate_factor <= config.climate_factor_max): return "climate factor is outside the growth applicability domain" return "" def _modifier( environment: GrowthEnvironment, parameters: GrowthParameters, config: GrowthConfig, ) -> float: site = 1.0 if environment.site_index_m is not None: site = max( config.site_factor_min, min( config.site_factor_max, environment.site_index_m / config.site_index_reference_m, ), ) climate = max( config.climate_factor_min, min(config.climate_factor_max, environment.climate_factor), ) competition = max( 0.0, 1.0 - environment.competition * parameters.competition_sensitivity, ) return site * climate * competition def _saturate( current: float, asymptote: float, rate: float, modifier: float, years: int, ) -> float: if current >= asymptote: return current return asymptote - (asymptote - current) * math.exp(-rate * modifier * years) __all__ = [ "GROWTH_MODEL_CARD", "GROWTH_PARAMETERS", "GROWTH_SCHEMA_VERSION", "GROWTH_STATUSES", "GrowthConfig", "GrowthEnvironment", "GrowthError", "GrowthParameters", "GrowthRequest", "GrowthResult", "grow", "validate_growth_result", ]