Downloading CESM2

Downloading the code and scripts

Starting with CESM2, releases are available through a public GitHub repository, http://github.com/ESCOMP/cesm.

Access to the code requires both git and Subversion client software in place that is compatible with GitHub and our Subversion server software. You will need access to the command line clients, git (v1.8 or greater) and svn (v1.8 or greater but less than v1.11). Currently, our Subversion server software is at version 1.8.17. For more information or to download open source tools, visit Subversion and git downloads.

With valid git and svn clients installed on the machine where CESM will be built and run, the user may download the latest version of the release code:

git clone -b release-cesm2.1.0 https://github.com/ESCOMP/cesm.git my_cesm_sandbox
cd my_cesm_sandbox

To checkout a previous version of CESM, first view the available versions:

git tag --list 'release-cesm2*'

To checkout a specific CESM release tag type, for example CESM2.0.1:

git checkout release-cesm2.0.1

Finally, to checkout all the individual model components, run the checkout_externals script from /path/to/my_cesm_sandbox.

./manage_externals/checkout_externals

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/my_cesm_sandbox.

Details regarding the CESM checkout process are available in the CESM GitHub repo README To see more details regarding the checkout_externals script from the command line, type:

./manage_externals/checkout_externals --help

Warning

When contacting the Subversion server for the first time, you may need to accept an authentication certification. If you experience problems such as checkout_externals hanging: Run svn ls https://svn-ccsm-models.cgd.ucar.edu/ww3/release_tags, permanently accepting the certificate when prompted, then retry the CESM download (starting over at the top of these instructions).

Warning

If a problem was encountered during checkout_externals, which may happen with an older version of the svn client software, it may appear to have downloaded successfully, but in fact only a partial checkout has occurred.

To confirm a successful download of all components, you can run checkout_externals with the status flag to show the status of the externals:

./manage_externals/checkout_externals -S

This should show a clean status for all externals, with no characters in the first two columns of output, as in this example:

Processing externals description file : Externals.cfg
Processing externals description file : Externals_CLM.cfg
Processing externals description file : Externals_POP.cfg
Processing externals description file : Externals_CISM.cfg
Checking status of externals: clm, fates, ptclm, mosart, ww3, cime, cice, pop, cvmix, marbl, cism, source_cism, rtm, cam,
    ./cime
    ./components/cam
    ./components/cice
    ./components/cism
    ./components/cism/source_cism
    ./components/clm
    ./components/clm/src/fates
    ./components/clm/tools/PTCLM
    ./components/mosart
    ./components/pop
    ./components/pop/externals/CVMix
    ./components/pop/externals/MARBL
    ./components/rtm
    ./components/ww3

You should now have a complete copy of the CESM2 source code in your /path/to/my_cesm_sandbox.

If there were problems obtaining an external, you might instead see something like:

e-  ./components/cam

This might happen if there was an unexpected interruption while downloading. First try rerunning ./manage_externals/checkout_externals. If there is still a problem, try running with logging turned on using:

./manage_externals/checkout_externals --logging

Check the manage_externals.log file to see what errors are reported.

Downloading input data

Input datasets are needed to run the model. CESM input data are available through a separate Subversion input data repository.

Warning

The input data repository contains datasets for many configurations and resolutions and is well over 10 TByte in total size. DO NOT try to download the entire dataset.

Datasets can be downloaded on a case by case basis as needed and CESM provides tools to check and download input data automatically.

A local input data directory should exist on the local disk, and it also needs to be set in the CESM scripts via the variable $DIN_LOC_ROOT. For supported machines, this variable is preset. For generic machines, this variable is set via the --input-dir argument to create_newcase. It is recommended that all users of a given filesystem share the same $DIN_LOC_ROOT directory.

The files in the subdirectories of $DIN_LOC_ROOT should be write-protected. This prevents these files from being accidentally modified or deleted. The directories in $DIN_LOC_ROOT should generally be group writable, so the directory can be shared among multiple users.

As part of the process of generating the CESM executable, the utility, check_input_data located in each case directory is called, and it attempts to locate all required input data for the case based upon file lists generated by components. If the required data is not found on local disk in $DIN_LOC_ROOT, then the data will be downloaded automatically by the scripts or it can be downloaded by the user by invoking check_input_data with the --download command argument. If you want to download the input data manually you should do it before you build CESM.

It is possible for users to download the data using svn subcommands directly, but use of the check_input_data script is highly recommended to ensure that only the required datasets are downloaded.

Warning

Again, users are STRONGLY DISCOURAGED from downloading the entire input dataset from the repository.