Getting Started

Prerequisites

gSAM–Chem builds on gSAM version 1.8.7 and requires:

• A Fortran compiler (Intel ifort/ifx or GNU gfortran ≥ 9)
• MPI implementation (OpenMPI, MPICH, or Intel MPI)
• NetCDF-Fortran library
• KPP 3.3.0 (for regenerating the chemistry code; not required to run)
• Python 3 with numpy, scipy, and netCDF4 (for post-processing)

On a typical HPC cluster these are available as environment modules. For example, on a system using Lmod:

module load intel/oneapi mpi/intel netcdf

Installation

Clone the repository from GitHub:

git clone https://github.com/gsam-chem/gsam-chem.git
cd gsam-chem

The repository layout is:

gsam-chem/
├── SRC/                    # Fortran source (gSAM + chemistry module)
│   ├── CHEMISTRY/          # Chemistry module
│   │   ├── CLOUDCHEM/      # CloudChem KPP mechanism (.kpp, .f90)
│   │   └── HET_CHEM/       # Heterogeneous chemistry
│   ├── SLM/                # Simple Land Model
│   ├── MICRO_M2005/        # Microphysics
│   ├── SGS_TKE/            # Turbulence closure
│   ├── RAD_RRTM/           # Radiation
│   └── ...                 # Other dynamical core modules
├── CASES/                  # Example case directories
│   └── goAMAZON_deep_convection/
├── SCRIPTS/                # Post-processing utilities
├── GLOBAL_DATA/            # Global data files (SST, ozone, etc.)
├── GRIDS/                  # Grid definition files
├── UTIL/                   # Utilities
├── Changes/                # Changelog
├── DOC/                    # Documentation
├── OBJ/                    # Build output (created at compile time)
├── Build                   # Build script (csh)
├── CaseName                # Active case name
├── gSAM                    # Compiled executable
├── gsam.run                # Job submission script
└── Makefile                # Makefile

Building gSAM–Chem

Building gSAM–Chem is a two-step process: first configure the top-level Makefile for your system, then run the Build csh script.

1. Configure the Makefile

Open Makefile and locate the block for your platform. The key variables to set are the MPI Fortran compiler and the path to your NetCDF installation (read from the $NETCDF environment variable by default):

# Makefile — compiler and NetCDF settings (Linux/Intel example)
FF90 = mpif90 -c -r8          # MPI Fortran compiler
NCPATH = ${NETCDF}            # set NETCDF in your environment

2. Configure the Build script

Open the Build csh script and set HOSTNAME to match your system. This selects the correct compiler flags from the Makefile. You can also change the physics modules here; the defaults are recommended for gSAM–Chem:

# Build — key settings
setenv HOSTNAME  your-cluster-name
setenv ADV_DIR   ADV_MPDATA
setenv SGS_DIR   SGS_TKE
setenv RAD_DIR   RAD_RRTM
setenv MICRO_DIR MICRO_M2005
setenv CHEM_MECH CLOUDCHEM
setenv HET_CHEM  HET_CHEM

3. Compile

Run the Build script from the repository root:

./Build

A successful build produces the executable gSAM in the repository root. Object files are placed in OBJ/.

Running a 2D Simulation

The GoAmazon deep convection case is the reference configuration for gSAM–Chem. A 2D run (single horizontal column, 256 vertical levels) is the fastest way to test a working installation — a 1-day test runs in roughly 15–30 minutes on 16 cores.

1. Set the active case

gSAM–Chem reads the case name from the CaseName file in the repository root. It should already contain the GoAmazon case:

cat CaseName
# goAMAZON_deep_convection

To use a different case, copy an existing case directory into CASES/ and update CaseName accordingly.

Key files in a case directory:

2. Configure the run

Open CASES/goAMAZON_deep_convection/prm and confirm the key namelist parameters. For a 2D test, set ny = 1:

&PARAMETERS
  dx = 66.66666, dy = 66.66666,
  nstop  = 86400,    ! stop after 1 day (seconds)
  nstat  = 300,      ! statistics output interval (seconds)
  nsave2D = 7200,    ! 2D output interval (seconds)
  nsave3D = 7200,    ! 3D output interval (seconds)
  dochem = .true.,
  ...
/

Chemistry switches and parameters are set in the &CHEMISTRY block in the same prm file:

&CHEMISTRY
  do_dry_deposition        = .true.
  do_convective_scavenging = .true.
  do_rainout               = .true.
  do_washout               = .true.
  do_megan_isoprene        = .true.
  do_bdsnp_no              = .true.
  do_CTG_lightning         = .true.
  do_IC_lightning          = .true.
  soil_wetness             = 0.70,   ! MERRA-2 wet season value
  ...
/

3. Submit the job

The repository includes gsam.run at the root — a SLURM submission script that launches gSAM on 256 cores across 8 nodes. Edit it for your cluster and then submit:

# Edit partition and node count for your cluster
nano gsam.run

# SLURM
sbatch gsam.run

# PBS/Torque
qsub gsam.run

For a quick 2D test, reduce --ntasks and mpirun -np to 16–32 cores; a 2D domain scales well at much lower core counts.

Running a 3D Simulation

A 3D simulation adds the second horizontal dimension, enabling resolved convective cells and three-dimensional transport. Budget roughly ~18 hours per simulation day on 256 cores (8 nodes).

To switch from 2D to 3D, increase ny from 1 to your target horizontal extent in prm and scale up the core count in gsam.run accordingly:

# gsam.run — 3D configuration
#SBATCH --ntasks=256
#SBATCH --nodes=8
mpirun -np 256 gSAM | tee sam.log

Output Files

gSAM–Chem writes NetCDF output in several categories:

Output frequencies are controlled in prm:

nsave3D  = 7200    ! 3D output interval (seconds)
nsave2D  = 7200    ! 2D output interval (seconds)
nstat    = 300     ! statistics interval (seconds)

Basic Analysis

The SCRIPTS/ directory includes Python utilities for reading gSAM–Chem output. Open the statistics file:

import netCDF4 as nc
import numpy as np
import matplotlib.pyplot as plt

ds = nc.Dataset('goAMAZON_deep_convection_STATS.ncstat')
t  = ds.variables['time'][:]        # hours
z  = ds.variables['z'][:]           # km
ISOP = ds.variables['ISOP'][:]      # ppb, (time, z)

plt.figure()
plt.pcolormesh(t, z, ISOP.T, shading='auto', cmap='YlGn')
plt.colorbar(label='Isoprene (ppb)')
plt.xlabel('Time (h)'); plt.ylabel('Height (km)')
plt.title('Domain-mean isoprene')
plt.savefig('isoprene_profile.png', dpi=150)

Chemical species in .ncstat and .ncchem files follow the CloudChem naming convention: ISOP, OH, HO2, O3, NO, NO2, HNO3, IEPOX, ISOPOOH, ISOP1Nit, ISOPDiNit, PAN, etc. All concentrations are in ppb.

Next Steps

• Swap the chemistry mechanism — compile any KPP-compatible .kpp file with KPP 3.3.0, place the generated Fortran in SRC/CHEMISTRY/<YourMechanism>/, set CHEM_MECH in the Build script, and recompile.
• Change the large-scale forcing — replace lsf and snd with ARM-format forcing files for a different campaign. gSAM's standard tools for constructing these files work unchanged in gSAM–Chem.
• Extend emissions — additional surface emission fluxes can be added via the emissions module in SRC/CHEMISTRY/emissions.f90.
• Compare with GEOS–Chem — scripts for regridding GEOS–Chem Classic output to gSAM–Chem domain coordinates are included in SCRIPTS/.

Questions? Open an issue on GitHub or contact the development team via the Publications & Team page.