EcoSIM Natural Plant Management

Overview

Use this skill to build, validate, or edit EcoSIM pft_mgmt_in inputs for natural ecosystems. Natural PFTs normally need planting information; tree PFTs also receive an annual 1% thinning rate spread uniformly over 12 monthly events. Existing NetCDF files can be exported to an Excel workbook for editing, then converted back to JSON or NetCDF.

Read references/plant_mgmt_contract.md when you need exact NetCDF dimensions, Excel sheet columns, variable names, string formats, thinning event fields, or JSON examples.

Workflow

1. Identify active PFTs for each topo unit and validate EcoSIM vegetation codes with $ecosim-vegetation-code against the active PFT parameter CDL.
2. Choose the editing path:
   • For an existing .nc, export to Excel, edit the workbook, then convert the edited workbook back to JSON or NetCDF.
   • For a new file, create either JSON directly or an Excel workbook matching the contract schema.
3. Set pft_dflag = 0 for constant natural vegetation unless year-specific PFT composition or management is needed. With pft_dflag = 0, EcoSIM uses record 1. With pft_dflag = 1, the selected PlantInfoMod.F90 matches the forcing year (yeari) to the NetCDF year record.
4. Set each topo unit NZ to the active PFT count. Do not exceed maxpfts = 5; only the first NZ PFT entries matter.
5. For each PFT, set pft_type to the validated six-character EcoSIM code. EcoSIM will use the first four characters plus the grid Koppen code when KoppenClimZone_col > 0, but keep the full validated code for clarity.
6. For planting, use DDMMYYYY = "01019999" unless the user provides a site-specific date. Derive Planting_population as plants, shoots, tillers, or stems per square meter and Planting_depth in meters.
7. For non-tree natural PFTs, set mgmt empty. For tree PFTs, add 12 monthly thinning events using FractionCut = 0.01 / 12 = 0.0008333333.

Conversion Commands

Use the bundled bridge for NetCDF, Excel, and JSON conversions:

.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py nc-to-xlsx pft-mngt.nc pft-mngt.xlsx
.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py xlsx-to-json pft-mngt.xlsx pft-mngt.json
.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py xlsx-to-nc pft-mngt.xlsx pft-mngt-edited.nc --json-output pft-mngt-edited.json

JSON remains supported. To create NetCDF directly from JSON, use either the bridge or PlantMgmtWriter.py:

.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py json-to-nc input.json output.nc
.venv-cmip6/bin/python applications/notebooks/scripts/PlantMgmtWriter.py input.json output.nc

Evidence Rules

• Search the web or literature for typical density and planting depth when values are not provided. Cite sources in the response or derivation note.
• Prefer species-specific stand density, seedling density, stem density, tiller density, or plant density. Convert all density units to plants m-2.
• Avoid substituting percent cover, LAI, biomass, or seeding rate for plant density unless no better source exists; if used, label it as an assumption.
• Convert depths to meters. If evidence is weak, use conservative defaults only with an explicit note: herbaceous PFTs often need shallow depths, tree seedlings need a larger initial depth.

Tree Thinning Convention

Apply monthly thinning only to tree PFTs such as ndlf, ndld, bdlf, bdln, bdlw, bspr, dfir, jpin, lpin, tasp, and woak. Treat bush, busn, and shru as non-tree woody PFTs unless the user asks to include woody shrub thinning.

Use these monthly event dates with year 0000:

31010000 28020000 31030000 30040000 31050000 30060000
31070000 31080000 30090000 31100000 30110000 31120000

Each thinning event should use:

{
  "iHarvType": 0,
  "jHarvType": 0,
  "CutHeight": 1000.0,
  "FractionCut": 0.0008333333,
  "FineFractionLeafHarvested_pft": 1,
  "FineFractionNonleafHarvested_pft": 1,
  "StalkFractionHarvested_pft": 1,
  "StandeadFractionHarvested_pft": 0,
  "FineFractionLeafHarvested_col": 0,
  "FineFractionNonleafHarvested_col": 0,
  "StalkFractionHarvested_col": 0,
  "StandeadFractionHarvested_col": 0
}

This represents natural mortality/thinning without ecosystem biomass export. Flag the mass-flow assumption if changing ecosystem-level export fractions.

For harvested biomass, the ecosystem-level harvest fraction applies to the harvested component, not to the original component pool. Litter return is:

component_pool * pft_harvest_fraction * (1 - ecosystem_harvest_fraction)

For transient yearly schedules, prefer actual calendar years in DDMMYYYY if exact day-of-year alignment matters. The selected PlantInfoMod.F90 treats year 0000 as a leap year when converting dates to ordinal day.

Validation

Run the bridge round trip on a scratch path and inspect the decoded JSON:

.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py nc-to-json input.nc /tmp/pft-mgmt.json
.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py nc-to-xlsx input.nc /tmp/pft-mgmt.xlsx
.venv-cmip6/bin/python .agents/skills/ecosim-natural-plant-mgmt/scripts/plant_mgmt_excel_bridge.py xlsx-to-nc /tmp/pft-mgmt.xlsx /tmp/pft-mgmt-roundtrip.nc --json-output /tmp/pft-mgmt-roundtrip.json

Verify that pft_dflag, year, NH1/NV1/NH2/NV2/NZ, pft_type, pft_pltinfo, nmgnts, and pft_mgmt exist; NZ equals active PFT count; nmgnts equals populated management rows; non-tree PFTs have zero management events unless explicitly managed; tree PFTs have 12 thinning events when using the natural-tree convention.