Imported from lzwei196/KISS---Knowledge-Infrastructure-for-Scientific-Simulation (models/DayCent/SKILL.md). Install upstream with npx skills add lzwei196/KISS---Knowledge-Infrastructure-for-Scientific-Simulation --skill DayCent. Copyright stays with the author.

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document. If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation, or hand-coded approximation in place of the real model. Doing so produces scientifically invalid results and defeats the purpose of the KI.

Before starting, run: python preflight_check.py (in this KI directory) to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong (model crashes, wrong output, unexpected values), follow this order. Do NOT skip steps or write debug scripts:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — Check the model's own documentation (PDF manual, README, official examples) for expected input formats, variable names, and units
3. Find working examples — Look in outputs/ for previous successful runs of this model, or check if the model ships with test/example data
4. Fix the tool — Now that you know what "correct" looks like, make targeted fixes

Resist the urge to write diagnostic/debug Python scripts. The answers are almost always in the official docs and working examples, not in reverse-engineering the binary.

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 9 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

4 public tools; _-prefixed helpers and packaging files excluded.

DayCent — Daily Century Soil Organic Matter, Plant Production, and Trace-Gas Model

1. Model Identity

2. What This Model Does

DayCent (Daily-DAYCENT, also DDcentEVI) is the daily time-step version of the Century ecosystem model. It simulates plant production, soil organic matter dynamics, water balance, soil temperature, and trace-gas fluxes (N2O, NO, CH4, CO2) for cropping, grassland, and savanna ecosystems. It is the de-facto reference model for U.S. and global soil greenhouse-gas inventories (USDA, IPCC inventory teams) and has been in continuous development at Colorado State University / NREL for over three decades.

KNOWN GAP — forest ecosystems. DayCent supports a TREE submodel in principle, but the public WoosterExampleLinux distribution used by this KI ships a zero-byte tree.100 and no forest .sch template. Running DayCent as a forest model therefore requires a tree.100 obtained from CSU NREL separately. If your task asks for DayCent at a forest flux site (e.g. DE-Tha Norway spruce, US-Ha1, US-UMB), you cannot complete it with KI artifacts alone — you must either (a) obtain the full DayCent distribution with a populated tree.100 from CSU NREL, or (b) substitute a grassland (GRASS/GRAS1) parameterisation as a coarse surrogate and clearly flag this limitation in the run report. Do not fabricate tree parameters.

Version: DDcentEVI revision 491 (trunk, 2023-07-10) Binary type: ELF 64-bit, statically linked, x86-64 Source: Linux_Version_491/DDcentEVI_rev491 (precompiled in the distribution) Companion binary: DDlist100_rev491 — extracts user-selected variables from .bin archives into delimited .lis text tables.

DayCent does NOT compile from source in the standard distribution — the upstream release ships precompiled, statically-linked Linux and Windows binaries. The Fortran/C source is held separately by the CSU NREL group; this KI works with the public binary distribution.

Why DayCent (vs. raw Century or other ESMs)

• Daily time step: required for trace-gas modelling (N2O pulses after fertiliser, nitrification/denitrification, NO/N2O/N2 partitioning).
• Soil layer water + temperature: explicit soil profile (1-D bucket plus Parton-Hartman temperature solver), enabling realistic plant water stress and N transformations.
• Tested decomposition pools: the Century 5-pool SOM scheme (active, slow, passive surface, structural, metabolic) calibrated against decades of long-term experiment SOC data (Wooster OH, Sanborn MO, Rothamsted, etc.).
• Used by U.S. EPA and USDA for the GHG inventory of agricultural lands, so its outputs are the operational reference for U.S. cropland N2O.

3. Input Requirements

Exact machine-readable input/output shapes live in docs/format_spec.yaml (projected from dag.yaml plus diagnostics/triplets.yaml). Regenerate that spec after changing the dag or triplets; do not hand-edit the generated spec.

