GEOS-Chem Installation and Run log

In this post, I document the complete process of installing and configuring the GEOS-Chem Classic model, including environmental setup, compilation, and runtime configuration. The log is based on my experience running GEOS-Chem on a Linux HPC system, and covers both the challenges I encountered and the solutions I implemented.

1. Environmental Setup

GEOS-Chem requires a proper build environment.

export DIR=/data/user/hao_y/lib
export HDF5_DIR=$DIR/hdf5
export NETCDF_DIR=$DIR/netcdf
export PATH=$DIR/gcc-13.2.0/bin:$HDF5_DIR/bin:$NETCDF_DIR/bin:$PATH
export LD_LIBRARY_PATH=$DIR/gcc-13.2.0/lib64:$HDF5_DI

2. GEOS-Chem Classic initiiation

2.1 Clone and Initialize

git clone --recurse-submodules https://github.com/geoschem/GCClassic.git
cd GCClassic/run
./createRunDir.sh

2.2 Run Directory Configuration

My setting is as follows:

• Simulation: Full chemistry
• Complex SOA with semivolatile POA
• Meteorology: GEOS-FP
• Resolution: 0.25° × 0.3125°
• Domain: Asia (manually adjusted to South Asia later)
• Vertical Levels: 72 (native)

2.3 Compilation

Go into the run directory and install

cd runs/gc_025_SAsia_2018/gc_025x03125_AS_geosfp_fullchem_complexSOA/
cd build
cmake ../CodeDir -DRUNDIR=..
make -j 16
make install

After building, adjust these configuration files:
geoschem_config.yml,HISTORY.rc,HEMCO_Config.rc

3. Input Data Handling

3.1 Dry Run and AWS Setup

To determine required meteorological and restart data:

./gcclassic --dryrun | tee log.dryrun

# install the AWS service command line service tool.
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
./aws/install -i ~/aws-cli -b ~/bin

aws s3 ls --no-sign-request s3://geos-chem/
./download_data.py log.dryrun geoschem+aws

3.2 Download the data

./download_data.py log.dryrun geoschem+aws

3.3 Fixing restart file timestamp errors

Sometimes AWS pulls a misaligned restart file. Manually download the correct one, for example:

wget http://geoschemdata.wustl.edu/ExternalShare/geos-chem/10yr_benchmarks/14.0.0/GCClassic/Restarts/2018/GEOSChem.Restart.20181001_0000z.nc4

Place it into the Restarts/ directory of your run folder.

4. SLURM Run Script (run_gcclassic.slurm)

Simply run by sbatch run_gcclassic.slurm to start the simulation, and there will be email to remind when the simulation was done.

#!/bin/bash

#SBATCH -c 256                 # Request 16 cores
#SBATCH -N 1                   # Use 1 node
#SBATCH -t 6-00:00             # Max runtime of 12 hours
#SBATCH -p general             # <-- Replace iwith actual partition name
#SBATCH --mem=400000            # Request 400 GB memory
#SBATCH --job-name=gcclassic_run
#SBATCH --output=gcclassic_%j.out
#SBATCH --error=gcclassic_%j.err
#SBATCH --mail-type=END
#SBATCH --mail-user=yufang.hao@psi.ch  # <-- Add this if you want email alerts

###############################################################################
### GEOS-Chem Classic run script for SLURM (MERLIN cluster)
###############################################################################

# Load your GCC 13.2.0 environment
source ~/.bashrc

# Optionally load other environment modules if needed (HDF5, NetCDF, etc.)

# Remove stack size limit to prevent segfaults
ulimit -s unlimited

# (Optional) log current limits
ulimit -a

# Set OpenMP threads
export OMP_STACKSIZE=1G
export OMP_NUM_THREADS=$SLURM_CPUS_PER_TASK

# Run GEOS-Chem Classic
srun -c $OMP_NUM_THREADS time -p ./gcclassic >> GC.log

# Exit
exit 0

5. Debugging and Errors

5.1 Segmentation Fault

If encoutering:
Investigated via gdb, pinpointed to cldj_fjx_sub_mod.F90, line 1457:

DD(I,J,L,K) = -E(I,J)*C(J,L,K)

Likely due to unallocated or incorrectly dimensioned array.

I found increase the memory could be helpful, so in the

• Increased --mem=64000 (64 GB) to --mem=400000.
• Ensured ulimit -s unlimited applied

6. Output Control and Optimization

6.1. Optmization of exectuable speed

1. In HISTORY.rc, I disabled species output to save time and space.
2. In geoschem_config.yml,

autoreduce_solver:
  activate: true

This can help reduce runtime by simplifying the chemical solver dynamically.

7. Job Monitoring

Submit:

sbatch run_gcclassic.slurm

Monitor:

squeue -u $USER
scontrol show job <JOBID>

Stop

scancel <JOBID>

Check logs:

cat gcclassic_<JOBID>.out
cat gcclassic_<JOBID>.err

A simple example of the results

References

1. GEOS-Chem User Guides and Documentation
   GEOS-Chem Official Website: https://geos-chem.org
   User Documentation: https://geos-chem.readthedocs.io

2. GEOS-Chem GitHub Repository
   Source code and run directory setup: https://github.com/geoschem/GCClassic

3. GEOS-Chem Input Data on AWS
   https://registry.opendata.aws/geos-chem

4. AWS CLI Installation Guide
   https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html

5. GEOS-Chem Error Troubleshooting Guide
   https://geos-chem.readthedocs.io/en/14.2.2/geos-chem-shared-docs/supplemental-guides/error-guide.html