Downloading CESM1.1

Downloading the code and scripts

CESM release code will be made available through a Subversion repository. Access to the code will require Subversion client software in place that is compatible with our Subversion server software, such as a recent version of the command line client, svn. Currently, our server software is at version 1.4.2. We recommend using a client at version 1.5 or later, though older versions may suffice. We cannot guarantee a client older than 1.4.2. For more information or to download open source tools, visit:


http://subversion.tigris.org/

With a valid svn client installed on the machine where CESM1 will be built and run, the user may download the latest version of the release code. First view the available release versions with the following command:


> svn list https://svn-ccsm-release.cgd.ucar.edu/model_versions

When contacting the Subversion server for the first time, the following certificate message will likely be generated:


Error validating server certificate for 'https://svn-ccsm-release.cgd.ucar.edu:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
 - The certificate hostname does not match.
 - The certificate has expired.
Certificate information:
 - Hostname: localhost.localdomain
 - Valid: from Feb 20 23:32:25 2008 GMT until Feb 19 23:32:25 2009 GMT
 - Issuer: SomeOrganizationalUnit, SomeOrganization, SomeCity, SomeState, --
 - Fingerprint: 86:01:bb:a4:4a:e8:4d:8b:e1:f1:01:dc:60:b9:96:22:67:a4:49:ff
(R)eject, accept (t)emporarily or accept (p)ermanently? 

After accepting the certificate, the repository will request a username and password. Be aware that the request may set current machine login id as the default username. Once correctly entered, the username and password will be cached in a protected subdirectory of the user's home directory so that repeated entry of this information will not required for a given machine.

The release tags should follow a recognizable naming pattern, and they can be checked out from the central source repository into a local sandbox directory. The following example shows how to checkout model version CESM1.1:


> svn co https://svn-ccsm-release.cgd.ucar.edu/model_versions/cesm1_1 cesm1_1

Caution

If a problem was encountered during checkout, which may happen with an older version of the client software, it may appear to have downloaded successfully, but in fact only a partial checkout has occurred. To ensure a successful download, make sure the last line of svn output has the following statement:


Checked out revision XXXXX.

Or, in the case of an 'svn update' or 'svn switch':


Updated to revision XXXXX.

This will create a directory called cesm1_1 that can be used to modify, build, and run the model. The following Subversion subcommands can be executed in the working sandbox directory.

For various information regarding the release version checked out...


> svn info       

For a listing of files that have changed since checkout...


> svn status 

For a description of the changes made to the working copy...


> svn diff 

Obtaining new release versions of CESM

To update to a newer version of the release code you can download a new version of CESM1.1 from the svn central source repository in the following way:

Suppose for example that a new version of CESM1.1 is available at https://svn-ccsm-release.cgd.ucar.edu/model_versions/cesm1_1_<newversion>. This version can be checked out directly using the same standard CESM download method.

As an alternative, some users may find the svn switch operation useful. In particular, if you've used svn to check out the previous release, cesm1_1_<previousversion>, and if you've made modifications to that code, you should consider using the svn switch operation. This operation will not only upgrade your code to the version cesm1_1_<newversion>, but will also attempt to reapply your modifications to the newer version.

How to use the svn switch operation:

Suppose you've used svn to check out cesm1_1_<previousversion> into the directory called /home/user/cesm1_1

  1. Make a backup copy of /home/user/cesm1_1 -- this is important in case you encounter any problems with the update

  2. cd to the top level of your cesm1_1 code tree...

    
   > cd /home/user/cesm1_1
    
  3. Issue the following svn command...

    
   > svn switch https://svn-ccsm-release.cgd.ucar.edu/model_versions/cesm1_1_<newversion>  
    

The svn switch operation will upgrade all the code to the new cesm1_1_<newversion> version, and for any files that have been modified, will attempt to reapply those modifications to the newer code.

Note that an update to a newer version of the release code may result in conflicts with modified files in the local working copy. These conflicts will likely require that differences be resolved manually before use of the working copy may continue. For help in resolving svn conflicts, please visit the subversion website,

http://svnbook.red-bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve

A read-only option is available for users to view via a web browser at

https://svn-ccsm-release.cgd.ucar.edu

where the entire CESM1 release directory tree can be navigated.

The following examples show common problems and their solutions.

Problem 1: If the hostname is typed incorrectly:


> svn list https://svn-ccsm-release.cgd.ucar.edu/model_versions/cesm1_1_<version> 
svn: PROPFIND request failed on '/model_versions/cesm1_1_<version>'
svn: PROPFIND of '/model_versions/cesm1_1_<version>': Could not resolve hostname `svn-ccsm-releese': Host not found (https://svn-ccsm-releese)

Problem 2: If http is typed instead of https:


> svn list http://svn-ccsm-release.cgd.ucar.edu/model_versions/cesm1_1_<version>   
svn: PROPFIND request failed on '/model_versions/cesm1_1_<version>'
svn: PROPFIND of '/model_versions/cesm1_1_<version>': could not connect to server (http://svn-ccsm-release.cgd.ucar.edu)

Downloading input data

Input datasets are needed to run the model. CESM input data will be made available through a separate Subversion input data repository. The username and password for the input data repository will be the same as for the code repository.

Note: The input data repository contains datasets for many configurations and resolutions and is well over 1 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 now 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 as an argument to create_newcase. Multiple users can 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 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 -export 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. Again, users are STRONGLY DISCOURAGED from downloading the entire input dataset from the repository due to the size.