-
Notifications
You must be signed in to change notification settings - Fork 0
CableUserGuide_ModelCode
This section describes the file and directory structure of the model code. The model code comprises core scientific code which is intended to be identical across different CABLE implementations and interface code which allows CABLE to run offline or coupled to an atmospheric model. The directory structure of CABLE-2.0 is shown in Fig. 3. The three subdirectories of CABLE contain interface code (offline, UM) and core science code (core), split into biogeophys and biogeochem. biogeochem contains the CASA-CNP code.
Figure 3: The directory structure of the CABLE model.
Table 2: Fortran files in core/biogeophys subdirectory
#!html
<table cellpadding=5 cellspacing=0 style='background-color:#f8f8f8; border-top: 1px solid black; border-bottom: 1px solid black;'>
<tbody>
<tr>
<th colspan=2>
<strong>core/biogeophys</strong>
</th>
</tr>
<tr>
<td>cable_air.F90</td>
<td>Fills CABLE type 'air' with appropriate values calculating temperature dependent physical constants</td>
</tr>
<tr>
<td>cable_albedo.F90</td>
<td>Calculates surface albedo, including from snow covered surface</td>
</tr>
<tr>
<td>cable_canopy.F90</td>
<td>Calculates surface exchange fluxes through the solution of the combined equations of stomatal conductance, photosynthesis and surface energy balance. Transport of scalars within a canopy is included.</td>
</tr>
<tr>
<td>cable_carbon.F90</td>
<td>Calculates plant and soil respiration and updates carbon pools. Note: carbon pools reset if ACCESS model run restarted. Use CASA-CNP in preference to these routines for carbon fluxes</td>
</tr>
<tr>
<td>cable_cbm.F90</td>
<td>Calls CABLE routines including define_air, surface_albedo, define_canopy, soilsnow, carbon. Note that cbm is called once per timestep in the offline case but twice per timestep in the ACCESS case. Not all parts of cbm are executed in each of the ACCESS calls</td>
</tr>
<tr>
<td>cable_radiation.F90</td>
<td>Computes radiation absorbed by canopy and soil surface</td>
</tr>
<tr>
<td>cable_roughness.F90</td>
<td>Calculate roughness lengths as a function of soil and canopy parameters</td>
</tr>
<tr>
<td>cable_soilsnow.F90</td>
<td>All routines for calculating soil temperature and moisture and snow calculations</td>
</tr>
<tr>
<td>cable_common.F90</td>
<td>Reads vegetation and soil parameter files, fills vegin, soilin. NB. Most soil parameters overwritten by spatially explicit datasets input as ancillary file (for ACCESS) or surface data file (for offline). Module enables accessibility of variables throughout CABLE</td>
</tr>
<tr>
<td>cable_data.F90</td>
<td>Defines constants for CABLE</td>
</tr>
<tr>
<td>cable_define_types.F90</td>
<td>Defines parameters, variables and derived types, allocation and deallocation of these derived types</td>
</tr>
</tbody>
<table>
Table 3: Fortran files in core/biogeochem subdirectory
#!html
<table cellpadding=5 cellspacing=0 style='background-color:#f8f8f8; border-top: 1px solid black; border-bottom: 1px solid black;'>
<tbody>
<tr> <th colspan=2> <strong>core/biogeochem</strong> </th></tr>
<tr><td>casa_inout.F90</td></tr>
<tr><td>Input and output code for CASA-CNP when run offline. ACCESS version may use some of this code but still to be finalised</td></tr>
<tr><td>casa_variable.F90</td></tr>
<tr><td>defines/allocates variables for CASA-CNP</td></tr>
<tr><td>casa_cable.F90</td></tr>
<tr><td>Includes bgcdriver - interface between CASA-CNP and CABLE; sumcflux - accumulating carbon fluxes (not required for UM)</td></tr>
<tr><td>casa_cnp.F90</td></tr>
<tr><td>subroutines for calculating carbon, nitrogen, phosphorus cycle including plant growth</td></tr>
</tbody>
</table>
Table 4: Fortran files in offline subdirectory
#!html
<table cellpadding=5 cellspacing=0 style='background-color:#f8f8f8; border-top: 1px solid black; border-bottom: 1px solid black;'>
<tbody>
<tr> <th colspan=2> <strong>offline</strong> </th></tr>
<tr><td>cable_abort.F90</td> <td>Error management for CABLE offline</td></tr>
<tr><td>cable_checks.F90</td> <td>Defines ranges to verify validity of input and outputs, checks mass balance and energy balance.</td></tr>
<tr><td>cable_driver.F90</td> <td>Offline driver for CABLE</td></tr>
<tr><td>cable_initialize.F90</td> <td>Default initialization module for CABLE offline</td></tr>
<tr><td>cable_input.F90</td> <td>Input module for CABLE offline version</td></tr>
<tr><td>cable_iovars.F90</td> <td>Defines input/output related variables for CABLE offline</td></tr>
<tr><td>cable_output.F90</td> <td>Output module for CABLE offline</td></tr>
<tr><td>cable_parameters.F90</td> <td>Reads default parameter sets and basic initializations for CABLE. Parameter values are chosen based on a global map of vegetation and soil types.</td></tr>
<tr><td>cable_read.F90</td> <td>Read routines for CABLE offline</td></tr>
<tr><td>cable_write.F90</td> <td>Writing routines for CABLE offline</td></tr>
<tr><td>cable_mpicommon.F90</td> <td>Supporting routines for the mpi wrapper</td></tr>
<tr><td>cable_mpidrv.F90</td> <td>Driver for the mpi wrapper of CABLE</td></tr>
<tr><td>cable_mpimaster.F90</td> <td>Driver for CABLE on the master CPU</td></tr>
<tr><td>cable_mpiworker.F90</td> <td>Driver for CABLE on the worker CPU</td></tr>
</tbody>
</table>
Table 5: Fortran files in UM subdirectory
#!html
<table cellpadding=5 cellspacing=0 style='background-color:#f8f8f8; border-top: 1px solid black; border-bottom: 1px solid black;'>
<tbody>
<tr> <th colspan=2> <strong>UM</strong> </th></tr>
<tr><td>cable_explicit_driver.F90</td> <td>Passes UM variables to CABLE, calls cbm, passes CABLE variables back to UM.</td></tr>
<tr><td>cable_hyd_driver.F90</td> <td>Converts selected CABLE hydrology variables to UM variables for UM hydrology code</td></tr>
<tr><td>cable_implicit_driver.F90</td> <td>Updates CABLE variables (as altered by first pass through boundary layer and convection scheme), calls cbm, passes CABLE variables back to UM</td></tr>
<tr><td>cable_rad_driver.F90</td> <td>Pass CABLE albedo to UM variable for UM radiation scheme</td></tr>
<tr><td>cable_um_init.F90</td> <td>Initialize and update CABLE variables from UM forcing, calls to memory allocation and initialization routines</td></tr>
<tr><td>cable_um_init_subrs.F90</td> <td>Routines to pass UM variables into appropriate CABLE variables and to map parameters for each surface type to CABLE arrays</td></tr>
<tr><td>cable_um_tech.F90</td> <td>Routines to read CABLE namelist, check variables, allocate and deallocate CABLE arrays</td></tr>
</tbody>
</table>
We provide here a few notes on how CABLE is coupled to the UM. CABLE is called in the UM from four different places, corresponding to points where the UM either has available or is ready to receive, particular land-surface variables. Specifically the four calls to CABLE (from UM 7.3) are as follows
#!html
<table cellpadding=5 cellspacing=0 style='background-color:#f8f8f8; border-top: 1px solid black; border-bottom: 1px solid black;'>
<tbody>
<tr><td>CALL cable_rad_driver</td> <td>from</td> <td>control/top_level/ glue_rad-rad_ctl2.F90</td></tr>
<tr><td>CALL cable_explicit_driver</td> <td>from</td> <td>atmosphere/boundary_layer/sf_exch.F90</td></tr>
<tr><td>CALL cable_implicit_driver</td> <td>from</td> <td>atmosphere/boundary_layer/sf_impl.F90</td></tr>
<tr><td>CALL cable_hyd_driver</td> <td>from</td> <td>atmosphere/land_surface/hydrol.F90</td></tr>
</tbody>
</table>
The main CABLE routine ‘cbm’ is called twice per UM timestep, since a first estimate of surface fluxes is required for the boundary layer and convection routines, but these fluxes then need to be recalculated following those routines. ‘soilsnow’ and ‘carbon’ are only executed on the second of these two ‘cbm’ calls.
In general, the UM uses multi-dimensional arrays to store variables, in which not all elements represent active land points in the model. CABLE, on the other hand, is designed to process a one dimensional vector, in which all elements are expected to be active land points. The fortran routines PACK and UNPACK are used to pass variables between the UM and CABLE and back to the UM.
There are many reasons why you might want to change the CABLE code such as to add some new capability, to test an alternative parameterisation or to improve a simulation for a specific location. The best way to keep track of those changes, and hopefully later to contribute them to the core CABLE code, is to use the CABLE repository.
The first step is to create a branch in the repository for yourself and to check out a copy of the code (Section 2.1). You might create your branch from the tagged CABLE-2.0 release, the trunk (if it has been updated since the release due to a bug fix etc), or a shared branch that a group of people are working on. Once you have a working copy of CABLE, under version control, the general development workflow is as follows:
- Make changes to the code
- Commit those changes back to the repository
- Update your working copy
After you have made changes to the code, enter svn status at the command line. This will show you the status of your working copy relative to the latest version of your working copy’s origin in the repository (in general, your branch). More specifically it will show you changes relative to the latest version you updated (see notes on svn update below). The most likely thing you will see is the files you changed with an ‘ M’ for modified next to them, and possibly a bunch of other files with a ‘ ?’ next to them. The ‘ ?’ means that svn doesn’t know anything about these files because they don’t exist in the repository. If you want them to be added to the repository use svn add filename. For a list of all character codes used by svn status, type svn help status. svn diff will show you the changes made to the modified files relative to the repository branch. svn revert will revert these changes. You can do one file at a time, one directory, etc., with all of these commands.
svn commit will record these changes to the branch in the repository you checked out from i.e. in the example from Section 2.1 this is *!^branches/Users/*NCI_login /CABLE-2.0_feature1. This can also work on a single file or directory if specified, otherwise by default it will commit everything that is revealed by svn status(Except the ‘?’ files and a few others we will not go into here). Entering svn commit will bring up your designated editor, prompting for a log message. DO NOT waste time entering your name, the date, the files that were changed, the code changes etc. All of this is recorded automatically by svn. DO enter something meaningful which svn doesn’t know e.g. why the change was made, what you are achieving or testing, relevant papers, etc. There may be a limit to the length of a log message, but we haven’t found it yet.
The next thing to type is svn log. Ordinarily you would expect to see the log you just entered. The reason you don’t is that your working copy has hidden links to the repository, and these links are not up-to-date. Type svn update. This is a good habit to get into for a lot of reasons, but the first one you will come across is this. Now type svn log again. svn log –v will also list the files that have been changed.
Repeat steps 1, 2 and 3 as required.
To keep your working copy in sync with whichever location you originally branched from (original_location) you can use merging. First go into CABLE-2.0_feature1, and then
svn merge !^/original_location
If you have made no changes since you copied the original_location to CABLE-2.0_feature1 then this will be a very straightforward process. Following the merge enter svn status. This will show the files that were updated from merging with the original_location. Perform steps 2 and 3 from above.
If you have made changes since you copied the original_location to CABLE-2.0_feature1 then you need to make sure you commit those changes and update your branch (steps 2 and 3 above) before merging. Once you have done this then you can merge the original_location into your working copy. This process will be very straightforward so long as the files that have been modified in the original_location since you first copied it are not the same files that you have changed and committed. In fact, the files can be the same, so long as the lines that are modified in each file are not the same.
If svn merge does encounter modifications to the same lines in each file, then it will report a conflict. You have to resolve a conflict yourself. If this occurs then it is advised that you consult the svn documentation or seek further advice from [mailto:[email protected] [email protected]]; there are too many permutations of possible conflicts and possible solutions to be able to succinctly describe a proper course of action here. Even if a conflict is not reported, it is wise to check all files that have been merged in this way; while a code conflict may not have occurred, there could be a conflict in what the code is intended to do.
Your updated branch can then be shared with other CABLE users. By default, the repository is set up so that a user is only allowed to write to branches that they own i.e. *!^/branches/NCI_login / while all branches are readable. If you do not want your branches to be readable by others, please contact [mailto:[email protected] [email protected]].
If you have a code change that you would like to be part of the official CABLE code, please read the ‘Guidelines for use and development of CABLE’ and contact the CABLE coordinator.
