Specifying software libraries for GEOS-Chem
- Minimum system requirements
- Configuring your computational environment
- Downloading source code
- Downloading data directories
- Creating run directories
- Configuring runs
- Output files
- Visualizing and processing output
- Coding and debugging
- Further reading
Selecting pre-built libraries
If you are using GEOS-Chem on your institutions computational cluster, then chances are the sofware libraries that you need will have already been built for you. If this is the case, then it is typically a simple matter to select a certain set of libraries
IMPORTANT NOTE: You should select libraries corresponding to the compiler that you specified . Otherwise, the libraries might not function properly.
Using Lmod modules
As we saw in the previous chapter, the Lmod module system is a convenient way to select not only your compiler, but also the software libraries that you will need to use with GEOS-Chem. You can use the module load command to select the libraries that you need for GEOS-Chem, which typically are:
module load netcdf/4.7.0 # Loads netCDF 4.7.0 module load netcdf-fortran/4.4.0 # Loads netCDF-Fortran 4.4.0 module load git # Loads Git module load flex # Loads Flex (needed to build mechanisms with KPP) module load nco # Loads netCDF Operators, useful for working w/ data files module load cdo # Loads Climate Data operators, useful for working w/ data files module load cmake/3.15 # Loads CMake 3.15, used to build GEOS-Chem (12.6.0 and later) module load gdb # Loads the GDB debugger module load emacs # Emacs editor (if available)
Depending on how your system is maintained, you might have to specify a version number as part of the module name. You can usually use a command such as module avail to find specific implementations of a software library. You can also ask your IT staff which module versions to use.
Also note: depending on the version of netCDF that is installed, you may or may not have to also load netCDF-Fortran separately.
If you or someone at your institution has installed libraries using the Spack package manager, then you can use the spack load command to select the various libraries that you need for GEOS-Chem.
spack load firstname.lastname@example.org spack load email@example.com spack load firstname.lastname@example.org ... etc ..
Spack allows for multiple library implementations (i.e. the same library built with different compiler versions). To minimize confusion, it is always best to include the compiler and version number (%email@example.com) in the spack load commands.
Defining the proper environment variables
In addition to loading the various modules, you must also set some Unix environment variables in order to tell GEOS-Chem where to find the relevant library files.
Environment variables for netCDF
GEOS-Chem will take information about where the various netCDF library paths are located from these environment variables:
|GC_BIN||Points to the bin/ subfolder of the root netCDF path. This is where the nc-config and nf-config files are located.|
|GC_INCLUDE||Points to the include/ subfolder of the root netCDF path. This is where netCDF include files (*.h, *.inc) and compiled module files (*.mod) for the netCDF (and HDF5) libraries are located.|
|GC_LIB||Points to the lib/ subfolder of the root netCDF path. (On some systems this may be named lib64/ instead.) This is where the netCDF library files (*.a) are located.|
The best way to define these variables is to add them to one of your sysetm startup files, such as .bashrc or .bash_aliases.
netCDF via Lmod modules
When you load a netCDF library with a command such as module load netcdf, Lmod will usually add an environment variable such as NETCDF_HOME (or similar name) that denotes the root location of the netCDF library installation. You can then use this environment variable to define the GC_BIN, GC_INCLUDE, and GC_LIB variables with these bash shell commands:
# Tell GEOS-Chem where to find netCDF library files export NETCDF_HOME=path/to/netCDF/library/files/returned/by/Lmod export GC_BIN=$NETCDF_HOME/bin export GC_INCLUDE=$NETCDF_HOME/include export GC_LIB=$NETCDF_HOME/lib
netCDF via Spack
When you load a netCDF library with Spack, you can use the spack location command to point to the root location of the netCDF library installation:
# Tell GEOS-Chem where to find netCDF library files export NETCDF_HOME=`spack location -i firstname.lastname@example.org` export GC_BIN=$NETCDF_HOME/bin export GC_INCLUDE=$NETCDF_HOME/include export GC_LIB=$NETCDF_HOME/lib
In a subsequent chapter, we will see an example script that combines several of these library load commands and environment variable definitions together.
Environment variables for netCDF-Fortran
If (and only if) netCDF-Fortran is installed as a separate library on your system, you will also need to set these variables:
|GC_F_BIN||Points to the bin/ subfolder of the root netCDF Fortran path. This is where the nf-config file is located.|
|GC_F_INCLUDE||Points to the include/ subfolder of the root netCDF Fortran path. This is where netCDF include files (*.h) and compiled module files (*.mod) are located.|
|GC_F_LIB||Points to the lib/ subfolder of the root netCDF Fortran path. (On some systems this may be named lib64/ instead.) This is where the netCDF library files (*.a) are located.|
The best way to define these variables is to add them to one of your sysetm startup files.
If you are using a HPC cluster with the Lmod module manager, then environment variables that point to the root library folders (e.g. NETCDF_HOME, NETCDF_FORTRAN_HOME) will already be loaded into your Unix environment. We recommend using these variables to define the other environment variables as described in following secttions.
If you have any questions about where the library paths for netCDF are located on your system, ask your IT staff.
If you use bash, then add the following lines to one of your Unix environment startup files (e.g. .bashrc, .bash_aliases, etc.):
# NOTE: If netCDF-Fortran was loaded as a separate module, then # also define these variables. (Otherwise comment these out.) export NETCDF_FORTRAN_HOME=path/to/NetCDF-Fortran/library/files export GC_F_BIN=$NETCDF_FORTRAN_HOME/bin export GC_F_INCLUDE=$NETCDF_FORTRAN_HOME/include export GC_F_LIB=$NETCDF_FORTRAN_HOME/lib
Then to accept the changes, type at the Unix prompt: source ~/.bashrc (or source ~/.bash_aliases, etc.)