DayCent inputs are Century-style site files, DayCent-specific physical site parameters, multi-layer soil hydraulic profiles, daily weather, management schedules, and output toggles. The detailed file reference below gives the fixed-format expectations and common unit traps.

Pipeline (DayCent canonical 3-step run)

DayCent simulations almost always follow the equilibrium → base history → treatment pattern, taken directly from the WoosterExampleLinux reference that ships with the distribution.

The three-stage spin-up scheme is essential: DayCent SOM pools take centuries to equilibrate, and the ACEQ (Adaptive Century Equilibrium) block in a .sch file lets the model stop when pools converge.

4. Build Instructions

The model is shipped as a precompiled statically-linked ELF binary; no build step is required on a modern Linux x86-64 host:

# Verify the binary
file source/repo/Linux_Version_491/DDcentEVI_rev491
# ELF 64-bit LSB executable, x86-64, statically linked

# Make executable (it should already be)
chmod +x source/repo/Linux_Version_491/DDcentEVI_rev491
chmod +x source/repo/Linux_Version_491/DDlist100_rev491

# Smoke test
./DDcentEVI_rev491
# Should print: DAILYDAYCENT SOIL ORGANIC MATTER and TRACEGAS MODEL
#               trunk, 2023-07-10, revision 491

If you obtained DayCent source instead of the binary distribution, the build is controlled by a Makefile in the C source tree and depends on gfortran plus a C compiler (gcc/clang). The public release ships only binaries.

Quick start (Wooster example)

cd source/repo/WoosterExampleLinux
ln -sf ../Linux_Version_491/DDcentEVI_rev491 .
ln -sf ../Linux_Version_491/DDlist100_rev491 .

# 1) Equilibrium spin-up (ACEQ converges around year 750-1000)
cp no_outfiles.in outfiles.in
./DDcentEVI_rev491 -s wooster_eq -N eq

# 2) Base history (1900-1961 historical management without treatment)
./DDcentEVI_rev491 -s wooster_base -e eq -N base

# 3) Treatment run (corn-soy no-till from 1962)
cp few_outfiles.in outfiles.in
./DDcentEVI_rev491 -s wooster_cb_nt_blk1 -e base -N cb_nt

# 4) Extract variables to .lis text table
./DDlist100_rev491 cb_nt wooster few_outvars.txt
# Produces wooster.lis with columns from few_outvars.txt

Setting up a new FLUXNET site (site-adaptation recipe)

The WoosterExampleLinux pipeline is written for a corn-soy rotation in Ohio. To port it to an arbitrary FLUXNET tower, copy the example directory and edit the site-specific inputs — do not rewrite the binaries or the management history. The minimum-edit path is:

1. Copy the example as a template.

   cp -r source/repo/WoosterExampleLinux workdir/de_tha
   cd workdir/de_tha

2. Build the weather file with convert_forcing_to_daycent.py --source fluxnet. This is preferred over CMFD/MSWX/NASA-POWER for FLUXNET tasks because every FLUXNET2015 site CSV carries TA_F, P_F, SW_IN_F — the exact variables the .wth needs — and it works offline.

   python tools/convert_forcing_to_daycent.py      --source fluxnet      --fluxnet-csv KISSPATH_ROOT/.../sites/DE-Tha/FULLSET_DD.csv      --year-start 1996 --year-end 2014      --out workdir/de_tha/de_tha.wth

