GEOS-Chem Classic

This site provides instructions for GEOS-Chem Classic, the single-node mode of operation of the GEOS-Chem model. We provide instruction for downloading and compiling GEOS-Chem Classic, plus its required software libraries.

Note

If you would like to run GEOS-Chem on more than one node of a computing system, consider using GEOS-Chem High Performance (GCHP).

GEOS-Chem is a global 3-D model of atmospheric composition driven by assimilated meteorological observations from the Goddard Earth Observing System (GEOS) of the NASA Global Modeling and Assimilation Office. It is applied by research groups around the world to a wide range of atmospheric composition problems.

• GEOS-Chem Overview

• Narrative description of GEOS-Chem

Cloning and building from source code ensures you will have direct access to the latest available versions of GEOS-Chem Classic, provides additional compile-time options, and allows you to make your own modifications to GEOS-Chem Classic source code.

Getting Started

• Quickstart Guide
  • 1. Clone GEOS-Chem Classic
  • 2. Create a run directory
  • 3. Load your environment
  • 4. Configure your build
  • 5. Compile and install
  • 6. Configure your run directory
  • 7. Download input data
  • 8. Run your simulation
• Meet all hardware requirements
  • Computer system
  • Memory requirements
  • Disk space requirements
• Meet all software requirements
  • Supported compilers
  • Required software packages
  • Optional but recommended software packages
• Customize your login environment
  • Environment files
  • Sample environment file for GNU 12.2.0 compilers
  • Sample environment file for Intel 2023 compilers
  • Set environment variables for compilers
  • Set environment variables for parallelization
• Key references

GEOS-Chem Classic User Guide

• Download source code
  • Source code repositories
  • Download instructions
• Create a run directory
  • First-time user registration
  • Example: Create a full-chemistry simulation run directory
  • Example: Create a carbon gases simulation run directory
  • Run directory files and folders
• Compile the source code
  • Configure with CMake
  • Compile with Make
  • Get a summary of compilation options
• Configure your simulation
  • Commonly-updated configuration files
  • Less-commonly updated configuration files
• Download input data
  • GEOS-Chem Input Data on AWS cloud
  • Additional portals for meteorology data
  • Restart files
  • Download data with a dry-run simulation
• Run your simulation
  • Create a run script
  • Complete this pre-run checklist
  • Submit your run script to a scheduler
  • Or run the script from the command line
  • Verify a successful simulation
  • Minimize differences in multi-stage runs
  • Speed up a slow simulation
• View output files
  • Log files
  • History diagnostics output
  • Other diagnostic output files
• Diagnostics reference
  • GEOS-Chem History diagnostics
  • HEMCO diagnostics
  • Planeflight diagnostic
  • ObsPack diagnostic

GEOS-Chem Simulations

• Aerosol-only simulation
  • Overview
  • List of species
• Carbon gases simulation
  • Overview
  • List of species
• Fullchem simulation
  • Overview
  • List of species, by option
    • Standard
    • Benchmark
    • Complex SOA
    • Complex SOA plus semi-volatile POA
    • Marine POA
    • Acid uptake on dust
    • TOMAS aerosol microphysics
    • APM aerosol microphysics
    • RRTMG radiative transfer model
• Hg (mercury) simulation
  • Overview
  • List of species
• Metals simulation
  • Overview
  • List of species
• Tagged O3 simulation
  • Overview
  • List of species
• TransportTracers simulation
  • Overview
  • List of species

Supplemental guides

• GEOS-Chem Classic folder tree
• Sample GEOS-Chem run scripts
  • For clusters using the Slurm scheduler
    • Run script for Slurm
    • Submitting jobs with Slurm
  • For Amazon Web Services EC2 cloud instances
    • Run script for Amazon EC2
    • Running jobs on AWS
• Load software into your environment
  • On the Amazon Web Services Cloud
  • On a shared computer cluster
    • 1. Check if libraries are available as modules
      • 1a. Module load example
    • 2. Check if Spack-built libraries are available
    • 3. Check if libaries have been manually installed
    • 4. If there are none of these, install them with Spack
• Build required software with Spack
  • Introduction
  • Install Spack and do first-time setup
  • Clone a copy of GCClassic, GCHP, or HEMCO
  • Install the recommended compiler
  • Build GEOS-Chem dependencies and useful tools
  • Add spack load commands to your environment file
  • Clean up
