Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/DNDC/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill DNDC. 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.

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, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — The model's own documentation for expected formats/units
3. Find working examples — Check outputs/ or the model's shipped test data
4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

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.

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

DNDC (DNDCv.CAN) — DeNitrification-DeComposition Model Knowledge Infrastructure

Package: hydrocraft-dndc-crop v1.0.0 Model: DNDCv.CAN v9.6.0 — Canadian branch of DNDC95 Developers: Brian Grant & Ward Smith, Agriculture and Agri-Food Canada Source: https://github.com/BrianBGrant/DNDCv.CAN (binary only; source code proprietary) Domain: Crop growth, soil carbon/nitrogen cycling, greenhouse gas emissions Last updated: 2026-03-28 Stats: 4 tools | 7 skill documents | 18 diagnostic triplets | ~2,000 lines of validated Python

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER.

Data Validation Reference: See data_ki/CMFD/SKILL.md for CMFD unit documentation and known traps. See data_ki/FLUXNET/SKILL.md for eddy covariance flux observations.

Overview

DNDCv.CAN (DeNitrification-DeComposition, Canadian version) is a process-based biogeochemical model that simulates carbon and nitrogen cycling in agricultural ecosystems at the field scale on a daily time step. It is derived from the original DNDC95 codebase (August 2015, University of New Hampshire) and has been independently developed by Agriculture and Agri-Food Canada for Canadian cropping systems.

What DNDC simulates:

• Crop growth and development (phenology, biomass accumulation, C/N partitioning)
• Soil organic carbon decomposition and turnover (multi-pool model)
• Nitrogen cycling (mineralization, nitrification, denitrification, leaching, volatilization)
• Greenhouse gas emissions (N2O, NO, CO2, CH4 from soil processes)
• Soil water balance (infiltration, drainage, tile drainage, evapotranspiration)
• Soil temperature profile (freezing/thawing, frost dynamics, snow cover)
• Ammonia volatilization from fertilizer and manure
• Tillage effects on soil mixing and residue incorporation
• Manure and organic amendment decomposition (including biosolid C pools)
• Cover crop dynamics and frostkill sensitivity
• Preferential flow through soil macropores and cracking

Key architectural features:

• Windows PE32 executable (DNDC95.exe), no source code publicly available
• All inputs consolidated into a single .dnd text file per site
• Climate forcing via daily text files with 7 meteorological variables
• Soil profile always modeled to 200 cm (2 m) depth
• Batch execution via command-line interface with batch file listing
• Output written to Result/Record/ directory tree

What distinguishes DNDCv.CAN from other DNDC variants:

• Enhanced tile drainage simulation (mechanistic approach)
• Improved snow/frost dynamics and winter-spring N2O burst modeling
• Biosolid carbon pool for organic amendments
• pH-sensitive NH4:NH3 equilibrium
• RUE (radiation use efficiency) sensitivity improvements for crop growth
• Inversion tillage conceptualization
• Dynamic soil layer depth capability
• Preferential flow toggle with soil cracking/retreat sensitivity

6. Output Description (from dag.yaml)

This section restates the KI's dag.yaml. If this section and dag.yaml ever disagree, dag.yaml wins.

Headline output (validation_rank: 1):

SOC_stock_and_change -- Soil organic carbon stock and inter-annual change / sequestration (kgC/ha (stock), kgC/ha/yr (change))

Other dag outputs:

crop_grain_yield, crop_N_uptake, N2O_emission, NO_emission, N2_emission, NH3_volatilization, CO2_soil_respiration, CH4_flux, NO3_leaching, water_balance_components, soil_temperature_profile, soil_water_WFPS_and_water_table.

Agents must bind observations and scoring targets by these dag variable names, not by informal output labels. The dag variable SOC_stock_and_change is the rank-1 variable this KI is judged by.

Installation

Windows (Native)

DNDCv.CAN is distributed as a zip archive containing the PE32 executable and supporting files. No installation is required beyond extraction.

1. Download DNDC-Nov2024.zip from GitHub repository
2. Extract to a working directory (e.g., C:\DNDC\)
3. Contents:
   DNDC95.exe          — Main executable (PE32 Windows binary)
   *.dll               — Optional DLL files (DNDC-OptionalDLL.zip)
   Example .dnd files  — Sample input configurations

Linux (via Wine)

Since DNDC95.exe is a Windows PE32 binary, it must be run via Wine on Linux.

# Install Wine
sudo apt install wine64 wine32

# Verify Wine can run the binary
wine --version
file DNDC95.exe    # should report: PE32 executable (GUI) Intel 80386

