Specifying software libraries for GEOS-Chem

From Geos-chem
Revision as of 15:10, 16 January 2020 by Bmy (Talk | contribs) (Using 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


On this page, we discuss how to specify the software libraries (such as netCDF) that you will use with GEOS-Chem "Classic".

Please see Setting Up the GCHP Environment for detailed instructions about setting up your computational environment for a GCHP simulation.

Featured tutorial videos

The following tutorials about using Spack to build the compiler and libraries are posted at our GEOS-Chem Youtube channel: youtube.geos-chem.org:

Spack 1 thumbnail.png
Click HERE to view!!
Spack 2 thumbnail.png
Click HERE to view!!

--Bob Yantosca (talk) 14:56, 16 January 2020 (UTC)

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 that have been built with the same compiler that you specified . Otherwise, the libraries might not function properly.

Using a module manager

As we saw in the previous chapter, a module manager such as Lmod or environment-modules is 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, and you have a module manager such as Lmod or environment-modules installed, then you can use the spack load command to select the various libraries that you need for GEOS-Chem. To use spack load, you will also need to make sure that you have either the Lmod package or environment-modules package installed on your system.

spack load netcdf%gcc@9.2.0
spack load netcdf-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.

Spack also allows you to define an environment that can load a set of libraries, in much the same way as how Conda lets you select among multiple Python environments. If the Spack-built libraries on your system have been added to a Spack environment, then you can load the entire environment with a command such as:

spack activate ENVIRONMENT-NAME

and you can deactivate the environment with

despacktivate

--Bob Yantosca (talk) 15:08, 16 January 2020 (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_F_BIN, GC_F_INCLUDE, and GC_F_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
  3. All you need to know about Unix environment variables (Network World)



Previous | Next | Getting Started with GEOS-Chem