MESC

A Fortran-based microbial-explicit soil carbon cycle model.

---

1. Overview

The MESC model is a process-oriented soil carbon model that explicitly represents microbial decomposition processes (using Michaelis-Menten kinetics) implemented in Fortran, designed to simulate soil and ecosystem carbon dynamics and their controlling mechanisms.

The model adopts a modular architecture, clearly separating core process representation, input/output handling, and model control logic.
It makes use of netCDF (C + Fortran), enabling efficient handling of structured scientific data and deployment on high-performance computing (HPC) systems.

---

2. Code Structure and Design

MESC/
├── src/                   # Core Fortran source code
│   ├── main.f90           # main program or test program
│   ├── mod_calcost.f90    # compute cost for 14C, POC/MAOC fractions, HWSD SOC profile ...
│   ├── mod_constants.f90  # all constants
│   ├── mod_functions.f90  # different functions for 14C, POC/MAOC fractions, HWSD SOC profile ...
│   ├── functn_wrapper.f90 # 
│   ├── mod_inout.f90      # input or output (netcdf files)
│   ├── mod_interface.f90  # 
│   ├── mod_model_core.f90 # the core routines for the mesc model
│   └── mod_variables.f90  # all variables
│
├── auxil/                 # 
│   └── to do              #
│
├── cmake/                 # CMake helper modules
│   └── FindNetCDFFortran.cmake
│
├── test/                  # Test and example runs
│   ├── benchmark          # 
│   ├── input              # input data
│   ├── output             # ouput
│   ├── run_main.sh        # One-command run test script
│   └── readme      
│
├── pre-processing/        # 
│   ├── cable              # output data of CABLE
│   ├── ORCHIDEE           # output data of ORCHIDEE
│   ├── available_USDA_SoilSuborder_mask.py # 
│   ├── convert_scale.bash                  # 
│   ├── resample_USDA_SoilSuborder.py       # 
│   └── readme.md      
│
├── pre-processing/        # 
│   ├── ...                # 
│   ├── processing.py      # 
│   └── readme.md      
│
├── CMakeLists.txt         # Build configuration
├── build.sh               # One-command build script
├── README.md
└── LICENSE

---

3. Software Requirements

The MESC model has been developed and tested in the following software environments:

• Fortran compiler:
  • Legacy Intel compiler (ifort) version 2021.9.0
  • Intel compiler (ifx) version 2025.3.0
• netCDF-Fortran: versions 4.6.1, 4.6.2
• netCDF-C: versions 4.9.2, 4.9.3

On HPC systems, the required environment is typically provided via modules, for example:

module load oneapi23u1
module load netcdf_intel

The exact modules used will be specific to the HPC system.

---

4. Building the Model

Recommended: One-command build

./build.sh

This script automatically:

1. Loads the required compiler and libraries
2. Creates an out-of-source build directory
3. Configures and builds the model
4. Copies the executable to build/ or test/

The final executable is located at: build/main or test/main

Manual build (for development)

module load oneapi23u1 
module load netcdf_intel
mkdir build
cd build
cmake .. -DCMAKE_Fortran_COMPILER=ifort
cmake --build . -j

---

5. Running the Model

Input files (e.g., parameter files or netCDF datasets) should be placed in the same directory to ensure consistent input–output management.

cd test
./run_main.sh

---

6. Generating API Documentation

API documentation is generated with FORD, a Fortran documentation generator.

Install FORD (using a virtual environment is recommended):

pip install ford

Generate documentation:

ford mesc.md

This reads !> and !! comment blocks from src/*.f90 and produces static HTML output in doc/.

View documentation:

open doc/index.html

To regenerate after updating doc comments, simply re-run ford mesc.md.

---

Developer setup

We make use of Fortitude for Fortran linting. To install Fortitude, either create and activate a Python virtual environment and install via

pip install -r requirements-dev.txt

or follow the instructions on the Fortitude website.

To apply Fortitude for linting the MESC code base, run

fortitude check

from the command line. This will report any issues, given the configuration in fortitude.toml.