Docs

# S8: Batch Execution

## Purpose

Compile the DSSAT-CSM model from Fortran source code, create a batch file specifying which experiments and treatments to run, execute the model, and diagnose any runtime errors that occur.

## Prerequisites

- [ ] A Fortran compiler is installed (gfortran recommended, version >= 7.0).
- [ ] CMake is installed (version >= 3.10.0, as required by `CMakeLists.txt` line 7).
- [ ] S3-S7 completed: a valid FileX experiment file exists with all required sections.
- [ ] All referenced data files exist: `.SOL` soil profile, `.WTH` or `.WTX` weather files, cultivar files (`.CUL`, `.ECO`, `.SPE`).
- [ ] The `dssat-csm-data` repository or equivalent data directory is available at the expected path.
- [ ] You know which treatments to run and in what mode (batch, seasonal, sequence, etc.).

## Inputs

| Parameter       | Type      | Source              | Description                                           |
|-----------------|-----------|---------------------|-------------------------------------------------------|
| Source code     | Directory | Repository          | DSSAT-CSM Fortran source tree (this repository)       |
| FileX           | File      | S3-S7 outputs       | Experiment file(s) to simulate                        |
| Treatment IDs   | Integer   | User / protocol     | Which treatments from FileX to run                    |
| Run mode        | CHAR*1    | User decision       | How the model processes treatments (see mode table)   |
| Data directory  | Path      | Installation        | Location of supporting data files (.SOL, .WTH, etc.)  |

## Procedure

### Step 1: Compile DSSAT-CSM from Source

#### Step 1.1: Verify Prerequisites

Run the following commands and confirm successful output:

```bash
gfortran --version    # Must show gfortran version >= 7.0
cmake --version       # Must show CMake version >= 3.10.0
```

If gfortran is not installed:
- macOS: `brew install gcc`
- Ubuntu/Debian: `sudo apt install gfortran`
- CentOS/RHEL: `sudo yum install gcc-gfortran`

If CMake is not installed:
- macOS: `brew install cmake`
- Ubuntu/Debian: `sudo apt install cmake`

#### Step 1.2: Create Build Directory

DSSAT enforces out-of-source builds. In-source builds produce a fatal CMake error (see `CMakeLists.txt` lines 9-14).

```bash
cd /path/to/DSSAT
mkdir -p build
cd build
```

**CRITICAL**: Do NOT run `cmake` from the source directory root. The CMakeLists.txt will reject this with:
```
FATAL_ERROR: DSSAT in-source builds are not permitted.
```

#### Step 1.3: Configure with CMake

```bash
cmake ..
```

Expected output includes:
```
-- MAJOR: 4 MINOR: 8 MODEL: 5 BUILD: 41 COMMIT: <hash>
-- BRANCH: develop
```

This confirms CMake found the Fortran compiler and parsed the project definition. The version numbers come from `CMakeLists.txt` lines 22-25:
```
SET(MAJOR 4)
SET(MINOR 8)
SET(MODEL 5)
SET(BUILD 41)
```

**If CMake fails**: Check that the Fortran compiler is in your PATH. On macOS, ensure you are using Homebrew's gcc/gfortran, not Apple's clang (which lacks Fortran support).

#### Step 1.4: Compile

```bash
make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)
```

This compiles all Fortran source files and links them into the executable. The `-j` flag parallelizes compilation using all available CPU cores.

Expected result: An executable file is produced. The name follows the pattern `dscsm0XX` where XX matches the version. For v4.8.5, the executable is typically named `dscsm048`.

**Common compilation errors**:

