Docs

# S4 -- Model Execution

## Purpose

Assemble all input components into a runnable configuration, create batch files, execute
DNDCv.CAN v9.6.0 (as a Windows PE32 executable either natively on Windows or via Wine on
Linux), monitor execution, handle errors, and manage spinup procedures.

## Inputs

| Input | Source | Format | Notes |
|---|---|---|---|
| Completed `.dnd` file | S0-S3 skills | Text file | Contains all site, climate, soil, crop, and management configuration |
| Climate `.txt` files | S1 skill | Daily text files | One per simulation year (or one recycled) |
| `.spf` soil profile (optional) | S2 skill | Text file | Only if heterogeneous profile is used |
| MultiYear_CO2.txt (optional) | S1 skill | Text file | If transient CO2 is needed |
| Spinup file (optional) | Previous DNDC run | Binary/text from `Result/Inter/` | `soil_1`, `soil_2`, etc. |
| DNDC installation directory | System setup | Directory path | Must contain `DNDC95.exe`, `Database/`, `Library/`, `Result/` |

## Outputs

| Output | Location | Description |
|---|---|---|
| Summary output files | `Result/Record/Site/` or `Result/Record/Batch/` | Annual summaries of yield, N2O, leaching, SOC, water balance |
| Daily output files (if enabled) | `Result/Record/Site/` or `Result/Record/Batch/` | `Day_Climate1`, `Day_Crop1`, `Day_SoilC1`, etc. |
| Intermediate state files | `Result/Inter/` | `soil_1`, `soil_2`, etc. for spinup restart |
| Console / log output | stdout/stderr | Runtime messages, warnings, error codes |

## Procedure

### Step 1 -- Verify the DNDC Installation Directory

The expected directory structure is:

```
DNDC/
  DNDC95.exe          # Command-line executable
  DNDC.exe            # GUI executable (optional)
  Database/           # Internal lookup tables
  Library/            # Crop libraries, livestock files
  Result/             # Output directory (auto-created)
    Record/
      Site/           # Single-site simulation outputs
      Batch/          # Batch simulation outputs
    Inter/            # Intermediate state files for spinup
```

Confirm that `DNDC95.exe` (the command-line version) is present.  The GUI version
(`DNDC.exe`) is not needed for batch/automated runs.

### Step 2 -- Assemble the `.dnd` File

If building the `.dnd` programmatically (not via the GUI):

1. Write the climate/site header section (S0 parameters).
2. Write the soil section (S2 parameters).
3. Write the crop and management sections (S3 parameters).
4. Write the TileDrain and Model Parameters section.
5. Write the Save/paths section.

The `.dnd` is a strictly line-ordered text file.  Every parameter occupies a fixed line
number.  When editing by hand, never insert or delete lines -- only modify values in place.

**Tip:** Start from a known-good `.dnd` generated by the GUI and modify values, rather than
writing from scratch.

### Step 3 -- Create the Batch File

The batch file (`batch.txt`) lists the `.dnd` files to run, one per line:

```
C:\DNDC\simulations\site1.dnd
C:\DNDC\simulations\site2.dnd
C:\DNDC\simulations\site3.dnd
```

For a single simulation, the batch file contains just one line.

Paths in the batch file must use the path convention of the execution environment:
- **Windows native:** Use Windows paths (`C:\DNDC\...`)
- **Wine on Linux:** Use Windows-style paths that map to the Wine prefix
  (`Z:\home\user\DNDC\...` or `C:\DNDC\...` depending on drive mapping)

### Step 4 -- Execute on Windows (Native)

From the Windows command prompt:

```cmd
start /wait DNDC95.exe -s batch.txt
```

Or with explicit output directory and daily output control:

```cmd
start /wait DNDC95.exe -s batch.txt -daily 0 -output C:\DNDC\Result\custom_output\
```

Command-line flags:
| Flag | Description |
|---|---|
| `-s <batch_file>` | Path to the batch file listing `.dnd` files |
| `-daily <0\|1>` | Override daily output recording (0 = off, 1 = on) |
| `-output <dir>` | Override output directory |

The `start /wait` prefix ensures the command prompt waits for DNDC to finish before
returning control.

