Installing libraries for GEOS-Chem

From Geos-chem
Jump to: navigation, search

On this page we provide instructions on how to install netCDF-4 and related libraries for GEOS-Chem.

Check to see if netCDF is already installed on your system

If you are going to use GEOS-Chem on a shared computer system, chances are that your IT staff will have already installed one or more netCDF library versions that you can use. On many computer systems, you can load pre-compiled libraries and software packages (such as netCDF, HDF5, IDL ifort compiler, etc.) with the module command. Check with your system administrator or IT staff to see if module is already installed on your system. If it is, we recommend that you use module to load a version of the netCDF libraries into your computing environment.

You can load a combination of compiler and netCDF libraries in the same command. For example:

   module load intel netcdf

will load the default Intel Fortran Compiler version and the default netCDF version that was built with the Intel Fortran Compiler. You can also load specific compiler and netCDF versions by giving the version numbers, such as:

   module load intel/13.0.0.079 netcdf/intel/4.1.3

You can place these module load commands into your .bashrc or .cshrc startup file so that they will be executed every time you log in.

On most computer systems, the module command will also export one or more environment variables containing the directory paths where the libraries and relevant files can be found. This will allow you to always find the proper netCDF library on disk without having to hardwire the directory path in your .bashrc or .cshrc system startup file.

For example, the module load command listed above will export the NETCDF_HOME, NETCDF_INCLUDE, and NETCDF_LIB variables into your Unix environment. The NETCDF_HOME variable is the root folder of the netCDF library. Include files (*.h) and compiled module files (*.mod) are stored in the NETCDF_INCLUDE folder. Library files (*.a) are stored in the NETCDF_LIB folder.

The names of these environment variables will differ from system to system. Ask your IT staff about how the module command is implemented on your computer.

Special handling for netCDF-4.2 and higher versions

The C and Fortran library files are built from different installation packages in netCDF-4.2 and higher versions. Because of this dichotomy, your IT staff may have installed the netCDF Fortran library as a completely separate software module.

For example, we use these commands on the Odyssey cluster at Harvard to load the version of netCDF that was compiled with the GNU Fortran compiler:

   module load gcc/4.8.2-fasrc01      openmpi/1.10.1-fasrc01
   module load netcdf/4.3.3.1-fasrc02 netcdf-fortran/4.4.2-fasrc01

As you can see, the netCDF Fortran library (version 4.4.2) has to be loaded separately from the netCDF C-language library (version 4.3.3.1). In this particular case, both the netCDF C and Fortran libraries also rely on the OpenMPI library (although GEOS-Chem "Classic" doesn't need it).

The above module load commands will export the following variables into your Unix environment: NETCDF_HOME, NETCDF_INCLUDE, NETCDF_LIB, NETCDF_FORTRAN_HOME, NETCDF_FORTRAN_INCLUDE, NETCDF_FORTRAN_LIB.

Because the netCDF Fortran library is loaded as a separate module, it has own environment variables (NETCDF_FORTRAN_HOME, NETCDF_FORTRAN_INCLUDE, NETCDF_FORTRAN_LIB) to define the relevant directory paths. These are analogous to NETCDF_HOME, NETCDF_INCLUDE, and NETCDF_LIB as mentioned in the prior section.

If you don't have netCDF on your system, use Spack to install it

The GEOS-Chem-Libraries installer contains library versions that might not be compatible with the most recent Linux/Ubuntu/Fedora operating systems and gcc/gfortran and icc/ifort compilers. In particular, several users have noticed that the build fails for gcc/gfortran compiler versions 4.8 and higher.

If you do not already have a pre-built netCDF library on your system, we recommend using the Spack package manager to install the required libraries. Spack should be able to install netCDF and all required libraries for a variety of compiler/platform combinations.

Downloading Spack

Clone the Spack repository, which is hosted at Github, to your disk space:

git clone https://github.com/spack/spack.git

Using Spack to install netCDF libraries

Then install the libraries by issuing these commands:

cd spack/bin

./spack install netcdf-cxx4 netcdf-fortran

The initial installation may take more than a half-hour to complete.

Pointing GEOS-Chem environment variables to the Spack library paths

To find the root paths where Spack has installed these libraries, type:

spack find --paths netcdf-cxx4
spack find --paths netcdf-fortran

And then define the environment variables in your .bashrc startup script (or .cshrc if you are using csh/tcsh) to point to the following folders:

GC_BIN        --> point this to the bin     sub-folder of the netcdf-cxx4 root path
GC_INCLUDE    --> point this to the include sub-folder of the netcdf-cxx4 root path
GC_LIB        --> point this to the lib     sub-folder of the netcdf-cxx4 root path

GC_F_BIN      --> point this to the bin     sub-folder of the netcdf-fortran root path
GC_F_INCLUDE  --> point this to the include sub-folder of the netcdf-fortran root path
GC_F_LIB      --> point this to the lib     sub-folder of the netcdf-fortran root path

For more information

For complete instructions on using Spack, please see: https://spack.readthedocs.io/en/latest/.

If you encounter an error while using Spack, it could be due to an incompatibility with your particular compiler/platform combination. We encourage you to report all issues to the Spack developers by opening a ticket on the Spack issue tracker: https://github.com/spack/spack/issues

--Bob Yantosca (talk) 20:48, 27 November 2018 (UTC)