# Test execution
wine DNDC95.exe -s batch_file.txt -daily 0 -output ./output/

# For headless batch execution (recommended)
export WINEDEBUG=-all
wine start /wait DNDC95.exe -s batch_file.txt -daily 0 -output ./output/

Directory Structure

DNDC_workspace/
├── DNDC95.exe              # Model executable
├── *.dll                   # Optional DLLs
├── batch_file.txt          # Batch run configuration
├── inputs/
│   ├── site1.dnd           # Combined input file (site+climate+soil+crop+mgmt)
│   ├── site2.dnd           # One .dnd per simulation site
│   └── ...
├── climate/
│   ├── climate_station1.txt  # Daily climate forcing
│   └── ...
├── soil/
│   └── profiles.spf        # Soil profile definitions
└── Result/
    └── Record/
        ├── Site/           # Single-run outputs
        └── Batch/          # Batch-run outputs

Pipeline (7 Stages)

Command-Line Execution

Single Run

The GUI version (DNDC95.exe without flags) opens an interactive Windows application. For automated batch processing, use the command-line interface:

# Windows
start /wait DNDC95.exe -s batch_file.txt -daily 0 -output output_dir/

# Linux (Wine)
wine DNDC95.exe -s batch_file.txt -daily 0 -output output_dir/

CLI Flags

Batch File Format

The batch file is a plain text file with the following structure:

2                            # Number of .dnd files to run
inputs/site1.dnd             # Path to first .dnd file
inputs/site2.dnd             # Path to second .dnd file

Line 1: integer count of simulations. Lines 2+: one .dnd file path per line (relative or absolute).

Output Directory Structure

Result/Record/Batch/         # Batch run outputs
  site1_daily.csv            # Daily time series
  site1_annual.csv           # Annual summary
  site1_crop.csv             # Crop growth outputs
  site1_ghg.csv              # Greenhouse gas emissions

Input File Formats

DND File (.dnd) — Master Input

The .dnd file is a single text file containing ALL simulation parameters organized into named sections. Each section begins with a keyword header and contains key-value pairs or tabular data. A single .dnd file fully defines one simulation site.

Major sections:

Climate File — Daily Forcing

Daily text file with space or tab-delimited columns. The climate format type (specified in the .dnd file) determines the column layout.

Climate Format Type 5 (most complete, recommended):

Jday  MaxT   MinT   Prec     Radiation  WindSpeed  Humidity
1     -5.2   -12.8  0.00     4.35       3.2        72.0
2     -3.1   -10.5  0.15     5.12       2.8        68.5
3     -1.8   -8.3   0.00     6.88       4.1        65.0
...
365   -4.5   -11.2  0.08     3.92       3.5        74.0

All Climate Format Types:

Climate Variable Specifications:

Soil Profile File (.spf)

The .spf file defines soil layer properties for the 200 cm profile.

Format: One row per soil layer, space-delimited.

Example .spf layer:

0.10  1.35  0.025  4  6.5  0.65  0.30  0.49  0.005  0.22

DNDC Texture Classes:

8. Unit Conversion Table

Exact I/O shapes live in docs/format_spec.yaml; conversion traps are also tracked in diagnostics/triplets.yaml. This table is the high-level unit checklist an agent should use before assembling .dnd files or interpreting headline outputs.

Unit Trap Table

These are the most dangerous unit conversion pitfalls when preparing DNDC inputs. All unit errors are silent -- DNDC will run without error messages but produce physically meaningless results.

The single most common error: Precipitation in mm instead of cm. This causes a 10x overestimation of water inputs, leading to waterlogged soils, unrealistic drainage, excessive denitrification, and inflated N2O emissions.

Crop Library

DNDC includes parameterizations for 18+ crop types. Each crop is defined by growth parameters, biomass partitioning fractions, C/N ratios, and thermal requirements.

Key crop growth parameters in the DND file:

• Maximum biomass production (kgC/ha)
• Biomass fraction to grain, leaf, stem, root
• C/N ratio of grain, stover, root
• Thermal degree days for maturity
• Base temperature for growth (deg C)
• Water demand coefficient
• N fixation index (for legumes, 0-1)
• Root depth (fraction of soil profile)
• Root respiration: maintenance and new growth coefficients
• Above-ground respiration: maintenance and new growth coefficients

Common Parameters Reference

Site Parameters

Soil Initial Conditions

Fertilizer Parameters

Tillage Parameters

Tile Drainage Parameters

Key Output Variables

Tool Reference

convert_climate_to_dndc.py

Converts global meteorological datasets to DNDC daily climate format (type 5).

