Skip to content

Installation instructions

To install CABLE you need to have the following already installed on your system:

  • git
  • cmake
  • pkg-config
  • MPI (for parallel applications)
  • a Fortran compiler
  • the netCDF library

Flowchart of the installation

graph TD

    A(Clone CABLE with git):::UserAction -->|Serial?| B(Run `./build.bash`):::UserAction;
    B --> D[load modules and invoke `cmake`];
    D -->|Serial?| E;
    E[executable `cable`]:::Output;
    A -->|Parallel?| C(Run `./build.bash --mpi`):::UserAction;
    C --> D;
    D -->|Parallel?| F;
    F[executable `cable-mpi`]:::Output;
    click A "#getting-the-cable-source-code"
    click B "#launching-the-build"
    click C "#launching-the-build"
    click D "#description-of-the-build-process"
    click E "#description-of-the-build-process"
    click F "#description-of-the-build-process"

    UserAction ---- Automatic ---- Output;

    UserAction(Actions from the user):::UserAction;
    Automatic(Automatic steps of the build script);
    Output(Output of the build script):::Output;

    classDef UserAction fill:#FEFB8E
    classDef Output fill:#cefe8e

Getting the CABLE source code

CABLE can be downloaded from the GitHub repository. To install the latest version of CABLE, you simply need to clone the repository:

git clone https://github.com/CABLE-LSM/CABLE.git

Choice of protocol

If you have SSH keys installed for GitHub, you can also use the SSH protocol to clone the CABLE repository.

Building CABLE

In this section, we discuss building CABLE offline for single-site and regional/global applications.

In principle, the only requirements for building and running CABLE are a Fortran compiler and a netCDF distribution. However, in reality it is rarely so simple as this makes it sound.

Whilst we have endeavoured to make CABLE as portable as possible, and indeed we have used CABLE on a variety of platforms, our discussion here is limited to building CABLE on UNIX/Linux platforms only. Specifically, on Gadi@NCI, using Intel Fortran compiler. On other HPC systems there are likely modules available for both Fortran and netCDF. We recommend to get advice from your local system administrators.

See Build System for more extensive documentation on the build system.

CABLE has the directory structure:

science/
util/
params/
offline/
coupled/

All applications use the science/ util/ params/ directories. Offline applications also use the offline/ directory. Coupled applications use the coupled/ directory instead. We will not discuss the coupled applications any further here. Please refer to the documentation for a specific coupled application with CABLE to learn more.

Launching the build

CABLE supports both serial and parallel applications.

Serial for single-site

On a single processor, for single-site investigations with a suitable restart file, CABLE usually executes a year of forcing data in a matter of seconds/minutes. Even in the absence of a restart file, thus requiring spinup of the model, this usually doesn't take more than a few minutes. In this case a serial version of CABLE will suffice.

Multiprocessor for global simulations

For global (or regional) offline simulations, CABLE can still be run in serial mode (about 15 minutes/year for GSWP global run at 1x1 degree resolution). However, running on multiple processors speeds up the simulation considerably.

CABLE can be built using the BASH script build.bash in the project root directory.

Build on other HPC

Gadi specific configuration is guarded by a check on the current hostname (see here). This may be of use as a template for building CABLE on another Linux/HPC system. For advice on issues relating to porting to other HPC systems, please get in touch with ACCESS-NRI either via GitHub or the ACCESS-Hive Forum.

Executables are built in the <project_root>/build directory. Once built successfully, they are then installed in the <project_root>/bin directory.

To build the serial model execute:

./build.bash

To build the parallel model execute the same build script but with the --mpi flag.

./build.bash --mpi

Cleaning the build

From time to time, it might be useful to clean a previous build completely and restart the build from scratch.

To clean the previous build prior to compiling, specify the --clean flag to build.bash.

./build.bash --clean

Enabling debug mode

The release build is default. To enable debug mode, specify the CMake option -DCMAKE_BUILD_TYPE=Debug when invoking build.bash.

Enabling verbose output from Makefile builds

To enable more verbose output from Makefile builds, specify the CMake option -DCMAKE_VERBOSE_MAKEFILE=ON when invoking build.bash.

Tip

Run ./build.bash --help for information on supported options.