1. Downloading the model code

The NorESM2 model code is available through a public GitHub repository: https://github.com/NorESMhub/NorESM

  • Most users will probably want to clone the NorESM repository to a local machine using a git command-line client (see below). This gives easy access to both stable releases and development branches of NorESM.

  • Users who do not wish to a git command-line client can download archive files (zip or tar.gz) of stable releases from https://github.com/NorESMhub/NorESM/tags

1.1. Make a clone of the NorESM repository

You can obtain the code using the command-line git client on the appropriate machine as follows:

git clone https://github.com/NorESMhub/NorESM.git <noresm-base>

where <noresm-base> is the name of the directory where the latest version of the released code will be stored. You can replace <noresm-base> with the directory name you like.

Enter the <noresm-base> folder

cd <noresm-base>

Now you can check which remote servers you have configured:

> git remote -v
origin        https://github.com/NorESMhub/NorESM.git (fetch)
origin        https://github.com/NorESMhub/NorESM.git (push)

And check which branch you are using

> git branch

To use another version of the code, you can check out a specific tag or a branch.

1.2. Check out a specific NorESM branch, e.g. NorESM2.0.1

List all available tags

> git tag --list

To check out a specific tag, use git checkout <tag-name> where <tag-name> is a tag for the list, for instance release-noresm2.0.1

> git checkout release-noresm2.0.1

List all available branches

> git branch --all

To check out a specific branch, for instance noresm2

> git checkout -b noresm2 origin/noresm2

You can now inspect which tag or branch you are using by invoking the git branch command again. You can also inspect the commits log by invoking the git log command (to for instance only see the 3 commits, apply the -n 3 option).

1.2.1. NorESM releases configured for specific HPC platforms

Machine configurations for specific HPC platforms have been integrated in different releases of NorESM, depending on when the HPC platforms became available. The following table shows which release introduced support for a specific platform. Please see Running on different platforms for more details.

HPC platform

NorESM release

Fram

release-noresm2.0.0

Betzy

release-noresm2.0.3

1.3. Manage externals

Then you need to launch the download:

./manage_externals/checkout_externals  [this will take one to a few minutes ...]

this will use the repositories, tags, branches as specified in Externals.cfg (see Configure Externals.cfg for its manipulation)

The checkout_externals script will read the configuration file called Externals.cfg and will download all the external component models and CIME into /path/to/<noresm-base>.

Now you have a complete copy of the NorESM code in the directory <noresm-base>. At this point you can enter the subdirectory <noresm-base>/cime/scripts/ and start creating a case! (see Experiments)

Please note that if you checkout a new branch or tag, you will need to rerun checkout_externals in order to download the correct version of the model code

1.3.1. Confirm successful download of all components

To confirm a successful download of all components, you can run checkout_externals with the status flag -S to show the status of the externals or --logging to get a log of reported errors (if any):

./manage_externals/checkout_externals -S             [-S shows status of externals]
./manage_externals/checkout_externals --logging      [write log of errors in manage_externals.log]

1.4. Configure Externals.cfg

The Externals.cfg file contains code blocks that specify what model components to include in the NorESM build, where the source code for each component is located, and what verision of the model component to use. The file can be modified to use another repository, fork, branch or tag or release for any of the model components. The following example is for the land component, which in this case points to a version of the Community Terrestrial Systems Model (CTSM), which includes the Community Land Model (CLM)

[clm]
tag = release-clm5.0.14-Nor_v1.0.1
protocol = git
repo_url = https://github.com/NorESMhub/ctsm
local_path = components/clm
externals = Externals_CLM.cfg
required = True

The file takes the following keywords .. glossary:

[component name]
  Component to be configured. See existing Externals.cfg file for valid options.

required
  Wheter to include the component in the model build ('True' or 'False').

local_path
  Where to download the source code to, relative to where the checkout script is called from.

protocol
  Version control protocol used to manage the component ('git', 'svn', 'externals_only').

repo_url
  URL for the repository location. This keyword accepts either a path to a remote repository or a local clone. For local clones, user expansions (e.g. ~/) and environment variable expansions (e.g. $HOME), will be performed.

externals
  used to make *manage_externals* aware of sub-externals required by an external component.

tag
  tag name to checkout from the repository.

branch
  branch name to checkout from the repository.

hash
  the git hash to checkout from the repository.

NOTE: one and only one of tag, branch or hash must be supplied. The supplied string will be parsed to a git checkout command, but the the keyword determines what checks will be applied to the supplied string before parsing.

See more info here: https://github.com/ESCOMP/CESM/blob/master/README.rst