Key conversions performed:

• Precipitation: mm/day to cm/day (divide by 10)
• Radiation: W/m2 to MJ/m2/day (multiply by 0.0864)
• Temperature: Kelvin to deg C (subtract 273.15) if needed
• Humidity: fraction to percent (multiply by 100) if needed
• Validates: Jday sequence 1-365/366, MaxT >= MinT, Prec >= 0, Radiation >= 0

Supported input sources: NASA POWER, ERA5, CMFD, MSWX, Daymet, GridMET, custom CSV.

convert_soil_to_dndc.py

Converts soil database information to DNDC soil profile format.

Key conversions performed:

• SOC from percent or g/kg to kgC/kg soil
• Bulk density validation (1.0-2.0 g/cm3 range)
• Texture classification to DNDC texture ID (1-12)
• Hydraulic conductivity to m/hr
• Field capacity and wilting point to WFPS units
• Fills 200 cm profile, extrapolating deeper layers if source data is shallow

run_dndc.py

Assembles batch configuration and executes DNDC95.exe.

Features:

• Auto-detects Windows vs Linux (Wine) execution environment
• Generates batch file from list of .dnd file paths
• Monitors execution with timeout protection
• Captures Wine/Windows stderr for error diagnosis
• Validates output directory creation and file generation

parse_dndc_output.py

Parses DNDC output files into structured pandas DataFrames and CSV files.

Features:

• Reads batch output from Result/Record/Batch/ or single-run from Result/Record/Site/
• Extracts annual summaries: yield, GHG emissions, N balance, water balance, SOC
• Extracts daily time series (if -daily 1 flag was used)
• Computes derived metrics: yield-scaled N2O, N use efficiency, water use efficiency
• Generates multi-site comparison tables for batch runs

Version History (DNDCv.CAN)

Known issues (v9.5.6+):

• Inhibitor products are globally active during their parameterized timing (not per-event)
• Dynamic layer depth can break simulation if set too small (minimum 1 cm)

Diagnostic Triplets Summary

See diagnostics/triplets.yaml for the full set. Key entries:

11. Validated Results

The body validation campaign is pending in this SKILL body. Do not invent calibration, validation, or full-period metric values. When judging model skill, use docs/validation_convention.yaml for the cited convention bars and dag.yaml for the target variable identity.

Rank-1 validation target from dag.yaml:

Performance Metrics -- Convention Bars

These bars restate the KI convention facts. For SOC_stock_and_change, no extracted convention bar is stated in this body; consult docs/validation_convention.yaml before assigning a verdict for the rank-1 variable.

The extracted convention facts include duplicate crop_grain_yield pbias and nrmse rows with the same bands and citations shown above. Treat those duplicates as the same cited bars unless docs/validation_convention.yaml is changed and the KI projections are regenerated.

Data Replacement Tracking

Quick Start

# 1. Set up workspace
mkdir -p dndc_workspace/inputs dndc_workspace/climate dndc_workspace/Result
cp DNDC95.exe dndc_workspace/

# 2. Prepare climate file (type 5 format, precipitation in CM)
python tools/convert_climate_to_dndc.py \
    --input forcing_data.csv \
    --output dndc_workspace/climate/mysite_2020.txt \
    --source nasa_power \
    --year 2020

# 3. Prepare soil and assemble DND file
python tools/convert_soil_to_dndc.py \
    --input soil_data.csv \
    --lat 45.5 --lon -75.5 \
    --output dndc_workspace/inputs/mysite.dnd

# 4. Create batch file
echo "1" > dndc_workspace/batch_file.txt
echo "inputs/mysite.dnd" >> dndc_workspace/batch_file.txt

# 5. Run DNDC
cd dndc_workspace
wine DNDC95.exe -s batch_file.txt -daily 0 -output Result/

# 6. Parse outputs
python tools/parse_dndc_output.py \
    --input Result/Record/Batch/ \
    --output results_summary.csv

Coupling Points

• Climate forcing: ERA5, NASA POWER, CMFD, MSWX, Daymet, GridMET -- convert to type-5 format
• Soil data: HWSD, SoilGrids, SSURGO/SDA, ISRIC -- convert to DNDC soil profile
• Yield comparison: Statistics Canada CANSIM, USDA NASS, FAO FAOSTAT
• GHG validation: Eddy covariance (N2O, CO2), static chamber measurements
• Water balance: Lysimeter data, tile drain monitoring, soil moisture sensors
• Multi-model comparison: DNDC has been benchmarked against DayCent, EPIC, RZWQM2, APSIM, Holos