### Step 5 -- Execute on Linux via Wine

DNDC is a Windows PE32 executable and requires Wine to run on Linux.

**Basic execution:**

```bash
cd /path/to/DNDC
wine DNDC95.exe -s batch.txt
```

**With Xvfb (headless, no display):**

```bash
xvfb-run wine DNDC95.exe -s batch.txt
```

**Full production command with output control:**

```bash
cd /path/to/DNDC
WINEDEBUG=-all xvfb-run wine DNDC95.exe -s batch.txt -daily 0 -output Z:\\path\\to\\output\\
```

Notes on Wine execution:
- `WINEDEBUG=-all` suppresses Wine debug messages that clutter stdout.
- `xvfb-run` provides a virtual X framebuffer so Wine does not require a physical display.
- Path separators in arguments to `DNDC95.exe` must be Windows-style backslashes.
- Use the Wine drive mapping (`Z:` maps to `/` by default) for paths outside the Wine prefix.
- Wine prefix can be set with `WINEPREFIX=/path/to/prefix` if using a custom installation.

**Path translation example:**

| Linux path | Wine path |
|---|---|
| `/home/user/DNDC/batch.txt` | `Z:\home\user\DNDC\batch.txt` |
| `/data/output/` | `Z:\data\output\` |

### Step 6 -- Monitor Execution

**Runtime indicators:**
- DNDC prints progress to stdout (year and day being simulated).
- For a single-site, single-year simulation, execution typically takes 1-30 seconds.
- Multi-decade or multi-site batch runs can take minutes to hours.

**Check for completion:**
- The process exits with return code 0 on success.
- Output files appear in the `Result/Record/` directory.
- For batch runs, each `.dnd` produces a separate output subdirectory.

**Monitoring long runs:**

```bash
# Check if DNDC is still running
ps aux | grep DNDC95

# Watch output directory for new files
watch -n 5 ls -lt /path/to/DNDC/Result/Record/Batch/
```

### Step 7 -- Handle Common Errors

| Error Symptom | Likely Cause | Fix |
|---|---|---|
| Immediate crash, no output | Malformed `.dnd` file (wrong line count, corrupted structure) | Regenerate `.dnd` from GUI or known-good template |
| Crash at year N | Missing climate file for year N | Verify all climate files exist and paths in `.dnd` are correct |
| Crash with soil error | `.spf` file not found or malformed | Check `.spf` path and format; ensure layers sum to 2.0 m |
| Runs but produces zero yield | Wrong climate format type; precipitation in mm not cm | Verify climate format type matches file; check units |
| Wine: "fixme" or "err" messages | Normal Wine compatibility messages | Suppress with `WINEDEBUG=-all`; only worry if execution fails |
| Wine: display error | No X server available | Use `xvfb-run` for headless execution |
| Very slow execution | Daily output enabled for large batch | Disable daily output (`-daily 0`) unless needed |
| Output directory not created | Missing `Result/` directory structure | Create `Result/Record/Site/` and `Result/Record/Batch/` directories manually |

### Step 8 -- Spinup Procedures

Spinup equilibrates soil C/N pools to steady state before the main simulation.  Without
spinup, initial transients in SOC decomposition can dominate the first several years of
results.

**Method 1 -- Internal spinup (Reset Soil):**
1. Set `Reset Soil (annual) after 10 years` = 1 (Yes) in the TileDrain/Model Parms tab.
2. Run a 10+ year simulation with repeated management.
3. After year 10, the soil state resets annually to the year-10 conditions.
4. All years after the reset period use equilibrated initial conditions.

**Method 2 -- External spinup file:**
1. Run a preliminary simulation (e.g., 10-50 years with repeated management).
2. DNDC writes soil state files to `Result/Inter/` (named `soil_1`, `soil_2`, etc.).
3. In the target simulation, enable `Read from spinup File` and provide the path to the
   desired soil state file.
4. Set the read frequency (e.g., every 1 year) to re-initialize from that state.

**Spinup best practices:**
- Use at least 10 years of spinup for agricultural systems.
- Use 50-100 years for natural/forest systems where SOC turnover is slow.
- Verify spinup adequacy by checking that SOC change in the last spinup year is < 1% of
  total SOC.
- For batch runs with many sites, a common spinup period can be shared if sites have
  similar management history.

### Step 9 -- Organize Output

After successful execution:
1. Copy or move output files from `Result/Record/` to a project-specific directory.
2. Record the `.dnd` file, climate files, and `.spf` file alongside outputs for
   reproducibility.
3. Clear the `Result/` directory before the next run to avoid mixing outputs.

## Verification

- Confirm that output files exist in the expected directory:
  - `Summary_*` files for annual results.
  - `Day_*` files if daily output was enabled.
- Check that the number of data rows in summary files matches the number of simulation years.
- Verify the process exit code is 0.
- For spinup runs, confirm that `soil_*` files were written to `Result/Inter/`.
- Quick sanity check: open the summary file and verify that yield, N2O, and SOC values are
  within physically plausible ranges.

## Traps

| Trap | Consequence | Prevention |
|---|---|---|
| **Forgetting `start /wait` on Windows** | Command prompt returns immediately; script continues before DNDC finishes | Always use `start /wait` for scripted runs |
| Wine path separators (/ instead of \\) | DNDC cannot find files | Use Windows-style backslashes in all paths passed to DNDC95.exe |
| `.dnd` edited with wrong line count | Silent data misalignment; parameters read from wrong lines | Never insert/delete lines; only modify values in place |
| Running without `xvfb-run` on headless Linux | Wine fails trying to open a display | Always wrap with `xvfb-run` on servers without a display |
| Output directory not writable | DNDC crashes silently or produces no output | Check directory permissions before running |
| Batch file has Windows line endings on Linux (or vice versa) | Path parsing fails | Use `dos2unix` or `unix2dos` as needed |
| Spinup file from incompatible DNDC version | Corrupted soil initialization | Only use spinup files generated by the same DNDC version |
| Daily output enabled for large batch | Terabytes of output; disk full | Disable daily output unless specifically needed for diagnostics |
| Not clearing Result/ between runs | Old and new outputs mixed in same directory | Clear or rename Result/Record/ before each new batch |
| Climate file paths in `.dnd` use relative paths | Paths break when DNDC working directory differs from expectation | Always use absolute paths in `.dnd` and batch files |

## Example

Running a 3-year corn simulation on Linux via Wine:

```bash
# Set up directory
DNDC_DIR="/home/user/DNDC"
SIM_DIR="/home/user/simulations/corn_ottawa"

# Verify installation
ls "$DNDC_DIR/DNDC95.exe" "$DNDC_DIR/Database" "$DNDC_DIR/Library"

# Create batch file with Wine path
echo "Z:\\home\\user\\simulations\\corn_ottawa\\OTT_corn.dnd" > "$SIM_DIR/batch.txt"

# Ensure output directories exist
mkdir -p "$DNDC_DIR/Result/Record/Batch"
mkdir -p "$DNDC_DIR/Result/Inter"

# Execute
cd "$DNDC_DIR"
WINEDEBUG=-all xvfb-run wine DNDC95.exe -s "Z:\\home\\user\\simulations\\corn_ottawa\\batch.txt" -daily 0

# Check exit status
if [ $? -eq 0 ]; then
    echo "DNDC completed successfully"
    ls -la "$DNDC_DIR/Result/Record/Batch/"
else
    echo "DNDC failed with exit code $?"
fi

# Archive results
cp -r "$DNDC_DIR/Result/Record/Batch/" "$SIM_DIR/output/"
```

For a 10-year spinup followed by a 3-year production run:

```bash
# Step 1: Run spinup (10 years, Reset Soil enabled)
cd "$DNDC_DIR"
WINEDEBUG=-all xvfb-run wine DNDC95.exe -s "Z:\\path\\to\\spinup_batch.txt" -daily 0

# Step 2: Copy spinup soil state
ls "$DNDC_DIR/Result/Inter/soil_*"

# Step 3: Run production (3 years, reading from spinup file)
# The production .dnd has "Read from spinup File" enabled pointing to the soil_10 file
WINEDEBUG=-all xvfb-run wine DNDC95.exe -s "Z:\\path\\to\\production_batch.txt" -daily 1
```