-
Notifications
You must be signed in to change notification settings - Fork 0
CableUserGuide_GettingCable
Users may familiarize themselves with CABLE via the CABLE trac page (https://trac.nci.org.au/trac/cable). This page is publically viewable, however access to many of the features requires logging in. A user login is provided as part of the process of getting CABLE.
Getting CABLE basically involves agreeing to a CABLE license agreement and then downloading it from the CABLE repository at the National Computational Infrastructure (NCI). The process is summarized below:
-
If you do not have a NCI login, apply for a NCI identity using the form available at http://nf.nci.org.au/accounts/forms/user_registration.php Note that after you submit the form here, you will be supplied with a 6-digit reference number. Write down the reference number and click the link near top-right that reads 'connection to existing project form'. There you can put 'CABLE' as the project, put in the 6-digit reference number and your surname before submitting. Later, you will receive your NCI identity in form of XXX### (i.e. 3 characters plus 3 digits) and your password separately. ** Note that this NCI identity does not give you compute resource on any NCI machines; you cannot login unless you have another NCI project that allows you to do so.
-
Register as a CABLE user by completing the registration form, available at http://www.cawcr.gov.au/projects/access/cable/index.php
Send an email to [email protected] asking to join the ‘CABLE software group’ and include your pre-existing NCI login, or the NCI identity number that you have received from Step 1 and a scan of the signed registration form.
Once registered you will receive a welcome message from the CABLE email list, and a NCI login if you have not had one previously. This NCI login will grant you access to both the CABLE trac page and the repository (discussed in Section 2.1), but does not have any compute resources attached to it. The trac system serves as a management tool for the CABLE project. All issues related to CABLE can be submitted via tickets, which can then be assigned to relevant persons to be addressed. The ticket can be passed on, resolved, stimulate further investigation and tickets etc, all the while being documented accordingly. Furthermore these tickets are accessible (and linkable) by all members of the community – to read and comment.
In addition to the ticket management system, trac provides a wiki mechanism for communication amongst the community, hosting documents, listing publications, etc. The trac can even be used to browse the repository code, logs and version history. Note however, that even though it is possible, code should not be downloaded via the trac. Code downloaded in this manner is no longer linked to the repository.
** N.B. The following procedures can be performed on your own machines/servers especially when you do not have compute resource on the NCI system.
The CABLE repository uses Subversion (svn) version control software. For excellent and reliable information see the developer’s documentation at http://svnbook.red-bean.com/. Be sure to get the right documentation to match your client version. For your reference the repository (host) is currently using version 1.6.11.
The CABLE svn repository lives on the trac.nci.org.au server, in the directory /svn/cable. The svn URL of the CABLE repository (root) is thus https://trac.nci.org.au/svn/cable. Note: from hereon we represent the root of the repository with the symbol !^.
Fig. 2 shows the structure of the repository, comprising a trunk, tags and branches. Most version control repositories are setup this way, however this structure (and also the names ‘ tags, trunk and branches’) is quite arbitrary. The repository is more or less a file system and tags, trunk and branches are merely the top-level directories. In svn jargon directories are often referred to generically as branches . In general the ‘official’ version of CABLE is developed in the branch called trunk, formal releases are available in the tags branch, while user development occurs in the branches branch. branches/Users is for developments that are being undertaken by individual users, whilst branches/Share is for developments that are being undertaken by a group of people.
Standard practice is to copy the branch from the repository into which you envisage your developments returning, which is generally the trunk. Initially however, users should start with the latest tagged release of CABLE as this is consistent with the corresponding files you will need from CABLE-AUX (discussed below). The following examples assume using v2.0. The first step is to copy the tag to your own branch (otherwise you will be unable to commit any changes you make back into the repository). Using user NCI_login as an example
svn copy !^/tags/CABLE-2.0 !^branches/Users/NCI_login/CABLE-2.0_feature1
Here, CABLE-2.0_feature1 is the name given to the branch. Choose a meaningful name as it is unlikely that this will be the only branch you create. You can also create a directory structure in your user branch. Once you have copied the tag to your own branch you can check it out with,
svn checkout !^/branches/Users/NCI_login/CABLE-2.0_feature1
By default this will create a working copy in the directory from which you execute the command called CABLE-2.0_feature1. If you want it called 'something_else' you can just do
svn checkout !^/branches/Users/NCI_login/CABLE-2.0_feature1 something_else
There is no limit to how many times you can check out the same branch, nor how many different names you give it. Keep in mind though that all copies refer back to the same branch, limiting the usefulness of this property.
Figure 2: CABLE Subversion repository tree structure
In all modes, using CABLE requires providing some extra data/information that is not included with the source code downloaded in the previous section. We package this auxiliary data separately in a directory/branch called CABLE-AUX, which can be downloaded from the repository. Using consistent nomenclature as in Section 2.1:
svn checkout !^/branches/Share/CABLE-AUX
Note: Users will not have write permission to this branch, however it is recommended that you do “check out” this branch so that it is clear what version of CABLE-AUX you have, and it is a simple matter to update your copy of CABLE-AUX later on. It should be further stressed that some of the auxiliary files kept in CABLE-AUX (some of which are absolutely necessary to use CABLE) may be appropriate for specific versions of the trunk. This will be noted in revision logs.
It is useful at this stage for us to introduce the contents of CABLE-AUX. The directory structure of CABLE-AUX is shown below.
- UM
- UMUI
- core
- offline
The only difference between this directory structure and that of the source code (Section 6), is the inclusion of a UMUI sub-directory. ln the UMUI sub-directory, and also the UM sub-directory, are files required for running CABLE in the UM. The UM user interface is designed to run on one machine and then submit a build/run job to a subsequent, remote machine. Hence, only the UMUI/ subdirectory is required on the machine hosting the UM user interface. The UM/ sub-directory is required on the machine hosting the model build/run. All applications of CABLE require the core/ sub-directory. Implementations of CABLE offline require the offline sub-directory as well as core/.
In general CABLE requires initialization of certain surface variables, vegetation and soil parameters and, in offline cases, meteorological forcing. In both modes, offline and online, CABLE initializes its vegetation and soil parameters from text files located in CABLE-AUX/core/biogeophys. The CABLE-AUX/core/biogeochem sub-directory contains initialization files for CASA-CNP. Meteorological forcing and other surface data are obtained via the host model in the UM case. In offline mode, CABLE obtains this forcing and data from netcdf files. We provide examples of these files in the sub-directory CABLE-AUX/offline.
The paths to the files discussed above are defined in cable.nml. Currently we use separate namelist files for the UM and offline, examples of which can be found in the respective sub-directories of CABLE-AUX. By default the namelists are set to point to files used in pre-release testing of CABLE-2.0. These paths should be substituted with file paths applicable to your application. Note, however that some of the paths remain accessible on vayu for the sake of applications of CABLE in UM/ACCESS. It is hard- wired in the source code that the namelist file exists in the running directory of the executable. In the offline case you will need to copy the namelist file to the same directory as the CABLE executable. In the online case this is copied for you into the directory where the UM model is executed, from the default location of your CABLE-AUX/UM installation. This copy is then backed up and dated, however rest assured that the initial copy of the namelist will be used in subsequent CRUNs should the experiment be configured to re-run over consecutive periods. Basically the rule is that, cable.nml will be copied from CABLE-AUX/UM for NRUNs, and re-used for CRUNs.
The CABLE-AUX/UM sub-directory needs to be located on the machine which builds/runs the UM model. In this sub-directory are two files cable.nml and libcable.a. The namelist file, cable.nml, was briefly discussed above, and further in Sections 3.2, 4.3 and 5.1.1. libcable.a is the CABLE library generated by the build.ksh script accompanying the source code (Section 6). When the UM model is built, the over-ride file from above tells the UM where to pickup this file and link it into the generated UM executable.
In addition to the CABLE source code and CABLE-AUX folder that are available to download from the repository, there is also a CABLE tools branch ( at !^/branches/Share/tools). This “package” is an optional extra and not required to either build or run the CABLE model in any mode. We intend to further populate CABLE tools, however at present it is limited to a single tool in the sub-directory zero_diff.
Basically the zero_diff tool provides a means for testing the bit-wise reproducibility between two versions of CABLE. For example you may have made changes that you expect will be otherwise science neutral. You can test this assumption automatically on a fine scale in offline and online modes and also on any number of processors. Alternatively you may have made a change to the code which you expect should not affect CABLE in other modes. You can use the zero_diff tool to verify this.
Further documentation of this tool is available within the zero_diff directory.