| Error                                    | Cause                                           | Resolution                                         |
|------------------------------------------|------------------------------------------------|----------------------------------------------------|
| `gfortran: command not found`            | Compiler not installed or not in PATH          | Install gfortran; check PATH                       |
| `Error: Unresolvable reference to...`    | Missing source file or module dependency       | Ensure all source directories are present          |
| `Error: Type mismatch in argument`       | Fortran interface mismatch (compiler strictness)| Try `-fallow-argument-mismatch` flag in CMake      |
| `undefined reference to 'main'`          | Linking error                                  | Check that CSM_Main/CSM.for is included in build   |
| Multiple definition errors               | Duplicate compilation of same file             | Clean build: `rm -rf build && mkdir build`         |

#### Step 1.5: Verify the Executable

```bash
ls -la dscsm048    # or whatever the executable name is
./dscsm048         # Should print usage or wait for input
```

If the executable runs and prints model header information or waits for input, compilation succeeded.

**IMPORTANT**: After any source code changes, you must re-run `make` from the build directory. Forgetting to recompile after code changes is the most common cause of "my changes had no effect."

### Step 2: Create the Batch File

#### Step 2.1: Understand Batch File Format

The batch file is a fixed-format text file that tells the CSM which experiment files and treatments to run. The file is named `DSSBatch.v48` (or any name -- the name is passed as a command-line argument).

Source reference: The CSM reads the batch file looking for the `$BATCH` header (`CSM.for` line 238), then reads experiment paths and treatment numbers from subsequent lines (`CSM.for` lines 266-277).

#### Step 2.2: Write the Batch File Header

The first line must be `$BATCH(CROP)` where CROP is the crop name (for documentation only; the model only looks for `$BATCH`).

```
$BATCH(MAIZE)
```

Comment lines start with `!` and are ignored:
```
! Directory    : /path/to/experiments
! Command Line : ./dscsm048 B DSSBatch.v48
! Crop         : Maize
```

#### Step 2.3: Write the Column Header

```
@FILEX                                                                                        TRTNO     RP     SQ     OP     CO
```

The `@FILEX` header line is required. The model reads it to locate column positions.

Column layout (from `CSM.for` lines 268-272):
- Columns 1-92: Full path to the FileX experiment file (fixed-width, padded with spaces).
- Columns 93-98: TRTNO (treatment number, I6 format).
- Columns 99-104: RP (replication number, I6 format).
- Columns 105-110: SQ (sequence number, I6 format; 0 for non-sequence runs).
- Columns 111-116: OP (option number, I6 format; 0 for default).
- Columns 117-122: CO (control option, I6 format; 0 for default).

**CRITICAL**: The FileX path occupies columns 1 through 92. The model reads the path by finding the last non-blank character position in columns 1-92, then extracts the 12-character filename from the end of that string (`CSM.for` lines 268-270). If the path is too long and exceeds 92 characters, it will be truncated, and the model will fail with a "File not found" error. This is a Fortran fixed-format string limitation.

#### Step 2.4: Write Treatment Lines

One line per treatment to simulate:

```
/full/path/to/Maize/UFGA8201.MZX                                                                    1      1      0      0      0
```

The path must be left-justified and the filename must end at or before column 92. Pad with spaces between the path and column 93.

To run multiple treatments from the same experiment:
```
/full/path/to/Maize/UFGA8201.MZX                                                                    1      1      0      0      0
/full/path/to/Maize/UFGA8201.MZX                                                                    2      1      0      0      0
/full/path/to/Maize/UFGA8201.MZX                                                                    3      1      0      0      0
```

To run treatments from different experiments:
```
/full/path/to/Maize/UFGA8201.MZX                                                                    1      1      0      0      0
/full/path/to/Maize/BRPI0202.MZX                                                                    1      1      0      0      0
```

#### Step 2.5: Batch File Validation

1. Verify every FileX path exists: `ls /full/path/to/Maize/UFGA8201.MZX`
2. Verify every treatment number exists within its FileX.
3. Verify no path exceeds 92 characters (count characters including the filename).
4. Verify the `$BATCH` header is present on the first non-comment line.

Tool reference: `create_batch_file` can automate batch file generation from a list of experiments and treatments.

### Step 3: Run the Model

