Skip to content

bioepic-data/ecosim-agent / .agents/skills/ameriflux-namelist-generator

ameriflux-namelist-generator

Unverified

Create 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

  1. Identify the AmeriFlux site_id such as US-Ha1, US-MMS, or US-Var.
  2. Confirm that site artifacts exist. Prefer:
    • result/<SITE_ID>/<SITE_ID>_ecosim_grid.nc
    • result/<SITE_ID>/<SITE_ID>_ecosim_climate_<first>-<last>.nc (climate files carry their forcing years)
    • result/<SITE_ID>/<SITE_ID>_pft_mgmt.nc
    • result/<SITE_ID>/<SITE_ID>_ecosim_site.json Then search result/, inputs/, data/, and the repository root.
  3. 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, or unified-ameriflux-extractor.
  4. 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
  1. If writing the namelist into an EcoSIM run directory, pass --run-dir /path/to/run_dir so input paths are written relative to the run directory, matching the Blodgett example.
  2. 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-year after 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 both start_date and stop_n from this schedule; see the chronology contract. Retain other ecosystems' existing chronology unless requested otherwise.
  3. Validate that referenced files exist from the namelist execution directory.
  4. 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-name for a model case label different from the site ID.
  • Use --grid-file, --pft-mgmt-file, and --climate-file when auto-discovery chooses the wrong artifact.
  • Use --force-start-year, --spinup-end-year, --force-end-year, --spinup-cycles, --start-year, and --stop-n to control chronology.
  • Use --lignification true for lignified root experiments; default is .false..
  • Use --micpar-file to include a micpar_file_in line.

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.nc is not sufficient for future SSP runs.
  • If forc_periods repeats 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_name matches the site/case.
  • grid_file_in, pft_mgmt_in, and clm_hour_file_in point to the intended NetCDF files.
  • forc_periods uses valid years available in the climate forcing.
  • hist_fincl1, hist_mfilt, and hist_nhtfrq match the intended output diagnostics.
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall