bioepic-data/ecosim-agent / .agents/skills/ameriflux-namelist-generator
ameriflux-namelist-generator
UnverifiedCreate EcoSIM Fortran namelists, run folders, and sourced HTML site guides from site-specific grid, plant management, climate forcing, and greenhouse-gas inputs. Use when preparing or updating an EcoSIM namelist, run folder, run directory, or runnable site case for AmeriFlux or FLUXNET sites.
AmeriFlux 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.
Include a self-contained <SITE_ID>.html site guide at the site-folder root
(alongside input/ and run_dir/), using the user's requested destination.
Explain the site setting, climate, soils, vegetation, management history, and
local case using cited field records and metadata. Distinguish observations
from model assumptions and report the actual validation and simulation status.
Follow the site-guide step in the run-folder workflow; the assembly script
preserves an existing guide but does not author its content.
Document the actual grid selected by the namelist in the guide, including layer geometry, soil properties with units, initialization and hydrologic boundaries, parameter sources/defaults, and the latest conflict-check result. Use the grid-documentation checklist in the site-guide workflow; a general soil description or benchmark comparison alone does not document the active grid.
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 \
--ecosystem-type grassland --observation-end-year 2021 \
--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. - Classify land cover from site evidence before choosing chronology. For
grasslands (
GRA) and croplands (CRO), use the first five complete forcing years four times (20-year spinup), then run the full transient once through the last available observation year. Pass--observation-end-yearafter checking actual observation records; do not substitute the forcing endpoint. The generator reads staged site JSON for land cover, or accepts--ecosystem-type grassland|cropland|other. If metadata are absent, supply the classification explicitly. Derive bothstart_dateandstop_nfrom this schedule; see the chronology contract. Retain other ecosystems' existing chronology unless requested otherwise. - Validate that referenced files exist from the namelist execution directory.
- For a run-folder request, create or refresh the site-root HTML guide after assembly and update its status after the smoke run, including when blocked.
When merging management sources or changing chronology, follow the run-folder workflow's Management Coverage and Code Evaluation step. Cover every selected year, retain provenance, and check the actual reader/process semantics before calling the inputs ready. Carry-forward is an explicitly authorized gap policy, not an automatic substitute for missing observations.
Common Overrides
Before a full run intended for comparison with observations, use
ecosim-evaluation-output-check
to verify the required history fields in an isolated one-year run and carry the
reviewed output selections into the production namelist. Keep missing mappings
visible. This output check complements the required two-year plant-trait smoke
test; it does not replace it or establish scientific model performance.
- 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.
Mandatory input gate
Use the shared case preflight before declaring assembly complete and before every smoke, evaluation-output or full/continued run. The supplied assembly/run scripts enforce it; a previous report cannot substitute for a fresh check after input or namelist changes. Errors and unsupported active configurations block; scientific evidence warnings remain visible and still require the sourced site review.
For experiments that change an existing case, follow experiment isolation and parameter identity. Honor an explicitly named PFT file, distinguish a filename change from changed parameter values, and retain historical validation provenance.
Validation
Run:
python .agents/skills/ameriflux-namelist-generator/scripts/create_ameriflux_namelist.py --site-id US-Var --dry-run
For grasslands/croplands, include --observation-end-year in the 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |