Skip to content
forked from GEOS-ESM/GEOSgcm

GEOS Earth System Model GEOSgcm Fixture

License

Notifications You must be signed in to change notification settings

senchiao/GEOSgcm

 
 

Repository files navigation

GEOS GCM Fixture

CI Status

CI Provider Status
CircleCI CircleCI
AWS CodeBuild CodeBuild
GitHub GitHub

Current State of GEOSgcm Subrepos

Repository Version
CICE geos/v0.0.2
CPLFCST_Etc v1.0.1
ecbuild geos/v1.3.0
ESMA_cmake v3.31.0
ESMA_env v4.19.0
FMS geos/2019.01.02+noaff.8
FVdycoreCubed_GridComp v2.5.0
geos-chem geos/v13.0.0-rc1
GEOS_OceanGridComp v2.1.1
GEOS_Util v2.0.2
GEOSchem_GridComp v1.12.2
GEOSgcm_App v2.2.1
GEOSgcm_GridComp v2.1.4
GEOSradiation_GridComp v1.4.0
GFDL_atmos_cubed_sphere geos/v2.4.1
GMI v1.0.0
GMAO_Shared v1.9.1
GOCART sdr_v2.1.2.7
HEMCO geos/v2.2.3
Icepack geos/v0.0.2
MAPL v2.40.0
MITgcm checkpoint68o
MOM5 geos/5.1.0+1.2.0
MOM6 geos/v2.2.0
NCEP_Shared v1.2.1
QuickChem v1.0.0
RRTMGP geos/v1.6+1.1.0
SIS2 geos/v0.0.1
StratChem v1.0.0
TR v1.0.0
UMD_Etc v1.3.0

How to build GEOS GCM

Preliminary Steps

Load Build Modules

In your .bashrc or .tcshrc or other rc file add a line:

NCCS
module use -a /discover/swdev/gmao_SIteam/modulefiles-SLES12
NAS
module use -a /nobackup/gmao_SIteam/modulefiles
GMAO Desktops

On the GMAO desktops, the SI Team modulefiles should automatically be part of running module avail but if not, they are in:

module use -a /ford1/share/gmao_SIteam/modulefiles

Also do this in any interactive window you have. This allows you to get module files needed to correctly checkout and build the model.

Now load the GEOSenv module:

module load GEOSenv

which obtains the latest git, CMake, and mepo modules.

Obtain the Model

On GitHub, there are three ways to clone the model: SSH, HTTPS, or GitHub CLI. The first two are "git protocols" which determine how git communicates with GitHub: either through https or ssh. (The latter is a CLI that uses either ssh or https protocol underneath.)

For developers of GEOS, the SSH git protocol is recommended as it can avoid some issues if two-factor authentication (2FA) is enabled on GitHub.

SSH

To clone the GEOSgcm using the SSH url (starts with [email protected]), you run:

git clone -b vX.Y.Z [email protected]:GEOS-ESM/GEOSgcm.git

where vX.Y.Z is a tag from a GEOSgcm release. Note if you don't use -b, you will get the main branch and that can change from day-to-day.

Permission denied (publickey)

If this is your first time using GitHub with any SSH URL, you might get this error:

Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

If you do see this, you need to upload an ssh key to your GitHub account. This needs to be done on any machine that you want to use the SSH URL through.

HTTPS

To clone the model through HTTPS you run:

git clone -b vX.Y.Z https://github.com/GEOS-ESM/GEOSgcm.git

where vX.Y.Z is a tag from a GEOSgcm release. Note if you don't use -b, you will get the main branch and that can change from day-to-day.

Note that if you use the HTTPS URL and have 2FA set up on GitHub, you will need to use personal access tokens as a password.

GitHub CLI

You can also use the GitHub CLI with:

gh repo clone GEOS-ESM/GEOSgcm -- -b vX.Y.Z

where vX.Y.Z is a tag from a GEOSgcm release. Note if you don't use -b, you will get the main branch and that can change from day-to-day.

Note that when you first use gh, it will ask what your preferred git protocol is (https or ssh) to use "underneath". The caveats above will apply to whichever you choose.


Single Step Building of the Model

If all you wish is to build the model, you can run parallel_build.csh from a head node. Doing so will checkout all the external repositories of the model and build it. When done, the resulting model build will be found in build/ and the installation will be found in install/ with setup scripts like gcm_setup and fvsetup in install/bin.

Develop Version of GEOS GCM

