| CI Provider | Status |
|---|---|
| CircleCI |  |
| GitHub |  |
In your .bashrc or .tcshrc or other rc file add a line:
module use -a /discover/swdev/gmao_SIteam/modulefiles-SLES15
module use -a /nobackup/gmao_SIteam/modulefiles
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.
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.
To clone the GEOSgcm using the SSH url (starts with git@github.com), you run:
git clone -b vX.Y.Z git@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.
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.
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.
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.
The GEOS GCM uses a Python utility called mepo to manage multiple git repositories instead of using other technologies like Git
submodules. mepo uses a YAML file that provides a list of components (and their versions) that are required for a particular configuration of GEOS GCM.
We highly recommend setting up mepo to use blobless clones to speed
up cloning of the sub-repositories, especially on discover. To do this, there is a one-time command to run:
mepo config set clone.partial blobless
This will set up mepo to use blobless clones for all future clones by adding an entry to ~/.mepoconfig.
If all you wish is to build the model, you can run:
./parallel_build.csh
from a login 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.
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
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/.
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.
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.
The steps detailed below are essentially those that parallel_build.csh performs for you. Either method should yield identical builds.
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
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.
On tcsh:
source @env/g5_modules
or on bash:
source @env/g5_modules.sh
CMake generates the Makefiles needed to build the model. This command:
cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install
As is, this command assumes you are in the root of the GEOSgcm checkout and will create a build/ directory in the root of the checkout and install into install/ parallel to the build/` directory.
This command has three options:
-Bspecifies the build directory.-Sspecifies the source directory (root of the checkout).-DCMAKE_INSTALL_PREFIXspecifies the installation directory.
If you prefer to install elsewhere change the path in:
-DCMAKE_INSTALL_PREFIX=/path/to/install
and CMake will install there.
If you prefer your build somewhere else, you can specify that with:
-B /path/to/build
Finally, if your source is in a different directory than the current one, you can specify that with:
-S /path/to/source
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.
cmake --build build -j N
cmake --install build
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.
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 /path/to/install/bin
./gcm_setup
Please check out our contributing guidelines.
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.