LANDIS succession kernel

Purpose

ws4.ecosystem.landis implements the published LANDIS-II Biomass Succession equations in original Python. The Predictive Ecology Biomass_core tests are used as an exact reference oracle; no third-party code is copied.

Functions

  • calculate_sum_b — site biomass with the LANDIS young-cohort boundary;

  • calculate_competition — bAP and bPM;

  • calculate_anpp — actual ANPP;

  • calculate_growth_mortality — developmental mortality;

  • calculate_age_mortality — age-related mortality.

Reference traits

LANDIS_REFERENCE_TRAITS holds the 16-species appendix values for maximum cohort biomass, maximum ANPP, longevity, mortality shape, and growth-curve exponent. The values are numeric reference facts from the public Biomass_core comparison tables; no third-party code or prose is copied.

landis_reference_config(species=None, stage="nonSpinup") returns a configuration with the selected reference traits. Unknown names fail loudly. Fuel fraction and snag decay are not in the appendix and remain provisional.

Process

LandisSuccessionProcess runs in the growth phase and applies the kernel to each fragment. LandisSuccessionConfig supplies per-species traits and a default. The process can replace the default logistic succession source through ProcessEnsembleConfig.succession_process.

R parity

P199 ran the published Biomass_core R kernel in an isolated LandR/SpaDES.core stack and captured randomized parity fixtures in tests/fixtures/landis_r_parity/. WS4 matches the R outputs within 1e-8 for age mortality, ANPP, growth mortality, competition, and sumB. This is kernel parity, not a spatial landscape run.

Heterogeneous reference

P211 extends the P200 case to four pixel groups with initial ages 10–100 and biomass 500–5000 g/m². The reference year-10 biomass is 10822; WS4 is 10809.75 (-0.113%). The script and fixture are scripts/landis_heterogeneous_reference.R and tests/fixtures/landis_heterogeneous_reference/.

Spatial reference

P200 ran the full Biomass_core module on a 10 × 10, 100 m landscape for 10 years with a fixed seed. The captured trajectory is in tests/fixtures/landis_spatial_reference/ and the reproducibility script is scripts/landis_spatial_reference.R. This is a toy spatial reference, not a regional LBSE reproduction.

WS4 spatial comparison

P202 ran the WS4 LANDIS process on the P200 initial cohorts and found a -6.64% year-10 gap. P210 aligned the annual transition with Biomass_core’s age, mAge, floor, and integer-truncation order. Year 1 is now 2694 vs 2694; year 10 is 9444 vs 9460 (-0.169%). The residual is consistent with regeneration and module bookkeeping that the process does not yet implement.

Tests

tests/test_ecosystem_landis.py reproduces the published reference values for ANPP, growth/mortality, competition, sumB, and age mortality, including spin-up and non-spin-up stages and the young-cohort regression case.

LandisBatchSuccessionProcess applies the same kernels to the whole cohort table in one landscape event per year. tests/test_ecosystem_dataset.py checks that the batch state and volume match the per-fragment process exactly; only the event-log granularity differs.

The dataset runner maps compiled species codes to the reference traits with a provisional alias table (PL and PLI to jack pine, SX and SE to white spruce, BL to balsam fir, AT and ACT to trembling aspen, and so on). Unknown codes use the process default. The aliases are a bridge, not a species-specific calibration; callers can supply exact LandisSpeciesTraits overrides.

A species cohort’s biomass_t_ha is its density on its own area. The process converts it to LANDIS B in g/m² by multiplying by area_fraction and by 100, so sumB is the whole-fragment biomass in the kernel’s published units. Updated B is converted back to t/ha. This keeps multi-species competition and the area-weighted fragment totals consistent. Unknown species use the provisional default trait values, now expressed on the same g/m² scale as the reference table.

Limits

  • The process is a single-cohort-table transition, not a full landscape LBSE integration.

  • Seed dispersal, serotiny, resprouting, and light competition beyond the kernel are not yet implemented.

  • Reference values are numeric facts; no third-party implementation or prose is copied.

  • No LBSE or LandR run; the comparison is kernel-level.

  • Fuel fraction and snag decay remain provisional.

  • The source modules are reference-only and mostly have no explicit licence file.