Installing and Running OpenGGCM

Installing and Running OpenGGCM#

System Requirements#

OpenGGCM has fairly minimal dependencies:

Required dependencies:

  • Fortran90 compiler (recommended: gfortran)

  • MPI

  • perl

  • autotools

Optional dependencies:

  • HDF5 (if using XDMF/HDF5 output)

  • ADIOS2 (for code coupling)

  • cmake

Todo

A devcontainer can be a convenient way of getting everything in place to build / run / develop OpenGGCM, but needs documentation and unfortunately is not usually a feasible way of running production.

Marvin#

On UNH’s Cray “Marvin”, I set up the environment for OpenGGCM using conda. (This should work on other machines, too, if one opts to use conda. Most machines are going to have a way to set up environments, it’s generally probably best to stick with that.)

Todo

Add how to installing (mini-)conda.

Create a .condarc in your home directory with the following content:

channels:
 - conda-forge
 - defaults
channel_priority: strict

Create an environment for OpenGGCM:

conda create -n ggcm
conda activate ggcm

conda install openmpi-mpifort
conda install "adios2=*=mpi_openmpi_*"
conda install cmake
conda install hdf5
conda install jupyter
conda install xarray
conda install dask
conda install matplotlib
pip install ggcmpy

You also want to set the environment variable OPENGGCMDIR to the location of the OpenGGCM source you cloned from github above, e.g. by adding the following to your .bashrc or .zshrc.

export OPENGGCMDIR=$HOME/src/openggcm # adjust for your OpenGGCM source location

Activate your environment.

[kaig@ln-0001 openggcm]$ conda activate ggcm
(ggcm) [kaig@ln-0001 openggcm]$

Obtaining OpenGGCM#

Repository Access#

OpenGGCM is maintained in a private github repository. Please contact Kai kai.germaschewski@unh.edu or Doug william.cramer@unh.edu to be given access.

Cloning the repository#

Todo

  • Setting up ssh or alternative github authentication

  • forking the repo if planning to do development

(ggcm) [kaig@ln-0001 ~]$ mkdir src
(ggcm) [kaig@ln-0001 ~]$ cd src
(ggcm) [kaig@ln-0001 src]$ git clone git@github.com:unh-hpc/openggcm.git
Cloning into 'openggcm'...
remote: Enumerating objects: 70227, done.
remote: Counting objects: 100% (940/940), done.
remote: Compressing objects: 100% (316/316), done.
remote: Total 70227 (delta 682), reused 756 (delta 621), pack-reused 69287 (from 2)
Receiving objects: 100% (70227/70227), 86.08 MiB | 42.67 MiB/s, done.
Resolving deltas: 100% (54561/54561), done.
Updating files: 100% (1615/1615), done.

This should get you a copy of the OpenGGCM source in src/openggcm.

Have the autotools prepare the code for building:

(ggcm) [kaig@ln-0001 src]$ cd openggcm
(ggcm) [kaig@ln-0001 openggcm]$ ./autogen.sh

Building and Installing OpenGGCM Utilities#

Compile the utilities:

(ggcm) [kaig@ln-0001 openggcm]$ cd util
(ggcm) [kaig@ln-0001 util]$ ./configure --prefix=$HOME
[...]
(ggcm) [kaig@ln-0001 util]$ make
[...]
(ggcm) [kaig@ln-0001 util]$ make install
[...]

This compiles and install the utilities into $PREFIX/bin, so with the prefix set to $HOME into the bin/ folder in your home directory. Add that folder to your path (again, something you may want to do in .bashrc or similar to persist it).

(ggcm) [kaig@ln-0001 util]$ export PATH=$HOME/bin:$PATH
(ggcm) [kaig@ln-0001 util]$ fppn # make sure the fppn tool is now available
usage: fppn [-q] [-c] [-v1] [-v2] [-v3] [-v4] [-longout] [-fold] file

Setting up a run#

Let’s set up a sample run, and run it.

(ggcm) [kaig@ln-0001 work]$ mkdir test0003
(ggcm) [kaig@ln-0001 work]$ cp -a $OPENGGCMDIR/run-template/test0003/{runme,swdata} test0003/
(ggcm) [kaig@ln-0001 work]$ cd test0003
(ggcm) [kaig@ln-0001 test0003]$ ./runme
[...]

Get a coffee and cross your fingers…

Once the build successfully finishes, one should make a batch script and submit a job.

Todo

Really, the runme should be adapted to make a batch script for Marvin here.

But for now, we’ll just run the code by hand.

(ggcm) [kaig@ln-0001 test0003]$ cd target
(ggcm) [kaig@ln-0001 target]$ srun -n 6 ./openggcm
srun: job 27370 queued and waiting for resources

Well, since the queue is full, I just ran on the head node:

(ggcm) [kaig@ln-0001 target]$ mpirun -n 6 ./openggcm
[...]

This run is set up to be a tiny test case, so it only runs for a minute or so. But it should produce some MHD and ionosphere output files that can be plotted using ggcmpy as shown in the sample notebook.

Contents