GCHP Hardware and Software Requirements
- Hardware and Software Requirements
- Downloading Source Code and Data Directories
- Obtaining a Run Directory
- Setting Up the GCHP Environment
- Running GCHP: Basics
- Running GCHP: Configuration
- Output Data
- Developing GCHP
- Run Configuration Files
The following is a short list of hardware requirements for GCHP:
- GCHP requires a minimum of 6 cores to run.
- The number of cores that you run GCHP on must be a multiple of 6.
- Most GCHP and GEOS-Chem Classic users use the Intel Fortran Compiler (ifort). Compatibility with open-source GNU compilers will be in an upcoming version (likely 12.5.0). Regardless of whether you use an Intel compiler or not we highly recommend that you use Intel CPUs, preferably Xeon. It is a known issue that ifort does not optimize well on AMD chips (this was actually intention). Don't worry too much about CPU speed; if you can use Xeon CPUs then you will be OK.
- Most clusters are built upon nodes with 16 to 32 CPUs each. One node of 32 CPUs will provide sufficient resources for standard GCHP c48 runs. It will have the added benefit of not needing to use the network interconnect for MPI.
- GCHP can run with ~7 GB per CPU if using C24, the cubed sphere resolution equivalent to 4° x 5°. Higher resolutions will require more memory per core depending on how many cores you use for your run. We have found that the biggest bottleneck for running high resolution simulations is the amount of memory available per node since it limits the memory available per core. The best solution when running into memory per core limitations is to request more nodes, reserve all memory per node by requesting all cores, and use fewer cores per node than you have requested for your actual GCHP run.
- InfiniBand is recommended if you can afford it. If not, a 10 Gigabit Ethernet is a good alternative when using high-end interconnects like Cisco or high-end Hewlett-Packard (HP). A 1000 Mbps Gigabit Ethernet should also work if you get an optimized router like Cisco or HP, but it will be less speed-dependent and have more packet latency. This is minimized in the high-end network interconnects.
- If you are using an interconnect, it would be very helpful if the system had two: one interconnect for file transfer, log-in, etc, and the other interconnect for MPI-only communication. Using two interconnects in this way prevents problems such as file I/O interfering with MPI packet transfer. This is probably now standard on turn-key systems. Ask your local cluster administrator what is available for you to use.
The recommended software detailed in this section is standard on many primary HPC systems in use by academic and scientific institutions. GCHP requires C and Fortran compilers, an implementation of a Message Passing Interface (MPI), C-preprocessor software, and netCDF C and Fortran libraries. Utility tools available from the GCHP Makefile assume use of git version control software. If any of the required software is not available then you must acquire it to compile and run GCHP.
Please be aware that it is absolutely necessary to use the same compilers, whether Fortran or C, when compiling GEOS-Chem, GCHP, MPI, NetCDF and their prerequisites. For systems with pre-installed packages, such as an institutional compute cluster, you must determine how each package was compiled to ensure that you will be able to build and run GCHP successfully. If your pre-installed packages were not built with the same compilers then you will need to build them yourself or have them built for you by your organization's technical support staff.
We are currently only supporting GCHP on Linux distributions.
You should acquire source code by cloning or forking the GEOS-Chem and GCHP repositories on GitHub using git. The GCHP Makefile assumes use of git version >1.8. Otherwise you will get an error that the -C option is not available. Check the default git version on your cluster by typing 'git --version' at the command line. If you have version 1.8 and prior then check with your system administrator on modules available with a more recent version of git, or download a newer version for free from the web.
If you are new to git then you should take time to get familiar with it. The UCAR CESM project has an excellent git guide, CIME Git Workflow, that is a great resource regardless of your skill level. The same basic workflow can be used for GEOS-Chem.
The Message Passing Interface (MPI) is the fundamental requirement for distributed memory computing. Past reported successful GCHP tests have used OpenMPI, MVAPICH2, MPICH, and SGI MPT. MVAPICH2 is a derivation of MPICH for use with the Infiniband interconnect. All tests were configured with Intel Fortran + Intel C, Intel Fortran + GNU C, or GNU Fortran + GNU C.
Please note that we have had reports of diagnostic write problems when using MPICH and MVAPICH2 on some systems. Switching to OpenMPI version 3.0 or 3.1 appears to resolve the problems. We therefore recommend trying OpenMPI 3 before other implementations of MPI if possible. See the GCHP issues page on GitHub for more information.
You may test which compiler your version of MPI is using with:
$ mpif90 --version (for Fortran Compiler) $ mpicc --version (for C compiler)
GCHP has been successfully compiled with the GNU Compiler Collection (GCC) and the Intel Fortran Compiler (ifort). A summary of reported version compatibility is displayed in the table below. Our testing is not exhaustive so compilers not listed may be compatible with GCHP.
*** Important *** There is a run-time bug in GCHP when using GCC compilers that results in an incorrect land mask. We recommend that users not compile GCHP with gfortran until this bug is resolved which will be when we upgrade the MAPL version in GCHP. We are aiming to put this update into GEOS-Chem 12.5.0. See the wiki post on this issue for more information.
|Compiler||GCHP Versions Tested||Result|
|Intel Fortran 13||v11-02b||Relatively slow compared to more recent versions of ifort|
|Intel Fortran 14||DevKit||Failed to compile prerequisite libraries|
|Intel Fortran 15||v11-02d||Success|
|Intel Fortran 16||v11-02d||Success
|Intel Fortran 184.108.40.206||12.2.0||Fail|
|Intel Fortran 17.0.4||12.2.0||Success; earlier versions of ifort17 are buggy and should not be used|
|Intel Fortran 18.1.163||12.2.0||Success|
|GNU Compiler Collection 5.2.0||v11-02c,v11-02d||Success|
|GNU Compiler Collection 7.1.0||v11-02-release-candidate||Success|
|GNU Compiler Collection 8.2||12.2.0||Compilation successful, but run fails. See the wiki post on this issue for more information.|
We have found that IFORT 17.0.4 works best with OpenMPI MPI 3 implementations on the Harvard Odyssey cluster using Intel chips. Compiling with ifort on AMD chips results in a significant slow-down due to the design of the compiler.
If you have tried to compile GCHP with a compiler or version not listed above please contact the GEOS-Chem Support Team to report your findings.
The ESMF library
The ESMF library provides a software infrastructure that allows different components of Earth System Models to communicate each other, using MPI parallelization. For more information about ESMF, please see: https://www.earthsystemcog.org/projects/esmf/
NOTE: At present (Jun 2019), an ESMF installation comes with GCHP, but in the near future, GCHP will use ESMF as an external software dependency.
To compile certain ESMF components in GCHP, a compatible C pre-processor (cpp) needs to be available. If you are having compilation errors in the GCHP/Shared directory, you may check your C pre-processor version with the following command:
$ cpp --version
cpp versions in the 4.x series (4.8.5) have been used to successfully build GCHP, while at least one version in the 5.x series (5.4.0) have failed to correctly process the Fortran sources in the Shared directories for compilation.
A netCDF library installation is required to run GCHP. If you are using 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. Please note that parallel reading and writing requires netCDF-4 and requires that it be compiled with parallel-enabled HDF5 libraries. NetCDF-3 does not have parallel capabilities.
Starting with netCDF-4.2, the Fortran netCDF library split off as an independent distribution to be built after building the C library. Prior to that version the Fortran netCDF library was bundled with the C library in a single distribution of netCDF. We have successfully built GCHP using versions of netCDF both before and after the split. The only difference to be aware of is that using netCDF-4.2 requires setting additional environment variables.
If you are using netCDF-4.2 and later versions then you will need to include the following in your bashrc (this example assumes you are using bash):
export GC_BIN="$NETCDF_HOME/bin" export GC_INCLUDE="$NETCDF_HOME/include" export GC_LIB="$NETCDF_HOME/lib" export GC_F_BIN="$NETCDF_FORTRAN_HOME/bin" export GC_F_INCLUDE="$NETCDF_FORTRAN_INCLUDE" export GC_F_LIB="$NETCDF_FORTRAN_LIB"
If using earlier versions of netCDF (prior to 4.2) then you should only include the following:
export GC_BIN="$NETCDF_HOME/bin" export GC_INCLUDE="$NETCDF_HOME/include" export GC_LIB="$NETCDF_HOME/lib"
These environment variables are included in the sample GCHP bashrc files included in all GCHP run directories. Please see the Getting Started with GCHP section of the wiki for more information on setting up your environment. Just remember that if you change any of the sample bash environment files to work on your system then you should check your netCDF version number to determine what environment variables you need.