#### Step 3.1: Run Modes

The model is invoked with:
```bash
./dscsm048 <RUNMODE> <BATCHFILE> [SIMCONTROL]
```

Or with explicit model specification:
```bash
./dscsm048 <MODEL> <RUNMODE> <BATCHFILE> [SIMCONTROL]
```

Source reference: `CSM.for` lines 140-199 define all run modes.

| Mode | Name            | Description                                                    | Batch File Required |
|------|-----------------|----------------------------------------------------------------|---------------------|
| A    | All treatments  | Runs all treatments in a single FileX                          | No (FileX on cmdline)|
| B    | Batch           | Runs treatments listed in batch file                           | Yes                 |
| N    | Seasonal        | Seasonal analysis (multi-year same treatment)                  | Yes                 |
| Q    | Sequence        | Rotation/sequence analysis (cycles through treatments)          | Yes                 |
| S    | Spatial         | Spatial analysis mode                                          | Yes                 |
| E    | Sensitivity     | Sensitivity analysis mode                                      | Yes                 |
| F    | Farm            | Farm model simulation                                          | Yes                 |
| C    | Command line    | Single treatment from command line                             | No                  |
| G    | Gencalc         | Genetic coefficient calculator (command line)                  | No                  |
| T    | Gencalc batch   | Genetic coefficient calculator (batch)                         | Yes                 |
| Y    | Yield forecast  | Yield forecasting mode                                         | Yes                 |
| I    | Interactive     | Interactive mode (GUI-driven)                                  | No                  |
| D    | Debug           | Debug mode (reads temp file directly)                          | No                  |
| L    | Locus           | Gene-based model                                               | Yes                 |

**Most common usage**: Mode `B` with a batch file:
```bash
./dscsm048 B DSSBatch.v48
```

**Run all treatments in one experiment**:
```bash
./dscsm048 A UFGA8201.MZX
```

**Run a specific treatment from command line**:
```bash
./dscsm048 C UFGA8201.MZX 1
```

#### Step 3.2: Execute the Model

1. Change to the working directory where data files are located (or where you want output):
```bash
cd /path/to/working/directory
```

2. Run the model:
```bash
/path/to/build/dscsm048 B DSSBatch.v48
```

3. The model will produce output to the current working directory (not the directory where the executable or FileX is located).

4. Expected behavior: The model prints progress to stdout (treatment names, dates). Each treatment runs through the DYNAMIC state machine (see Step 4). The model exits when all treatments are complete.

#### Step 3.3: Verify Successful Execution

After the model finishes:

1. Check that `Summary.OUT` exists and has data lines:
```bash
wc -l Summary.OUT     # Should have header + one line per treatment
```

2. Check for errors:
```bash
cat MODEL.ERR 2>/dev/null   # Should not exist or be empty for clean run
cat ERROR.OUT 2>/dev/null   # Runtime errors
cat WARNING.OUT 2>/dev/null # Non-fatal warnings
```

3. Check that output files were created:
```bash
ls -la Summary.OUT Overview.OUT PlantGro.OUT SoilWat.OUT
```

### Step 4: Understand the DYNAMIC State Machine

The model processes each treatment through a sequence of phases defined as integer constants in `ModuleDefs.for` lines 67-77:

```fortran
INTEGER, PARAMETER ::
    RUNINIT  = 1,    ! One-time initialization for entire run
    INIT     = 2,    ! (Will replace RUNINIT & SEASINIT; not fully implemented)
    SEASINIT = 2,    ! Seasonal initialization
    RATE     = 3,    ! Daily rate calculations
    EMERG    = 3,    ! Used for some plant processes (same value as RATE)
    INTEGR   = 4,    ! Daily integration
    OUTPUT   = 5,    ! Write daily outputs
    SEASEND  = 6,    ! End-of-season summary
    ENDRUN   = 7     ! Close all files, final cleanup
```