• Customize simulations with research options
  • Aerosols
    • Aerosol microphysics
      • APM
      • TOMAS
  • Chemistry
    • Adaptive Rosenbrock solver with mechanism auto-reduction
    • Alternate chemistry mechanisms
      • Carbon mechanism
      • Custom full-chemistry mechanism
      • Hg mechanism
    • HO2 heterogeneous chemistry reaction probability
    • TransportTracers
  • Diagnostics
    • GEOS-Chem and HEMCO diagnostics
    • RRTMG radiative transfer diagnostics
  • Emissions
    • Offline vs. online emissions
      • Example: Disabling offline dust emissions
    • Sea salt debromination
  • Photolysis
    • Particulate nitrate photolysis
  • Wet deposition
    • Luo et al 2020 wetdep parameterization
• Understand what error messages mean
  • Where does error output get printed?
  • Compile-time errors
    • Cannot open include file netcdf.inc
    • KPP error: Cannot find -lfl
    • GNU Fortran internal compiler error
    • This module file was not generated by any release of this compiler
  • Run-time errors
    • Excessive fall velocity error
    • Floating invalid or floating-point exception error
    • Forced exit from Rosenbrock
      • More about KPP error tolerances
    • GEOS-Chem Classic simulation failed after TPCORE initialization
    • HEMCO Error: Cannot find field
    • HEMCO Error: Cannot find file for current simulation time
    • HEMCO Error: Cannot get field PS_NEXTDAY
    • HEMCO ERROR: Not enough time slices: BC_<species-name>
    • HEMCO Error: Time stamps may be wrong
    • HEMCO Run Error
    • Integrator error code: -5, STOP at INTEGRATE_KPP
    • libnetcdff.so.7: cannot open shared object file: No such file or directory
    • Negative tracer found in WETDEP
    • Permission denied error
  • File I/O errors
    • List-directed I/O syntax error
    • NF90_Def_Var: Can not create compressed variable
    • NF90_Def_Var: Can not define variable
    • NetCDF: HDF Error
    • NetCDF: Variable not found
  • Segmentation faults and similar errors
    • Array-out-of-bounds error
    • Segmentation fault encountered after TPCORE initialization
    • Invalid memory access
    • Stack overflow
  • Less commmon errors
    • Bus Error
    • Double free or corruption
    • Dwarf subprogram entry error
    • Free: invalid size
    • Munmap_chunk: invalid pointer
    • Out of memory asking for NNNNN
• Debug GEOS-Chem and HEMCO errors
  • Check if a solution has been posted to Github
  • Check if your computational environment is configured properly
  • Check any code modifications that you have added
  • Check if your runs exceeded time or memory limits
  • Send debug printout to the log files
  • Look at the traceback output
  • Identify whether the error happens consistently
  • Isolate the error to a particular operation
  • Compile with debugging options
  • Use a debugger
  • Print it out if you are in doubt!
  • Use the brute-force method when all else fails
  • Identify poorly-performing code with a profiler
• Manage a data archive with bashdatacatalog
  • What is bashdatacatalog?
  • Usage instructions
• Archive output with the History diagnostics
  • Introduction
    • The HISTORY.rc configuration file
      • Sample HISTORY.rc file
    • Wildcards (GEOS-Chem Classic only)
    • Prefixes
    • File naming convention
    • Vertical coordinates in netCDF files
  • Diagnostic collections
    • AdvFluxVert
    • AerosolMass
    • Aerosols
    • BoundaryConditions
    • Budget
    • Carbon
    • CH4
    • CloudConvFlux
    • CO
    • CO2
    • ConcAboveSfc
    • ConcAfterChem
    • DryDep
    • JValues
    • KppARDiags
    • KppDiags
    • LevelEdgeDiags
    • MercuryChem
    • MercuryEmis
    • MercuryOcean
    • Metrics
    • ProdLoss
    • RadioNuclide
    • Restart
    • RRTMG
    • RxnConst
    • RxnRates
    • SatDiagn
    • SatDiagnEdge
    • SpeciesConc
    • StateChm
    • StateMet
    • StratBM
    • Tomas
    • UVFlux
    • WetLossConv
    • WetLossLS
  • Adding new History diagnostics