3. Edit <site>.100 (rename wooster_site.100 → de_tha_site.100):

   • Update sitlat / sitlng to the tower coordinates (DE-Tha: 50.96, 13.57).
   • Replace the 12 monthly PRECIP(1..12), TMN2M(1..12), TMX2M(1..12) with monthly climatology computed from the .wth you just built. A 1-liner: awk '{m=$2; p[m]+=$7; n[m]+=1} END {for(i=1;i<=12;i++) print i, p[i]/n[i]*30.44}' de_tha.wth gives monthly PRECIP in cm.
   • Update sand / silt / clay / bulkd / ph from the site soil metadata (for FLUXNET sites, the AUXMETEO.csv or the site's ancillary CSV).
   • Do NOT change the SOM initial pools — the equilibrium run will overwrite them. Keep the Wooster defaults as a starting point.

4. Rebuild soils.in with tools/convert_soil_to_daycent.py using HWSD at the tower lat/lon (or the site soil CSV if available).

5. Edit the schedules (*.sch):

   • In <site>_eq.sch / <site>_base.sch / <site>_treatment.sch, set wooster_site.100 → de_tha_site.100 and wooster_prism.wth → de_tha.wth.
   • Replace the CROP CORN / LAST / CROP SOYB / LAST blocks with the ecosystem at the tower. For a cropland or grassland, pick the appropriate crop.100 entry (e.g. GRASS, W1, C3-GR) and update the schedule years. For a forest site, see the KNOWN GAP above — without a populated tree.100 you must either substitute grass or stop. Do not invent tree parameters.
   • Adjust the simulation year block (1 2014 ...) to match the target validation period.

6. Run the 3 stages exactly as in the Wooster quick-start, swapping in the new file names.

7. Extract daily GPP by parsing summary.out for the cprodc column (see the DayCent → FLUXNET variable map below).

This is a deliberately manual port — DayCent assumes the user has made site-specific decisions (crop choice, rotation, fertilisation, phenology) that cannot be auto-generated from the FLUXNET metadata alone. Document every departure from the Wooster template in a CHANGES.md next to the workdir.

Input files reference

DayCent input files are ASCII fixed-format Century-100 style files with parameter values in column 1 and a label in column 2.

<site>.100 — site climate, soil, and SOM initial conditions

Sections: *** Climate parameters (PRECIP(1..12), TMN2M(1..12), TMX2M(1..12)), *** Site and control parameters (sitlat, sitlng, sand, silt, clay, rock, bulkd, nlayer, nlaypg, drain, basef, stormf, swflag, ph, micosm, sitpot, ...), *** External nutrient input parameters (epnfa, epnfs), and SOM initial pools (som1ci, som2ci, som3ci, strucc, metabc, etc.). The Linux_Version_491 example wooster_site.100 is the canonical reference template.

Units (from Wooster site file): PRECIP in cm/month, TMN2M/TMX2M in °C, sand/silt/clay as fractions (0–1), bulkd in g/cm³, sitlat/sitlng in decimal degrees.

sitepar.in — site physical parameters (DayCent-specific)

Free-format key/value with a slash separator. Defines elevation (m), slope/aspect (deg), albedo, vegetation reflectivity, snow flag, N2O nitrification adjustment, solar-radiation surface transmission per month, hydraulic damping, etc. The hours_rain parameter tells the model how many hours each daily precip event lasts — critical for infiltration vs runoff partitioning.

soils.in — multi-layer soil hydraulic profile

One row per layer. Columns (no header):

1. Top depth (cm)
2. Bottom depth (cm)
3. Bulk density (g/cm³)
4. Field capacity (vol/vol)
5. Wilting point (vol/vol)
6. Evaporation coefficient
7. Root fraction in layer
8. Sand fraction (0–1)
9. Clay fraction (0–1)
10. OM fraction (0–1, sometimes column 9 is OM and 10 is something else)
11. Saturated hydraulic conductivity (cm/sec)
12. pH

The DayCent_Manual_full_02.06.2024.pdf documents the exact column meaning by revision — read it before changing soil columns. Some columns are interpreted differently between rev 470 and rev 491.

<weather>.wth — daily weather

Columns 1-7: day-of-month, month, year, day-of-year, Tmin (°C), Tmax (°C), precipitation (cm/day). Optional columns 8-9: solar radiation (langleys/day), relative humidity (%), wind (m/s) — only used if usexdrvrs=1 in sitepar.in.

Trap: precipitation is in cm/day, NOT mm/day. CMFD/MSWX/NASA-POWER all return mm/day, so the converter MUST divide by 10.

<schedule>.sch — model schedule

Defines simulation period, starting/initial system, climate file, and the list of timed management events (CROP, FERT, HARV, GRAZ, FRST, LAST, SENM, FIRE, TREE, IRRI, OMAD, CULT, ACEQ, ...). The ACEQ event triggers adaptive equilibrium termination. LAST ends the growing season for a crop block.

outfiles.in — output channel toggles

Lists 28 possible output files, one per line, with a 0/1 toggle and the filename. The Wooster example provides three presets:

• no_outfiles.in — everything off (use during equilibrium)
• few_outfiles.in — bio.out, harvest.csv, summary.out, year_summary.out
• outfiles.in — full output (large files)

5. Execution

DDcentEVI_rev491 [-s] schedule-file [options]
  -s  schedule file  (required)
  -e  old-binary-file to extend  (e.g. -e eq for base history)
  -i  old-binary-file providing initial conditions only
  -n  new-binary-output-file (optional)
  -N  binary-output-file (overwrite allowed)
  -t  list-file (.lis) to be written
  -v  output variable list  (file like few_outvars.txt)
  -d<x>  delimiter: -dt tab, -dc comma
  -l  directory to search for library .100 files
  --site  site file replacing file in schedule
  --sitdbg  debug soil/sitepar input echo

Typical usage chains three calls (-N writes the eq binary, then -e eq extends it through history, then -e base extends through treatment).

6. Output Description

This section restates dag.yaml; if this section and the dag disagree, the dag wins. The dag's validation_rank: 1 variable is the headline output by which the KI is judged:

cprodc (daily net C production, GPP proxy) — Daily net C production reported in summary.out; the closest DayCent variable to daily GPP for cropland/grassland (an approximation, not true gross primary productivity). (gC/m2/day)

Other dag outputs named by this KI are: n2o_emission, no_emission, ch4_flux, co2_heterotrophic, nee, reco, aboveground_biomass (aglivc), crop_yield (cgrain), soil_organic_carbon (somsc), soil_moisture_layers, soil_temperature_layers, and evapotranspiration / water_balance.

Output files

Extraction with DDlist100

./DDlist100_rev491 <bin-root> <out-prefix> <variable-list-file>
# Example: ./DDlist100_rev491 cb_nt wooster few_outvars.txt
# -> wooster.lis with columns from few_outvars.txt

The variable list file is one variable name per line (e.g. aglivc, bglivcj, bglivcm, somsc, agcprd, cgrain, fertot11). The full list of available variable names is in Documentation/DayCent_Manual_full_02.06.2024.pdf, section "List of Output Variables".

Mapping DayCent outputs to FLUXNET variables

When validating DayCent against eddy-covariance towers, use these mappings:

cprodc is output daily when summary.out is enabled (few_outfiles.in already switches it on). Grab it with a tiny post-run parser rather than running DDlist100 for daily GPP. The .lis alternative (agcprd + bgcprd summed over a day) is also valid but is harder to wire up for a daily comparison because the .lis tables are typically annualised.

7. Tool Inventory

Each tool follows the validate → process → validate pattern from the KDT v5.1 specification and imports shared utilities from ki_tools_common.

8. Unit Conversion Table

The table documents unit conversions that the DayCent pipeline uses or checks. Use docs/format_spec.yaml as the generated contract and the model's own input files/manual as the authority for file-level units.

Unit traps (READ BEFORE WRITING A FORCING CONVERTER)

Most common silent failure: leaving precipitation in mm/day. The model runs without error but the basin is 10× too wet, the crop drowns, soil moisture saturates, and SOM accumulates uncontrollably. Always validate mean annual precip in cm/year against a known reference for the site (Wooster: ~95 cm/yr, eastern Nebraska: ~75 cm/yr).

8c. Sign Conventions and Output Units

9. Diagnostic Triplets (Top 5)

Check diagnostics/triplets.yaml before debugging any failed or suspicious run. Do not duplicate the full corpus in this file; use these five real IDs as the fastest first scan.

10. Coupling Interfaces

DayCent is normally run as a standalone site model in this KI. Coupling work should bind to dag variables rather than ad hoc column names.

11. Validated Results

Primary — Wooster SOC (bundled example, coarse annual)

• Tier: real — compared against measured SOC at the Wooster OH long-term Corn-Soy no-till experiment (Lal et al., 1998; Mishra et al., 2010).
• Benchmark site: Wooster, Ohio (Wayne County, OH; ~40.78°N, 81.93°W).
• Observed values: SOC at 1962, 1971, 1980, 1992 = 3402, 4789, 3885, 4266 g C / m² (0–20 cm), reproduced from wooster_run_rev491_Linux.R shipped with the DayCent distribution.
• Metric: Pearson r and RMSE between simulated somsc and observed SOC at the four sample years.

Headline Dag Variable

The dag's rank-1 validation variable is cprodc (daily net C production, GPP proxy), unit gC/m2/day. Its dag description is: Daily net C production reported in summary.out; the closest DayCent variable to daily GPP for cropland/grassland (an approximation, not true gross primary productivity).

Performance Metrics — judged against the field's bar, not intuition

State pass/fail bars only from docs/validation_convention.yaml. Null bands in that file are written here as no cited threshold; do not replace them with remembered or generic cutoffs.

No validated numeric campaign result is embedded in this SKILL body for the rank-1 cprodc (daily net C production, GPP proxy) output. Run-level reports must compute achieved metrics from the task's observation set and judge them against docs/validation_convention.yaml; if the convention has no cited band for the metric, report no cited threshold instead of inventing one.

Data Replacement Tracking

Daily GPP at a FLUXNET cropland/grassland site

DayCent can be validated against eddy-covariance daily GPP at FLUXNET cropland or grassland towers (but see the KNOWN GAP above for forest sites). Reference workflow:

1. Build .wth with --source fluxnet pointing at the site's FULLSET_DD.csv.
2. Follow the site-adaptation recipe above to make <site>_*.sch, <site>_site.100, and soils.in.
3. Run eq → base → treatment with few_outfiles.in (produces summary.out).
4. Parse summary.out day-by-day; extract the cprodc column as daily GPP in g C m⁻² d⁻¹.
5. Align on date with the FLUXNET GPP_NT_VUT_REF column (filter out -9999 missing) and compute Pearson r, NSE, KGE over the overlap.
6. Judge the run only against cited bars present in docs/validation_convention.yaml. If a needed metric has no cited band, state no cited threshold; do not substitute a generic pass/fail cutoff. Check phenology (CROP/LAST dates) and N fertilisation schedule before retuning.

12. Parameter Selection by Region

Use physically informed site inputs, not generic calibration shortcuts. For cropland and grassland tasks, start from the WoosterExampleLinux schedule and edit site climate, soil, crop/grass parameterisation, rotation, fertilisation, and phenology to match the target. For forest tasks, the bundled public example does not include a populated tree.100, so a true forest DayCent run requires that upstream parameter library from CSU NREL or an explicitly reported grassland surrogate.

References

• Parton, W.J. et al. (1998). DAYCENT and its land-surface submodel. Ecological Modelling 109, 67–95.
• Del Grosso, S.J., Parton, W.J., Mosier, A.R., et al. (2001). Simulated interaction of soil C, N and N2O fluxes. Global Biogeochemical Cycles 15.
• Hartman, M., Parton, W.J., Del Grosso, S., et al. (2024). DayCent Model Reference Manual, revision 491. CSU NREL.
• Wooster long-term experiment SOC: Lal, R., Mahboubi, A.A., Fausey, N.R. (1994). Long-term tillage and rotation effects on properties of a central Ohio soil. SSSAJ 58, 517–522.

Provenance notes

This KI was generated by KDT v5.1 from the public DayCent v491 release. The binary was not built from source — DayCent source is not bundled with the public release. If you need to modify the model itself, contact the CSU NREL group for the source distribution.