Specifying software libraries for GEOS-Chem

From Geos-chem
Revision as of 20:50, 19 December 2019 by Bmy (Talk | contribs) (netCDF-Fortran via Spack)

Jump to: navigation, search

Previous | Next | Getting Started with GEOS-Chem

  1. Minimum system requirements
  2. Configuring your computational environment
  3. Downloading source code
  4. Downloading data directories
  5. Creating run directories
  6. Configuring runs
  7. Compiling
  8. Running
  9. Output files
  10. Visualizing and processing output
  11. Coding and debugging
  12. 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.

--Bob Yantosca (talk) 20:16, 19 December 2019 (UTC)

Using Spack

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 netcdf%gcc@9.2.0
spack load ntcdf-fortran%gcc@9.2.0
spack load flex%gcc@9.2.0
... 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 (%gcc@9.2.0) in the spack load commands.

--Bob Yantosca (talk) 20:23, 19 December 2019 (UTC)

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:

Variable Description
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.

Example: 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

Example: 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 netcdf%gcc@9.2.0`
export GC_BIN=$NETCDF_HOME/bin
export GC_INCLUDE=$NETCDF_HOME/include
export GC_LIB=$NETCDF_HOME/lib

--Bob Yantosca (talk) 20:47, 19 December 2019 (UTC)

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:

Variable Description
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.

Example: netCDF-Fortran via Lmod modules

When you load a netCDF-Fortran library with a command such as module load netcdf-fortran, Lmod will usually add an environment variable such as NETCDF_FORTRAN_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_FORTRAN_HOME=path/to/netCDF-Fortran/library/files/returned/by/Lmod
export GC_BIN=$NETCDF_FORTRAN_HOME/bin
export GC_INCLUDE=$NETCDF_FORTRAN_HOME/include
export GC_LIB=$NETCDF_FORTRAN_HOME/lib

Example: netCDF-Fortran via Spack

When you load a netCDF library with Spack, you can use the spack location command to define an environment variable that points to the root location of the netCDF-Fortran library. 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_FORTRAN_HOME=`spack location -i netcdf-fortran%gcc@9.2.0`
export GC_F_BIN=$NETCDF_FORTRAN_HOME/bin
export GC_F_INCLUDE=$NETCDF_FORTRAN_HOME/include
export GC_F_LIB=$NETCDF_FORTRAN_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.

--Bob Yantosca (talk) 20:47, 19 December 2019 (UTC)

Further reading

  1. Guide to netCDF in GEOS-Chem
  2. Spack documentation



Previous | Next | Getting Started with GEOS-Chem