• Work with netCDF files
  • Useful tools
  • Examine the contents of a netCDF file
  • Read the contents of a netCDF file
    • Read data with Python
    • Read data from multiple files in Python
  • Determining if a netCDF file is COARDS-compliant
  • Edit variables and attributes
  • Concatenate netCDF files
    • Concatenate with the netCDF operators
    • Concatenate with Python
  • Regrid netCDF files
    • Regrid with cdo
      • Issue with cdo remapdis regridding tool
    • Regrid with GCPy
    • Regrid with nco
    • Regrid with xarray
    • Regrid with xESMF
  • Crop netCDF files
  • Add a new variable to a netCDF file
  • Chunk and deflate a netCDF file to improve I/O
• Prepare COARDS-compliant netCDF files
  • The COARDS netCDF standard
  • COARDS dimensions
  • COARDS coordinate vectors
    • time
      • Special considerations for time vectors
    • lev
      • Additional considerations for lev vectors:
    • lat
    • lon
  • COARDS data arrays
    • Attributes for data arrays
    • Ordering of the data
  • COARDS Global attributes
  • For more information
• View GEOS-Chem species properties
  • Species properties defined
    • Required default properties
    • Identification
    • Physical properties
    • Dry deposition properties
    • Wet deposition properties
    • Transport tracer properties
      • Properties used by each transport tracer
    • Other properties
  • Access species properties in GEOS-Chem
    • The Species derived type
    • The SpcPtr derived type
    • The GEOS-Chem Species Database object
    • Species index lookup with Ind_()
    • Species lookup within a loop
• Parallelize GEOS-Chem and HEMCO source code
  • Overview of OpenMP parallelization
  • Example using OpenMP directives
  • Environment variable settings for OpenMP
  • OpenMP parallelization FAQ
    • How can I tell what should go into the !$OMP PRIVATE clause?
    • Why do the !$OMP statements begin with a comment character?
    • Do subroutine variables have to be declared PRIVATE?
    • What does the THREADPRIVATE statement do?
    • Can I use pointers within an OpenMP parallel loop?
    • How many cores may I use for GEOS-Chem or HEMCO?
    • Why is GEOS-Chem is not using all the cores I requested?
  • MPI parallelization
• Run nested-grid simulations
  • Run a global simulation to create boundary conditions
    • 1. Download the GEOS-Chem source code
    • 2. Create a global simulation run directory
    • 3. Activate the BoundaryConditions diagnostic collection
    • 4. Configure the global simulation
    • 5. Compile GEOS-Chem and run the global simulation
  • Set up your nested grid run directory
    • 1. Create a nested-grid simulation run directory
    • 2. Configure your nested-grid simulation
    • 3. Copy the executable to the nested-grid run directory
    • 4. Run the nested-grid simulation
  • Frequently asked questions
    • Can I run nested GEOS-Chem simulations on the AWS cloud?
    • Can I save out boundary conditions for more than one nested grid in the same global run?
    • How can I find which data are available for nested grid simulations?
    • Where can I find out more info about nested grid errors?
    • I noticed abnormal concentrations at boundaries of the nested region. Is that normal?
• Update chemical mechanisms with KPP
  • Using KPP: Quick start
    • 1. Navigate to the KPP/custom folder within GEOS-Chem
    • 2. Edit the chemical mechanism configuration files
      • custom.eqn
      • custom.kpp
    • 3. Run the build_mechanism.sh script
    • 4. Recompile GEOS-Chem with your custom mechanism
  • Using KPP: Reference section
    • Adding species to a mechanism
    • Adding reactions to a mechanism
      • Gas-phase reactions
      • Gas-phase reactions: General form
      • Rates for two-body reactions according to the Arrhenius law
      • Other rate-law functions
      • Making your rate law functions computationally efficient
    • Heterogeneous reactions
    • Photolysis reactions
    • Adding production and loss families to a mechanism
    • Changing the numerical integrator
• Use the KPP-Standalone box model to test chemical mechanisms
  • Source code
    • KPP-Standalone Interface
    • KPP-Standalone Box Model
  • Usage instructions
• View related documentation

Help & Reference

• GEOS-Chem version history
• Known bugs and issues
• Contributing Guidelines
• Support Guidelines
• Editing this User Guide