GEOSgcm

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 50 Open GitHub ↗

GEOS Earth System Model GEOSgcm Fixture

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GEOS GCM Fixture

## CI Status

| CI Provider | Status                                                                                                          |
| ----------- | ------                                                                                                          |
| CircleCI    | [![CircleCI](https://circleci.com/gh/GEOS-ESM/GEOSgcm.svg?style=svg)](https://circleci.com/gh/GEOS-ESM/GEOSgcm) |
| GitHub      | ![GitHub](https://github.com/GEOS-ESM/GEOSgcm/workflows/Build%20Tests/badge.svg)                                |

## Current State of GEOSgcm Subrepos

| Repository                                                                     | Version                                                                                               |
| ----------                                                                     | -------                                                                                               |
| [ACHEM](https://github.com/GEOS-ESM/ACHEM)                                     | [v1.1.0](https://github.com/GEOS-ESM/ACHEM/releases/tag/v1.1.0)                                       |
| [CARMA](https://github.com/GEOS-ESM/CARMA)                                     | [v1.1.0](https://github.com/GEOS-ESM/CARMA/releases/tag/v1.1.0)                                       |
| [CICE](https://github.com/GEOS-ESM/CICE)                                       | [geos/v0.2.0](https://github.com/GEOS-ESM/CICE/releases/tag/geos%2Fv0.2.0)                            |
| [CPLFCST_Etc](https://github.com/GEOS-ESM/CPLFCST_Etc)                         | [v1.0.1](https://github.com/GEOS-ESM/CPLFCST_Etc/releases/tag/v1.0.1)                                 |
| [ecbuild](https://github.com/GEOS-ESM/ecbuild)                                 | [geos/v3.13.1](https://github.com/GEOS-ESM/ecbuild/releases/tag/geos%2Fv3.13.1)                       |
| [ESMA_cmake](https://github.com/GEOS-ESM/ESMA_cmake)                           | [v4.41.0](https://github.com/GEOS-ESM/ESMA_cmake/releases/tag/v4.41.0)                                |
| [ESMA_env](https://github.com/GEOS-ESM/ESMA_env)                               | [v5.25.0](https://github.com/GEOS-ESM/ESMA_env/releases/tag/v5.25.0)                                  |
| [FVdycoreCubed_GridComp](https://github.com/GEOS-ESM/FVdycoreCubed_GridComp)   | [v3.0.1](https://github.com/GEOS-ESM/FVdycoreCubed_GridComp/releases/tag/v3.0.1)                      |
| [GAAS](https://github.com/GEOS-ESM/GAAS)                                       | [v1.1.0](https://github.com/GEOS-ESM/GAAS/releases/tag/v1.1.0)                                        |
| [geos-chem](https://github.com/GEOS-ESM/geos-chem)                             | [geos/v13.0.0-rc1](https://github.com/GEOS-ESM/geos-chem/releases/tag/geos%2Fv13.0.0-rc1)             |
| [GenCast-GEOS_FP](https://github.com/GEOS-ESM/GenCast_GEOS-FP)                 | [geos/v0.3.1](https://github.com/GEOS-ESM/GenCast_GEOS-FP/releases/tag/geos%2Fv0.3.1)                 |
| [GEOS_OceanGridComp](https://github.com/GEOS-ESM/GEOS_OceanGridComp)           | [v3.10.0](https://github.com/GEOS-ESM/GEOS_OceanGridComp/releases/tag/v3.10.0)                        |
| [GEOS_Util](https://github.com/GEOS-ESM/GEOS_Util)                             | [v3.0.1](https://github.com/GEOS-ESM/GEOS_Util/releases/tag/v3.0.1)                                   |
| [geos_state_bias](https://github.com/GEOS-ESM/geos_state_bias)                 | [geos/v1.0.0](https://github.com/GEOS-ESM/geos_state_bias/releases/tag/geos/v1.0.0)                   |
| [GEOSchem_GridComp](https://github.com/GEOS-ESM/GEOSchem_GridComp)             | [v2.0.0](https://github.com/GEOS-ESM/GEOSchem_GridComp/releases/tag/v2.0.0)                           |
| [GEOSgcm_App](https://github.com/GEOS-ESM/GEOSgcm_App)                         | [v3.0.1](https://github.com/GEOS-ESM/GEOSgcm_App/releases/tag/v3.0.1)                                 |
| [GEOSgcm_GridComp](https://github.com/GEOS-ESM/GEOSgcm_GridComp)               | [v3.0.1](https://github.com/GEOS-ESM/GEOSgcm_GridComp/releases/tag/v3.0.1)                            |
| [GEOSradiation_GridComp](https://github.com/GEOS-ESM/GEOSradiation_GridComp)   | [v2.0.0](https://github.com/GEOS-ESM/GEOSradiation_GridComp/releases/tag/v2.0.0)                      |
| [GFDL_atmos_cubed_sphere](https://github.com/GEOS-ESM/GFDL_atmos_cubed_sphere) | [geos/v3.0.0](https://github.com/GEOS-ESM/GFDL_atmos_cubed_sphere/releases/tag/geos%2Fv3.0.0)         |
| [gigatraj](https://github.com/GEOS-ESM/gigatraj)                               | [geos/v1.0.0](https://github.com/GEOS-ESM/gigatraj/releases/tag/geos%2Fv1.0.0)                        |
| [GMI](https://github.com/GEOS-ESM/GMI)                                         | [v1.6.0](https://github.com/GEOS-ESM/GMI/releases/tag/v1.6.0)                                         |
| [GMAO_perllib](https://github.com/GEOS-ESM/GMAO_perllib)                       | [v1.1.0](https://github.com/GEOS-ESM/GMAO_perllib/releases/tag/v1.1.0)                                |
| [GMAO_Shared](https://github.com/GEOS-ESM/GMAO_Shared)                         | [v3.0.1](https://github.com/GEOS-ESM/GMAO_Shared/releases/tag/v3.0.1)                                 |
| [GOCART](https://github.com/GEOS-ESM/GOCART)                                   | [v2.6.5](https://github.com/GEOS-ESM/GOCART/releases/tag/v2.6.5)                                      |
| [HEMCO](https://github.com/GEOS-ESM/HEMCO)                                     | [geos/v2.3.0](https://github.com/GEOS-ESM/HEMCO/releases/tag/geos%2Fv2.3.0)                           |
| [Icepack](https://github.com/GEOS-ESM/Icepack)                                 | [geos/v0.3.0](https://github.com/GEOS-ESM/Icepack/releases/tag/geos%2Fv0.3.0)                         |
| [MAM](https://github.com/GEOS-ESM/MAM)                                         | [v1.1.0](https://github.com/GEOS-ESM/MAM/releases/tag/v1.1.0)                                         |
| [MAPL](https://github.com/GEOS-ESM/MAPL)                                       | [v2.70.0](https://github.com/GEOS-ESM/MAPL/releases/tag/v2.70.0)                                      |
| [MATRIX](https://github.com/GEOS-ESM/MATRIX)                                   | [v1.0.0](https://github.com/GEOS-ESM/MATRIX/releases/tag/v1.0.0)                                      |
| [MITgcm](https://github.com/GEOS-ESM/MITgcm)                                   | [checkpoint68o](https://github.com/GEOS-ESM/MITgcm/releases/tag/checkpoint68o)                        |
| [MOM5](https://github.com/GEOS-ESM/MOM5)                                       | [geos/5.1.0+1.2.0](https://github.com/GEOS-ESM/MOM5/releases/tag/geos%2F5.1.0%2B1.2.0)                |
| [MOM6](https://github.com/GEOS-ESM/MOM6)                                       | [geos/v3.8](https://github.com/GEOS-ESM/MOM6/tree/geos/v3.8)                                          |
| [NCEP_Shared](https://github.com/GEOS-ESM/NCEP_Shared)                         | [v1.5.0](https://github.com/GEOS-ESM/NCEP_Shared/releases/tag/v1.5.0)                                 |
| [QuickChem](https://github.com/GEOS-ESM/QuickChem)                             | [v1.0.0](https://github.com/GEOS-ESM/QuickChem/releases/tag/v1.0.0)                                   |
| [RRG](https://github.com/GEOS-ESM/RRG)                                         | [v1.1.0](https://github.com/GEOS-ESM/RRG/releases/tag/v1.1.0)                                         |
| [RRTMGP](https://github.com/GEOS-ESM/rte-rrtmgp)                               | [geos/v1.7+1.0.0](https://github.com/GEOS-ESM/rte-rrtmgp/releases/tag/geos%2Fv1.7%2B1.0.0)            |
| [SIS2](https://github.com/GEOS-ESM/SIS2)                                       | [geos/v0.0.1](https://github.com/GEOS-ESM/SIS2/releases/tag/geos%2Fv0.0.1)                            |
| [StratChem](https://github.com/GEOS-ESM/StratChem)                             | [v1.1.0](https://github.com/GEOS-ESM/StratChem/releases/tag/v1.1.0)                                   |
| [Topo](https://github.com/GEOS-ESM/Topo)                                       | [geos/v2.2.1](https://github.com/GEOS-ESM/Topo/releases/tag/geos%2Fv2.2.1)                            |
| [TR](https://github.com/GEOS-ESM/TR)                                           | [v1.2.1](https://github.com/GEOS-ESM/TR/releases/tag/v1.2.1)                                          |
| [UMD_Etc](https://github.com/GEOS-ESM/UMD_Etc)                                 | [v1.5.0](https://github.com/GEOS-ESM/UMD_Etc/releases/tag/v1.5.0)                                     |
| [WW3](https://github.com/GEOS-ESM/WW3)                                         | [v7.14-geos-r1](https://github.com/GEOS-ESM/WW3/releases/tag/v7.14-geos-r1)                           |
| [umwm](https://github.com/GEOS-ESM/umwm)                                       | [v2.0.0-geos-r1](https://github.com/GEOS-ESM/umwm/releases/tag/v2.0.0-geos-r1)                        |

## 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-SLES15
```

##### 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)](https://docs.github.com/en/github/authenticating-to-github/securing-your-account-with-two-factor-authentication-2fa)
is enabled on GitHub.

##### SSH

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](https://github.com/GEOS-ESM/GEOSgcm/releases). 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](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account)
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](https://github.com/GEOS-ESM/GEOSgcm/releases). 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](https://docs.github.com/en/github/authenticating-to-github/accessing-github-using-two-factor-authentication#authenticating-on-the-command-line-using-https)
as a password.

##### GitHub CLI

You can also use the [GitHub CLI](https://cli.github.com/) with:
```
gh repo clone GEOS-ESM/GEOSgcm -- -b vX.Y.Z
```
where `vX.Y.Z` is a tag from a [GEOSgcm release](https://github.com/GEOS-ESM/GEOSgcm/releases). 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.

### Setting up `mepo` to use blobless clones

The GEOS GCM uses a Python utility called [mepo](https://github.com/GEOS-ESM/mepo/) to manage **m**ultiple git r**epo**sitories 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](https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/) 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`.

---

### Single Step Building of the Model

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`.

#### 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](https://github.com/GEOS-ESM/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

##### Run CMake

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:

1. `-B` specifies the build directory.
2. `-S` specifies the source directory (root of the checkout).
3. `-DCMAKE_INSTALL_PREFIX` specifies 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
```

###### 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

```
cmake --build build -j N
cmake --install build
```

where `N` is the number of parallel processes. On discover login nodes, this should only be as high as 2 due to limits on the login 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 /path/to/install/bin
./gcm_setup
```

## Contributing

Please check out our [contributing guidelines](CONTRIBUTING.md).

## License

All files are currently licensed under the Apache-2.0 license, see [`LICENSE`](LICENSE).

Previously, the code was licensed under the [NASA Open Source Agreement, Version 1.3](LICENSE-NOSA).

GEOSgcm

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README