#### Phase Execution Order

For a single treatment:
```
RUNINIT (1)  -->  Called once at start of run
  |
  v
SEASINIT (2) -->  Called once per season (initializes weather, soil, plant)
  |
  v
[Daily loop begins]
  |
  RATE (3)   -->  Calculate daily rates: weather -> soil -> SPAM -> plant
  |
  INTEGR (4) -->  Integrate state variables forward one day
  |
  OUTPUT (5) -->  Write daily output to PlantGro.OUT, SoilWat.OUT, etc.
  |
  [If harvest/end condition met] --> SEASEND (6) --> [exit daily loop]
  [Otherwise] --> [next day] --> RATE (3)
  |
  v
SEASEND (6)  -->  Write seasonal summary to Summary.OUT
  |
  v
[If more seasons/treatments] --> SEASINIT (2)
[If done] --> ENDRUN (7)
  |
  v
ENDRUN (7)   -->  Close all files, deallocate memory
```

#### Why This Matters

- If the model crashes during RATE (3), you may have partial PlantGro.OUT output but no Summary.OUT entry for that treatment.
- If the model crashes during SEASINIT (2), no daily output files will be created for that treatment.
- If the model finishes SEASEND (6) but crashes during ENDRUN (7), Summary.OUT will have data but output files may not be properly closed.

### Step 5: Monitor Execution and Diagnose Errors

#### Step 5.1: Check MODEL.ERR

The MODEL.ERR file contains detailed error descriptions for DSSAT error codes. The model looks for this file in the executable directory first, then in the standard DSSAT path (`ERROR.for` lines 62-72).

Error format in ERROR.OUT (the runtime error log):
```
*RUN-TIME ERRORS OUTPUT FILE
<experiment info>
ERRKEY  ERRNUM  FILE  LNUM
```

Common error codes:
- Error 42: Section not found in input file (e.g., `*INITI` section missing from FileX).
- Error 28: Batch file not found or cannot be opened.
- Error 26: `$BATCH` header not found in batch file or malformed treatment line.

#### Step 5.2: Check WARNING.OUT

WARNING.OUT contains non-fatal warnings (`Warning.for`). These do not stop the simulation but indicate potential issues.

Common warnings:
- Weather data missing for specific dates.
- Soil water content adjusted (clamped).
- Planting conditions not met on specified date.
- Nutrient balance warnings.

#### Step 5.3: Common Runtime Errors

| Error                                          | Cause                                                   | Diagnosis and Resolution                                       |
|------------------------------------------------|---------------------------------------------------------|----------------------------------------------------------------|
| `SIGFPE: Floating-point exception`             | Division by zero in a calculation                       | Check soil layers: zero thickness or zero BD causes this.      |
| `File not found` / `IOSTAT error`              | FileX, .SOL, .WTH, or cultivar file path is wrong      | Verify all paths; check for Fortran string truncation.         |
| Simulation stops with no output                | Fatal error during SEASINIT; check MODEL.ERR            | Open ERROR.OUT; look for the ERRKEY and ERRNUM.                |
| Simulation hangs indefinitely                  | Auto-planting cannot find suitable date                 | Widen planting window; check IPLTI switch; verify weather data covers the planting period. |
| `Summary.OUT` exists but has -99 for all values| Simulation ran but crop never emerged or matured        | Check PlantGro.OUT for stress factors; verify planting depth and cultivar. |
| `Section *XXXXX not found`                     | Required section missing from FileX                     | Add the missing section; see S3 for FileX structure.           |
| `Error in FILEIO`                              | Temporary IO file is corrupted or locked                | Delete DSSAT48.INP and re-run.                                 |
| Model runs but yield is 0                      | Crop failed; stress too high or wrong cultivar          | See S9 for output diagnosis procedures.                        |

#### Step 5.4: Debugging Strategies

1. **Run a single treatment first**: Before running a full batch, test with one treatment using mode `C`:
   ```bash
   ./dscsm048 C UFGA8201.MZX 1
   ```

