ameriflux-namelist-generator
Create EcoSIM Fortran namelist files and workable EcoSIM run folders for AmeriFlux site runs from site-specific grid, plant management, climate forcing, and greenhouse-gas inputs. Use when preparing o
SKILL.md.agents/skills/ameriflux-namelist-generator/SKILL.md
GitHubAmeriFlux Namelist Generator
Overview
Use this skill to create EcoSIM run namelists and executable-ready run folders for AmeriFlux sites. The namelist follows the Blodgett Blodget.ndlf.nolig.namelist pattern: one regression_test block, one ecosim block with site-specific forcing paths and output controls, an empty bbgcforc block, and one ecosim_time block.
Read references/namelist_contract.md when you need the field contract, forcing-period rules, path conventions, or validation checklist.
For any request to create a run folder, runfolder, run directory, or runnable site case, read and follow references/runfolder_workflow.md before writing files.
When asked to create a run folder for a site, build it under result/<SITE_ID>/ with two subfolders: input/ for every input file (site NetCDF, sidecars, reports, and copies of the PFT, GHG, and microbial parameter files) and run_dir/ for the namelist alone. Use scripts/create_site_run_folder.py --site-id <SITE_ID> after the site inputs exist, then always run scripts/create_site_smoke_run.py --site-id <SITE_ID> for a 2-year smoke run in result/<SITE_ID>/smoke_run/ followed by the plant-trait evaluation of the .desc file it writes; severe trait findings are corrected from literature-backed ranges in a site PFT parameter copy and the smoke run is repeated until they are fixed (see the run-folder workflow). Track the request with the ecosim-site-run-tracker skill.
Workflow
- Identify the AmeriFlux
site_idsuch asUS-Ha1,US-MMS, orUS-Var. - Confirm that site artifacts exist. Prefer:
result/<SITE_ID>/<SITE_ID>_ecosim_grid.ncresult/<SITE_ID>/<SITE_ID>_ecosim_climate_<first>-<last>.nc(climate files carry their forcing years)result/<SITE_ID>/<SITE_ID>_pft_mgmt.ncresult/<SITE_ID>/<SITE_ID>_ecosim_site.jsonThen searchresult/,inputs/,data/, and the repository root.
- If climate, grid, soil, or plant-management files are missing, use the relevant AmeriFlux skills first:
ameriflux-era5-to-ecosim,ameriflux-surgo-grid-extract,ecosim-natural-plant-mgmt, orunified-ameriflux-extractor. - Generate the namelist with the bundled script:
python .agents/skills/ameriflux-namelist-generator/scripts/create_ameriflux_namelist.py \
--site-id US-Var \
--output result/US-Var/US-Var.namelist \
--pft-file /Users/jinyuntang/work/github/ecosim_workspace/croots/input_data/ecosim_pftpar_20260520.nc \
--atm-ghg-file /Users/jinyuntang/work/github/ecosim_workspace/croots/input_data/fatm_hist_GHGs_1750-2023.nc
- If writing the namelist into an EcoSIM run directory, pass
--run-dir /path/to/run_dirso input paths are written relative to the run directory, matching the Blodgett example. - Review
start_date,forc_periods, andstop_n. The script can infer forcing years fromyearin the climate NetCDF, but simulation chronology is a modeling decision. - Validate that referenced files exist from the namelist execution directory.
Common Overrides
- Use
--case-namefor a model case label different from the site ID. - Use
--grid-file,--pft-mgmt-file, and--climate-filewhen auto-discovery chooses the wrong artifact. - Use
--force-start-year,--spinup-end-year,--force-end-year,--spinup-cycles,--start-year, and--stop-nto control chronology. - Use
--lignification truefor lignified root experiments; default is.false.. - Use
--micpar-fileto include amicpar_file_inline.
Cautions
- Do not set missing climate, grid, or plant-management files to
NO; that can make EcoSIM run with physically meaningless forcing or no active plant management. - Keep
delta_time=3600.when using hourly AmeriFlux/EcoSIM climate forcing. - Ensure the greenhouse-gas forcing spans the requested simulation period. Historical-only
fatm_hist_GHGs_1750-2023.ncis not sufficient for future SSP runs. - If
forc_periodsrepeats a short forcing window for spinup, make that intentional and document it in the run notes.
Validation
Run:
python .agents/skills/ameriflux-namelist-generator/scripts/create_ameriflux_namelist.py --site-id US-Var --dry-run
Then inspect the output and verify:
case_namematches the site/case.grid_file_in,pft_mgmt_in, andclm_hour_file_inpoint to the intended NetCDF files.forc_periodsuses valid years available in the climate forcing.hist_fincl1,hist_mfilt, andhist_nhtfrqmatch the intended output diagnostics.