Create your own repository of experiments

In other documentation we describe how to clone the MOM6-examples repository of experiment configurations. Here we describe how to construct your own independent experiment repository in which you can keep your own configurations.

Minimum setup for ocean-only experiments

These steps will create a repository with a structure as follows:

$ tree -L 2 My_experiments
My_experiments
├── expt1
│   ├── diag_table
│   ├── input.nml
│   └── MOM_input
└── src
    ├── FMS
    ├── mkmf
    └── MOM6

You can choose to put expt1 under "ocean_only" if you want to mimic the structure in MOM6-examples and maintain different classes of experiments, such as "ocean_only" or "coupled".

First create a new folder and initialize git. This folder will be what you get after a git clone and has the equivalent role that MOM6-examples has for GFDL experiments. We recommend naming the folder with the name of the repository you intend to use:

mkdir My_experiments
cd My_experiments
git init

By default git will use branch "master". If you want to develop on a different branch then you can change the branch now:

git checkout -b my_dev_branch

Now add the software and source code needed to build an ocean-only model:

git submodule init
git submodule add https://github.com/mom-ocean/mkmf.git src/mkmf
git submodule add https://github.com/NOAA-GFDL/FMS.git src/FMS
git submodule add [email protected]:my_github_account_name/MOM6.git src/MOM6
git submodule update --init --recursive

Note that we used the "https" transfer protocol for repositories which we never expect to need to fork and push to (i.e. read-only). For the MOM6 repository we used the git transfer protocol and pointed to your fork (replace "my_github_account_name" with your GitHub account name). If you don't have or want your own fork of MOM6, then replace the url with "https://github.com/NOAA-GFDL/MOM6.git".

This is what your directory will look like

% tree -L 2 .
.
`-- src
    |-- FMS
    |-- mkmf
    `-- MOM6

3 directories, 0 files

and git status reports:

% git status
On branch dev/master

Initial commit

Changes to be committed: (use "git rm --cached ..." to unstage)

    new file:   .gitmodules
    new file:   src/FMS
    new file:   src/MOM6
    new file:   src/mkmf

Let's commit this before adding an experiment:

git commit -m "Added source needed for ocean-only experiments"

Other source for ice-ocean experiments

If you plan to use the sea-ice model with your ocean then we need some other components:

git submodule add https://github.com/NOAA-GFDL/SIS2.git src/SIS2
git submodule add https://github.com/NOAA-GFDL/atmos_null.git src/atmos_null
git submodule add https://github.com/NOAA-GFDL/coupler.git src/coupler
git submodule add https://github.com/NOAA-GFDL/land_null.git src/land_null
git submodule add https://github.com/NOAA-GFDL/icebergs.git src/icebergs
git submodule add https://github.com/NOAA-GFDL/ice_param.git src/ice_param

Let's commit these additions:

git add .
git commit -m "Added components needed for ice-ocean experiments"

Create your own ocean-only experiment

From the "My_experiments" directory, first name your experiment and create a directory (here we use "expt1"):

mkdir expt1
cd expt1

The bare minimum of input files you need are input.nml, MOM_input, diag_table. Create input.nml with

cat << EOFA > input.nml
 &MOM_input_nml
         output_directory = './',
         input_filename = 'n'
         restart_input_dir = 'INPUT/',
         restart_output_dir = 'RESTART/',
         parameter_filename = 'MOM_input' /

 &diag_manager_nml
 /

 &fms_nml
        domains_stack_size = 955296
        stack_size =0 /
EOFA

Note that if you like to use the MOM_override model of perturbation parameters change parameter_filename = 'MOM_input','MOM_override'.

Grab a working MOM_input

wget -o/dev/null -O- https://github.com/NOAA-GFDL/MOM6-examples/archive/dev/master.tar.gz | tar -zxv --strip-components=3 -f - MOM6-examples-dev-master/ocean_only/benchmark/MOM_input

Create a simple diag_table with:

cat << EOFA > diag_table
"Experiment expt1"                             
1 1 1 0 0 0                                            
"output",      1,"days",1,"days","time",                 

#This is the field section of the diag_table.

# Prognostic Ocean fields:
#=========================

"ocean_model","u","u","output","all",.false.,"none",2
"ocean_model","v","v","output","all",.false.,"none",2
"ocean_model","h","h","output","all",.false.,"none",1
"ocean_model","e","e","output","all",.false.,"none",2
"ocean_model","temp","temp","output","all",.false.,"none",2
EOFA

Add the experiment to your repository

cd ../ # Back to top level
git add expt1
git commit -m "Added ocean-only experiment expt1 (based on benchmark from MOM6-examples)"

Push your repository to GitHub

Having followed the above steps you now have a working directory under version control with git. To collaborate, or even just backup your work, you can push it up to GitHub:

1. Create a new repository on GitHub by going to your account and clicking on the "+" icon "Create new..." (top-right of GitHub page once you are logged in).
2. Enter a name for the repository (we recommend using the same name for the folder you created and the repository but it is not mandatory)
3. Do not check "Initialize this repository with a README" nor add license or README files. You want a blank repository to push to since you already created a history in the steps above.
4. Create the blank respository by clicking "Create repository"
5. On the next page you will be given instructions for pushing, under the title "…or push an existing repository from the command line", which will be something like:

git remote add origin https://github.com/<my_github_account>/My_experiments
git push -u origin my_dev_branch

where the "my_dev_branch" is whatever you decided to use as the first branch (e.g. "master" by default).