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

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

3. Input Requirements

Exact machine-readable input and output shapes live in docs/format_spec.yaml. That file is projected from dag.yaml and diagnostics/triplets.yaml; regenerate it after changing either source, and do not hand-edit the projected spec.

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER. Then convert to DSSAT .WTH format using this KI's tool: tools/s2_weather_prep/convert_cmfd_to_wth.py

Soil properties

Data Sources: Use from ki_tools_common.soil_utils import lookup_hwsd for soil properties.

Data Validation Reference: See data_ki/CMFD/SKILL.md for CMFD unit documentation and known traps. See data_ki/HWSD/SKILL.md for soil property documentation.

DSSAT-CSM v4.8.5 — Knowledge Infrastructure

Model: DSSAT-CSM (Decision Support System for Agrotechnology Transfer, Cropping System Model) Version: 4.8.5, Build 41 Domain: Crop simulation — multi-crop growth, development, and yield Language: Fortran 90 Binary: KISSPATH_HOME/DSSAT/build/bin/dscsm048 License: Research/non-commercial Repository: https://github.com/DSSAT/dssat-csm-os

1. Model Identity

2. What This Model Does

Overview

DSSAT simulates crop growth, development, and yield for 24+ species (wheat, maize, rice, soybean, sorghum, millet, cotton, etc.) under varying weather, soil, and management conditions. It uses process-based physiology (photosynthesis, phenology, soil water balance, N/P dynamics) driven by daily weather data and management schedules.

Key advantage: Most detailed crop model in HydroCraft — 50+ diagnostic triplets, 9 pipeline stages, Chinese cultivar library with 42 calibrated varieties.

6. Output Description

Source of truth: dag.yaml. The dag is the model identity for outputs: each observable output's var, unit, description, validation rank and observability live there. This section restates the dag facts already extracted for the reader; if this section and dag.yaml ever disagree, dag.yaml wins.