2. **Enable verbose output**: Set IDETL='D' (detail) in the simulation controls section of FileX to get maximum output detail.

3. **Check intermediate file**: The model writes a temporary file `DSSAT48.INP` during execution. If the run fails, this file contains the parsed input data that can be inspected to see what the model actually read.

4. **Binary search for errors**: If a batch with many treatments fails, bisect the batch file to identify which treatment causes the error.

### Step 6: Post-Execution Cleanup

6.1. Output files are written to the current working directory. Move or rename them before running a new simulation, as DSSAT overwrites existing output files.

6.2. The temporary file `DSSAT48.INP` can be deleted after a successful run.

6.3. If running multiple experiments in sequence (not sequence mode), save output files between runs:
```bash
./dscsm048 B DSSBatch_exp1.v48
mkdir -p results/exp1 && mv *.OUT results/exp1/

./dscsm048 B DSSBatch_exp2.v48
mkdir -p results/exp2 && mv *.OUT results/exp2/
```

## Expected Outputs

| Output                  | Location                | Verification                                         |
|-------------------------|-------------------------|------------------------------------------------------|
| dscsm048 executable     | build/ directory        | File exists and is executable                        |
| DSSBatch.v48            | Working directory       | $BATCH header present; paths valid; treatments exist |
| Summary.OUT             | Working directory       | One data line per treatment; HWAH values present     |
| PlantGro.OUT            | Working directory       | Daily growth data for each treatment                 |
| SoilWat.OUT             | Working directory       | Daily soil water data                                |
| No MODEL.ERR/ERROR.OUT  | Working directory       | Absence indicates clean run                          |

## Validation Checks

1. **Compilation**: `dscsm048` executable exists and is newer than any source file modification time.
2. **Batch file format**: `$BATCH` header exists. All FileX paths resolve to existing files. Treatment numbers exist in their FileX. Path lengths <= 92 characters.
3. **Runtime**: `Summary.OUT` has the expected number of data lines (one per treatment). No `ERROR.OUT` file created. `WARNING.OUT` contains only benign warnings.
4. **Output completeness**: For each treatment in the batch, there is a corresponding entry in `Summary.OUT` with non-(-99) values for HWAH, ADAT, and MDAT (for crops that reach maturity).

Tool reference: `check_model_errors` can automate parsing of ERROR.OUT and WARNING.OUT.

## Common Pitfalls

| Pitfall                                        | Symptom                                                 | Resolution                                                   |
|------------------------------------------------|---------------------------------------------------------|--------------------------------------------------------------|
| Forgetting to recompile after code changes     | Source changes have no effect on simulation              | Run `make` in build directory before every run after edits   |
| Batch file path > 92 characters                | `File not found` error; Fortran string truncation        | Shorten directory path; move files closer to root            |
| Wrong run mode                                 | Unexpected behavior; model reads wrong input             | Verify mode letter matches intent (B for batch, N for seasonal)|
| Running cmake in source directory              | CMake fatal error about in-source builds                 | Always create and use a separate `build/` directory          |
| Missing DSSAT data files                       | Model cannot find .SOL, .WTH, or cultivar files          | Verify DSSATPRO.v48 paths; check file existence              |
| Output files from previous run overwritten     | Lost results from earlier simulation                     | Save/rename output files before each new run                 |
| Compilation with wrong gfortran version        | Mysterious compilation errors; type mismatch warnings    | Use gfortran >= 7.0; check with `gfortran --version`        |
| Running model from wrong working directory     | Files not found; output written to unexpected location   | cd to the data directory before running the executable       |
| DSSAT48.INP locked from previous crashed run   | Model cannot write temporary file                        | Delete DSSAT48.INP manually and re-run                       |
| Batch file missing blank line at end           | Last treatment may not be read                           | Add a blank line after the last treatment entry              |