parallel_build.csh provides a special flag for checking out the development branches of GEOSgcm_GridComp, GEOSgcm_App, GMAO_Shared, and GEOS_Util. If you run:

parallel_build.csh -develop

then mepo will run:

mepo develop GEOSgcm_GridComp GEOSgcm_App GMAO_Shared GEOS_Util

Debug Version of GEOS GCM

To obtain a debug version, you can run parallel_build.csh -debug which will build with debugging flags. This will build in build-Debug/ and install into install-Debug/.

Do not create and install source tarfile with parallel_build

Note that running with parallel_build.csh will create and install a tarfile of the source code at build time. If you wish to avoid this, run parallel_build.csh with the -no-tar option.

Passing additional CMake options to parallel_build.csh

While parallel_build.csh has many options, it does not cover all possible CMake options possible in GEOSgcm. If you wish to pass additional CMake options to parallel_build.csh, you can do so by using -- and then the CMake options. Note that anything after the -- will be interpreted as a CMake option, which could lead to build issues if not careful.

For example, if you want to build a develop Debug build on Cascade Lake while turning on StratChem reduced mechanism and the CODATA 2018 options:

parallel_build.csh -develop -debug -cas -- -DSTRATCHEM_REDUCED_MECHANISM=ON -DUSE_CODATA_2018_CONSTANTS=ON

As noted above all the "regular" parallel_build.csh options must be listed before the -- flag.


Multiple Steps for Building the Model

The steps detailed below are essentially those that parallel_build.csh performs for you. Either method should yield identical builds.

Mepo

The GEOS GCM is comprised of a set of sub-repositories. These are managed by a tool called mepo. To clone all the sub-repos, you can run mepo clone inside the fixture:

cd GEOSgcm
mepo clone

The first command initializes the multi-repository and the second one clones and assembles all the sub-repositories according to components.yaml

Checking out develop branches of GEOSgcm_GridComp, GEOSgcm_App, GMAO_Shared, and GEOS_Util

To get development branches of GEOSgcm_GridComp, GEOSgcm_App, GMAO_Shared, and GEOS_Util (a la the -develop flag for parallel_build.csh, one needs to run the equivalent mepo command. As mepo itself knows (via components.yaml) what the development branch of each subrepository is, the equivalent of -develop for mepo is to checkout the development branches of GEOSgcm_GridComp, GEOSgcm_App, GMAO_Shared, and GEOS_Util:

mepo develop GEOSgcm_GridComp GEOSgcm_App GMAO_Shared GEOS_Util

This must be done after mepo clone as it is running a git command in each sub-repository.

Build the Model

Load Compiler, MPI Stack, and Baselibs

On tcsh:

source @env/g5_modules

or on bash:

source @env/g5_modules.sh
Create Build Directory

We currently do not allow in-source builds of GEOSgcm. So we must make a directory:

mkdir build

The advantages of this is that you can build both a Debug and Release version with the same clone if desired.

Run CMake

CMake generates the Makefiles needed to build the model.

cd build
cmake .. -DBASEDIR=$BASEDIR/Linux -DCMAKE_Fortran_COMPILER=ifort -DCMAKE_INSTALL_PREFIX=../install

This will install to a directory parallel to your build directory. If you prefer to install elsewhere change the path in:

-DCMAKE_INSTALL_PREFIX=<path>

and CMake will install there.

Create and install source tarfile

Note that running with parallel_build.csh will create and install a tarfile of the source code at build time. But if CMake is run by hand, this is not the default action (as many who build with CMake by hand are developers and not often running experiments). In order to enable this at install time, add:

-DINSTALL_SOURCE_TARFILE=ON

to your CMake command.

Build and Install with Make
make -jN install

where N is the number of parallel processes. On discover head nodes, this should only be as high as 2 due to limits on the head nodes. On a compute node, you can set N has high as you like, though 8-12 is about the limit of parallelism in our model's make system.

Run the GCM

Once the model has built successfully, you will have an install/ directory in your checkout. To run gcm_setup go to the install/bin/ directory and run it there:

cd install/bin
./gcm_setup

Contributing

Please check out our contributing guidelines.

License

All files are currently licensed under the Apache-2.0 license, see LICENSE.

Previously, the code was licensed under the NASA Open Source Agreement, Version 1.3.

About

GEOS Earth System Model GEOSgcm Fixture

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • CMake 67.7%
  • Shell 23.1%
  • Dockerfile 9.2%