Headline output (the dag's validation_rank: 1 variable — the one this model is judged by):

HWAM (harvested grain yield at maturity, dry) — Dry grain/seed yield at physiological maturity per treatment - the canonical end-of-season yield variable. (kg/ha)

Other dag outputs named for this KI:

4. Build Instructions

DSSAT-CSM is already built for this KI. Verify the local binary/package/data before any run:

python preflight_check.py

If the binary must be invoked directly, use the existing local build: KISSPATH_HOME/DSSAT/build/bin/dscsm048.

5. Execution

Binary Location & Execution

ALWAYS use dssat_workdir_setup.py — NEVER set up DSSAT files manually.

import sys
sys.path.insert(0, "KISSPATH_KI_ROOT/DSSAT/knowledge_infrastructure/tools")
from dssat_workdir_setup import create_workdir, run_dssat, parse_summary

# Step 1: Create workdir (handles all 6 Fortran pitfalls automatically)
workdir = create_workdir(
    crop="MZ",                    # MZ=maize, WH=wheat, SB=soybean, RI=rice
    cultivar="IB0001",            # From genotype library (see Chinese Cultivar Library below)
    weather_file="path/to.WTH",   # DSSAT .WTH format weather file
    soil_id="IBMZ910014",         # DSSAT soil profile ID
    lat=32.625, lon=116.375,
    planting_date=80150,           # YYDDD format (year 80, DOY 150) or "YYYY-MM-DD"
    start_year=1980, end_year=1985,
    output_dir="/tmp/dssat_run",
)

# Step 2: Run DSSAT
result = run_dssat(workdir)
print(f"Success: {result['success']}")

# Step 3: Parse results
summary = parse_summary(workdir)
for rec in summary:
    print(f"Yield: {rec['HWAM']} kg/ha, Biomass: {rec['CWAM']} kg/ha")

What dssat_workdir_setup.py handles (6 known pitfalls):

Raw binary (only if you know what you're doing):

cd /path/to/working_directory
KISSPATH_HOME/DSSAT/build/bin/dscsm048 B DSSBatch.v48

7. Tool Inventory

Pipeline Stages

Additional tools: convert_cmfd_to_wth.py (CMFD → .WTH conversion), convert_hwsd_to_sol.py (HWSD → SOIL.SOL, 2-layer), and convert_soilgrids_to_sol.py (SoilGrids → SOIL.SOL, 6-layer, global coverage — preferred for new simulations).

Soil tool selection guide:

convert_soilgrids_to_sol.py advantages: 6 depth layers (vs 2), Saxton-Rawls 2006 PTF (vs 1986), direct bdod from SoilGrids, depth-varying SOC/pH, Mollisol BD correction for NE China black soils. Uses KISSPATH_DATA/soilgrids_global/ (global) with China-optimised fallback to KISSPATH_DATA/soilgrids/.

Stages 1-7 can run in parallel — they each write a section of the FileX or prepare external files. Stage 8 depends on all of 1-7. Stage 9 depends on 8.

Stage validators are now CLI-invocable (they used to require editing a module-level global, which is why running them straight from the shell exited 1):

python tools/s1_experiment_design/validate_filex_structure.py  /path/EXP0001.MZX
python tools/s2_weather_prep/validate_weather_file.py          /path/SITE0001.WTH
python tools/s3_soil_setup/validate_soil_profile.py            /path/SOIL.SOL

Stage 7 — management is a create_workdir(**management_kwargs) dict (NO tools/s7_* files)

tools/s4..s7 are EMPTY directories; every management decision is a keyword to create_workdir(). Source them from data, not from the defaults:

Trap (fixed 2026-08-10): before this, irrigation_events was accepted, documented and then silently discarded, and IRRIG was hard-wired to N for every non-rice crop — an irrigated site ran as dryland with no error. Also, fert_n from NPKGRIDS is a float and used to crash FileX generation; and convert_cmfd_to_wth.py threw away a completed multi-minute extraction if --output's directory did not exist yet.

GDHY (--obs gdhy) = point_time_series — expect a large POSITIVE PBIAS

validate_yield_timeseries.py --obs gdhy tags point_time_series (valid families [temporal_pattern_match, magnitude_accuracy, ranking_quality], determining metric pbias), so NSE/KGE/r/PBIAS are ALL gate-valid — unlike the FAOSTAT case below. It also writes scored_series.csv (date,obs,sim) and passes dates= to all_metrics, so the metric is re-derivable from the evidence.

Interpret the magnitude before you retune anything: DSSAT HWAM is one well-managed, pest- and weed-free field at attainable yield; a GDHY 0.5° pixel is an area-average actual yield over ~2 500 km² including marginal land, pests, weeds and harvest losses. The Global Yield Gap Atlas puts Chinese maize actual/attainable at ≈0.6, so a +40…60 % PBIAS at a Chinese maize cell is the structural yield gap, not a chain bug — no cultivar/forcing/soil switch removes it (the same gap produced the +297 % São Paulo row in the 3×3 table). The DSSAT-sanctioned way to represent an area average is SLPF < 1; this KI ships it as convert_soilgrids_to_sol.py --soc_slpf (≈0.80 for a 20 g/kg-SOC topsoil), but SLPF = 1.00 is the declared baseline and --soc_slpf is a named sensitivity test — do not flip it just to move PBIAS, and say which you used. Also match the period to the cultivar: GDHY runs 1981–2016, but the dag's point_time_series caveat requires consistent cultivar/management, so a 2000-released hybrid (e.g. CN0001 Zhengdan958) + present-day NPKGRIDS N rates should be scored from 2000 onward, not against 1981–99 farming.

8. Unit Conversion Table

Chinese Cultivar Library

Location: KISSPATH_HOME/DSSAT/Data/Genotype/China/

9. Diagnostic Triplets (50 entries)

See diagnostics/triplets.yaml for the full set. Top 5 most common:

11. Validated Results

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

State bars from docs/validation_convention.yaml; do not substitute remembered thresholds. For the dag's rank-1 variable, HWAM (harvested grain yield at maturity, dry), the convention bars extracted for this KI are:

The duplicate nrmse convention row is intentionally restated as extracted from the KI facts above. If the convention file is wrong, report it rather than editing it from this skill document.

Temporal yield validation — Pearson r / NSE / KGE require ≥2 simulation years

The single-year SPAM scalar (crop_obs.get_observed_yield) gives ONE (sim,obs) pair, and ki_tools_common/metrics.py returns NaN for <2 pairs, so r/nse/kge are structurally undefined and the orchestrator's r<0.5 gate retries forever. To get a DEFINED r, the DSSAT run must span ≥2 simulation years (set NYERS/ start_year..end_year so Summary.OUT has ≥2 WYEAR rows), then pair each year's HWAM against the multi-year GDHY series via tools/s9_output_parsing/validate_yield_timeseries.py (--workdir <wd> --lat <Y> --lon <X> --crop maize). It writes validation_metrics.json with {nse,kge,r,pbias}. A single-year FileX still yields one pair → tool exits rc=2 with a warning. Use single-year SPAM only for %bias/nRMSE point checks (the 3×3 table below).

OBS-SCALE RULE for the r<0.5 gate — the default --obs gdhy is the ONLY obs valid for the interannual r/NSE/KGE gate at a single site. GDHY is a 0.5° gridded yield product, so its pixel is co-located and scale-matched to the simulated point. Do NOT use --obs faostat for the r-gate: FAOSTAT is a national aggregate dominated by a smooth technology/fertilizer trend and by the production-weighted centroid (NE China + Henan/Shandong North China Plain). A single non-representative point (e.g. Bengbu, humid monsoon S. Anhui, 32.9N/117.4E) has ~4–5× the national interannual variance and can even anti-correlate with the national series — Bengbu maize 2005–2020 gave PBIAS +8.94% (good mean bias) but r = −0.083 / NSE −12.47 against China, mainland. The same national series tracks at r≈0.80 when the sim sits on a production-representative point (AquaCrop at Henan 34.0N/113.0E), so the failure is obs location/scale, not model physics. FAOSTAT national is %bias-only for a single point; for the r-gate either (a) re-run with --obs gdhy at the simulated pixel [recommended, runnable today: GDHY maize covers 2005–2016 on disk], or (b) build a multi-site ensemble at the national production centroid before comparing to the aggregate. FAOSTAT has no sub-national Area, so provincial (Anhui) is not available as a middle ground.

FAOSTAT IS NOT A FAILURE CASE — it has a VALID metric family; do not chase the r-gate (verified 2026-06-15). validate_yield_timeseries.py --obs faostat classifies the comparison as obs_shape: regional_aggregate_time_series (see dag.yaml outputs.HWAM.observability), whose valid families are [magnitude_accuracy, trend_match] — NOT temporal_pattern_match. The tool therefore emits pbias (magnitude_accuracy) + sim_slope_kgha_yr/obs_slope_kgha_yr/ trend_sign_agree (trend_match) and nulls nse/kge/r (kept under _raw_invalid_* only). For Bengbu maize 2005–2020 vs China, mainland this is a PASS: PBIAS +8.94% (good mean bias) and trend_sign_agree: true (both rising). The dag-driven gate scores on PBIAS + trend-sign, NOT on the raw _raw_invalid_r (−0.08) / _raw_invalid_nse (−12.5) — those are structurally intrinsic to a weather-only point process simulating a smooth, technology-trending national aggregate, and switching cultivar/forcing/parameters CANNOT rescue them. Do not re-run with --obs gdhy merely to satisfy an r<0.5 gate that does not apply to this obs_shape; only switch to GDHY if the task genuinely asks for the point_time_series interannual-pattern comparison. The slope_ratio (~0.19, sim captures ~1/5 of the national trend) reflects fixed cultivar+management across all years — it is a documented limitation, not a tool bug.

3×3 Validation Results (2026-04-10)

Known Issues (from validation)

10. Coupling Interfaces

DSSAT can run as a standalone site model or be coupled through prepared forcing, soil and management files. Upstream weather and soil data are converted into DSSAT-ready .WTH and SOIL.SOL files; downstream consumers use parsed Summary.OUT and PlantGro.OUT variables such as HWAM, CWAM, LAID, CWAD, GWAD, ET, SW, runoff and drainage.

Standalone Workflow (WITHOUT VIC — for single-site or farmer queries)

DSSAT can run independently without any hydrological model. Use this workflow when the user asks about crop yield, planting decisions, or cultivar comparisons — NOT the VIC 10-step workflow.

Step 1: Get weather data

# Use NASA POWER for any location worldwide (no local data needed)
python skills/vic-auto-run/s2_forcing/forcing_nasa_power.py \
  --lat 45.5 --lon -73.6 --start_year 2005 --end_year 2023 \
  --output_dir outputs/<run>/weather/
# Then convert to DSSAT .WTH format using the forcing-converter skill

Or, for China sites, convert CMFD directly to DSSAT .WTH with this KI's validated S2 tool (the canonical weather recipe — there is no tools/fetch_weather.py):

python tools/s2_weather_prep/convert_cmfd_to_wth.py \
  --forcing_dir KISSPATH_FORCING/Data_forcing_03hr_010deg/ \
  --lat 32.9 --lon 117.4 --start_year 2005 --end_year 2020 \
  --output /tmp/run/weather/SITE.WTH --station_name SITE

Notes: (1) run this in a conda env with a working NetCDF backend (e.g. KISSPATH_HOME/miniconda3/envs/ohq/bin/python) — the tool now falls back h5netcdf→netcdf4→scipy automatically, but the default lisflood env has a broken numpy/netCDF4 binary. (2) Point extraction over the 3-hourly store is I/O-bound (~8–10 min for 16 years). For global sites, load via ki_tools_common.load_forcing.load_daily_forcing and write the same .WTH columns (DATE/SRAD/TMAX/TMIN/RAIN/WIND).

Step 2: Set up and run using dssat_workdir_setup.py (MANDATORY)

import sys
sys.path.insert(0, "KISSPATH_KI_ROOT/DSSAT/knowledge_infrastructure/tools")
from dssat_workdir_setup import create_workdir, run_dssat, parse_summary

workdir = create_workdir(
    crop="MZ",                    # MZ=maize, WH=wheat, SB=soybean
    cultivar="IB0001",            # From cultivar library (see below)
    weather_file="path/to/MTRL0501.WTH",
    soil_id="IBMZ910014",
    lat=45.5, lon=-73.6,
    planting_date=5150,           # YYDDD: year 05, DOY 150 (or "2005-05-30")
    start_year=2005, end_year=2015,
    output_dir="outputs/<run>/dssat",
)

result = run_dssat(workdir)
summary = parse_summary(workdir)
for rec in summary:
    print(f"Yield: {rec['HWAM']} kg/ha")

Step 3: Visualize results

python skills/plot/plot_crop_yield_map.py \
  --csv outputs/<run>/dssat/gridded_yield.csv \
  --value_col hwam_kgha \
  --title "Maize Yield" --output outputs/<run>/yield_map.png

Known Limitations

• Chinese cultivar library primarily covers winter wheat zones; spring wheat needs calibration
• FileX format is fixed-width columns — whitespace errors cause silent failures
• Fortran path length limit (~72-256 chars depending on compiler)
• No built-in spatial mode — grid simulations use wrapper scripts

Generated by the Knowledge Dissection Toolkit v4.0.

Rice Simulation (CERES-Rice / RICER048)

Model: CERES-Rice (RICER048 in DSSAT) Status: Validated tool ready, Chinese cultivar library with 11 varieties Tool: tools/setup_rice_experiment.py

Quick Start (Rice)

import sys
sys.path.insert(0, "KISSPATH_KI_ROOT/DSSAT/knowledge_infrastructure/tools")
from setup_rice_experiment import setup_rice

# Auto-selects cultivar and planting date by latitude
result = setup_rice(
    lat=30.0, lon=114.0,         # Wuhan, Yangtze region
    year=2010,
    weather_file="path/to.WTH",
    soil_id="IB00000001",
    output_dir="/tmp/dssat_rice",
)
# Result contains: workdir, cultivar, summary (if run succeeded)

Chinese Rice Cultivar Table

Key CERES-Rice Parameters

Rice-Specific Notes

• Rice uses transplanting (PLME=T, PAGE=23 for seedling age) in the FileX
• Paddy rice needs flood irrigation management (IR011=bund height, IR009=flood depth)
• N fertilizer: typically 120-180 kg/ha in China (use NPKGRIDS for site-specific rates)
• The model does NOT have a separate .ECO file — ecotype params are in .SPE
• For double-cropping in South China, run two separate experiments (early + late)

Soybean Simulation (CROPGRO / SBGRO048)

Model: CROPGRO-Soybean (CRGRO048 engine, SBGRO048 species files) Status: Validated tool ready, Chinese cultivar library with 7 varieties Tool: tools/setup_soybean_experiment.py

Quick Start (Soybean)

import sys
sys.path.insert(0, "KISSPATH_KI_ROOT/DSSAT/knowledge_infrastructure/tools")
from setup_soybean_experiment import setup_soybean

# Auto-selects cultivar by latitude and maturity group
result = setup_soybean(
    lat=45.0, lon=126.0,         # Harbin, Northeast
    year=2010,
    weather_file="path/to.WTH",
    soil_id="IB00000001",
    output_dir="/tmp/dssat_soybean",
)

Chinese Soybean Cultivar Table

Key CROPGRO-Soybean Parameters

Soybean-Specific Notes

• CROPGRO is a different model engine than CERES — uses photothermal time, not GDD
• Soybean is a legume: SYMBI=Y is set automatically (N fixation enabled)
• Minimal N fertilizer needed (0-30 kg/ha starter), soybean fixes its own N
• Maturity Group (MG) is the key cultivar parameter — higher MG = longer season
• HHH soybean is relay-planted after winter wheat harvest (~mid June)
• Ecotype (.ECO) file exists for soybean (SBGRO048.ECO) and must be present

PlantGro.OUT Parser (Daily Growth Analysis)

Tool: tools/parse_plantgro.py Status: Operational, tested on maize 10-year PlantGro.OUT

Quick Start (PlantGro Parser)

import sys
sys.path.insert(0, "KISSPATH_KI_ROOT/DSSAT/knowledge_infrastructure/tools")
from parse_plantgro import parse_plantgro, extract_growth_summary, get_timeseries

# Parse all daily records
records = parse_plantgro("/path/to/PlantGro.OUT")

# Get summary metrics (peak LAI, phenology, stress days)
summary = extract_growth_summary(records)
for run in summary["runs"]:
    print(f"Run {run['run']}: LAI={run['peak_lai']}, "
          f"Grain={run['final_grain_kgha']} kg/ha, "
          f"Water stress days={run['total_stress_days_water']}")

# Extract time series for specific variables
ts = get_timeseries(records, ["LAID", "CWAD", "GWAD"], run_number=1)

CLI Usage

# Growth summary (peak LAI, phenology dates, stress)
python tools/parse_plantgro.py /path/to/PlantGro.OUT --summary

# Export daily data to CSV
python tools/parse_plantgro.py /path/to/PlantGro.OUT --format csv --output growth.csv

# Extract specific variables
python tools/parse_plantgro.py /path/to/PlantGro.OUT --variables LAID CWAD GWAD --format json

Key Output Variables

Growth Summary Output (extract_growth_summary)

Returns per run:

• peak_lai / peak_lai_date / peak_lai_dap
• max_biomass_kgha
• final_grain_kgha / final_harvest_index
• emergence_dap / emergence_date
• anthesis_dap / anthesis_date
• maturity_dap / maturity_date
• total_stress_days_water / total_stress_days_nitrogen
• max_root_depth_m
• total_thermal_time

12. Parameter Selection by Region

Crop Calendar Reference (China)

Data sources on server:

• GGCMI Crop Calendar: KISSPATH_HOME/Crop_model_dataset/GGCMI_phase3_crop_calendar/
• China Phenology GeoTIFF: KISSPATH_HOME/Crop_model_dataset/8313530/
• SPAM crop distribution: KISSPATH_HOME/Crop_model_dataset/dataverse_files/