Creating, documenting and running new configurations

Creating, documenting and running new configurations#

This section is intended to document the process of creating new configurations for ACCESS-AM3 in the context of the 21st Century Weather Centre. It’s not intended to replace the ACCESS-NRI documentation, if you are interested in learning how to run ACCESS-AM3, please refer to the ACCESS-NRI documentation.

The section assumes you are using cylc8, if not, it’s a good moment to do the switch.

New configurations?#

If you are planning to run ACCESS-AM3 with a different set of ancillaries, or different initial conditions, or you are changing anything in the suite, that is a new configuration.

When you run the model with a specific configuration, you get an experiment.

As an example for this tutorial, lest say we want to run ACCESS-AM3 with a new initial condition, based on the current release-n512e-aeroclim configuration. We’ll call it n512e-1983.

Workflow#

1. Clone the repository#

The 21st Century Weather configurations are store in a private repository (a fork of the ACCESS-NRI repository) at https://github.com/21centuryweather/access-am3-configs. You need to be a member of the organisation to have access to the repository. If you don’t have access, you can request it on Cumulus.

To clone the specific configuration:

git -C ~/roses clone git@github.com:21centuryweather/access-am3-configs.git -b release-n512e-aeroclim

Note

If you plan to use more than one configuration or want to explore them, you can clone the entire repository and switch between branches.

git -C ~/roses clone git@github.com:21centuryweather/access-am3-configs.git

If you already have the repository cloned, you can update any branch (bring any changes from the remote repository) with git pull or fetch a new branch from the remote repository with git fetch origin <branch-name>.

2. Create and switch to a new branch#

We recommend to create a new branch for each new configuration, this will make it easier to track changes, share the configuration and reproduce experiments.

To create a new branch, navigate to the folder ~/roses/access-am3-configs` use the following commands:

git checkout release-n512e-aeroclim # to switch from main to the n512e beta relase configuration
git checkout -b n512e-1983

This will switch the repository to the release-n512e-aeroclim branch and create a new branch called n512e-1983. At this point both branches are identical.

Note

Check the current branch you are using and any new changes with git status.

Now you can make any changes to the configuration, for example, changing the initial conditions to use a restart from 1983.

3. Tracking changes#

It’s very important to track any changes you make to the configuration. This will help you to reproduce experiments and share your configuration with others. We’ll track changes by doing commits to the configuration branch and pushing them to the remote repository on GitHub.

Let’s change the initial conditions to use a restart from 1983. Edit the file site/nci_gadi.rc and change the line:

{% set AINITIAL = '/g/data/gb02/public/AM3/restartdumps/n96e/deva.da19830101_00' %}

And these 2 lines to run the experiment from January 1, 1983 for 12 months in rose-suite.conf_nci_gadi:

EXPT_BASIS='19830101T0000Z'
EXPT_RUNLEN='P12M'

When running git status you will see that the files site/nci_gadi.rc and rose-suite.conf_nci_gadi have been modified:

$ git status
On branch n512e-1983
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   rose-suite.conf_nci_gadi
	modified:   site/nci_gadi.rc

no changes added to commit (use "git add" and/or "git commit -a")

As git mention, we need to add the files to the staging are and commit them:

git add rose-suite.conf_nci_gadi site/nci_gadi.rc
git commit -m "Changed initial conditions to use restart from 1983 and run for 12 months"

The changes, now are being tracked by git in your local repository. You can test the configuration and run experiments. If you need to do further changes, maybe something went wrong, it’s crucial to repeat the steps to track all the changes in the configuration.

Note

If you want to see the changes you have made to a file, you can use git diff <file>. This will show you the differences between the current version of the file and the last committed version. It is a good practice to do this before committing the changes, to make sure you are not committing any unwanted changes.

4. Push changes to GitHub#

When you are ready, you will need to push the configuration (the new branch) to the remote repository on GitHub:

git push --set-upstream origin n512e-1983

Because n512e-1983 is a new branch that only exists on your local repo, you need to set up the same in the remote repository “origin” the first time you push to Github. So, --set-upstream will create the branch in the remote repository. After that, for following updates, you can use git push and it will work the same.

Now you can check your configuration on GitHub and share it with others.

Note

You can do as many commits and update (push) the branch to the remote repository as many times as you need until the configuration is ready to go. Always be sure to:

  • Track all the changes you make to the configuration.

  • Create a new branch for each new configuration.