Software container for the Canadian Land Surface Scheme including Biogeochemical Cycles (CLASSIC)

Apptainer software container for the CLASSIC modelling framework. This software container is designed to integrate with the CLASSIC model (see also the CLASSIC gitlab repository and the version 2.0 Zenodo repository). Quick start guide Running the Quick Start Scripts This document will walk you through the basic setup, compilation, and running of CLASSIC at the CLASSIC benchmarking collection (CBC) FLUXNET sites. Requirements This guide assumes the reader is using a Linux machine (or environment that emmulates Linux such as Windows Subsystem for Linux (WSL)) and that they have Apptainer (previously named Singularity) and tar installed. Linux installation information for Apptainer can be found here and tar can be installed from here. If you are uisng a Windows or Mac machine, there is information on installing Apptainer for those environments here. Obtaining the Source Code The first step is setting up a directory structure to work in. For this guide, we will work in a directory located at /home/classic_ops. Which can be navigated to using the following command: cd /home/classic_ops The CLASSIC repository, which contains the source code, can be cloned with: git clone https://gitlab.com/cccma/CLASSIC.git OR If you are familiar with git’s workflow and wish to contribute to the codebase in the future, then it is a good idea to first fork a copy to your own GitLab account. Once you have a fork, you can clone the repository with: git clone https://gitlab.com/_your_gitlab_username_/CLASSIC.git Once the cloning process is complete, there should be a directory titled CLASSIC, located in your directory like: /home/classic_ops/CLASSIC Obtaining other necessary files All other necessary files are found here in the form of compressed packages. We will use the tar command to unpack them beside the CLASSIC repository, Your directory should now contain the following: /home/classic_ops/CLASSIC /home/classic_ops/CLASSIC_container.tar.gz /home/classic_ops/FLUXNET.tar.gz From the /home/classic_ops directory, we will decompress the tarballs and move the decompressed files to the locations used within the quick start scripts. We will have to make some of these locations first as well. The following list of commands will accomplish this: tar xzvf CLASSIC_container.tar.gz tar xzvf FLUXNET.tar.gz mv CLASSIC_container.sif CLASSIC/tools/apptainerContainerRecipe/ mkdir CLASSIC/inputFiles/CO2 mv FLUXNET/TRENDY_v13_CO2_1700-2023_GCP2024.nc CLASSIC/inputFiles/CO2/ mv FLUXNET/meteorology CLASSIC/inputFiles/ mv FLUXNET/FLUXNETsites_obs CLASSIC/inputFiles/ rm -r FLUXNET/ Note that the resulting directory structure is expected to be in place for the following steps to work. Using the container Navigate to the CLASSIC root directory (i.e, cd /home/classic_ops/CLASSIC). The rest of this guide will assume that you are located in this directory: While the quick start scripts discussed later in this guide are set up to execute container commands on behalf of the user, understanding how the basic container commands work can be handy to help solve any issues that come up. This may be necessary as the version of Apptainer being used and the Operating System you are working in can impact how to form the Apptainer commands. As we cannot anticipate and cover all possible cases within this guide, we recommend referring to the Apptainer documentation for assistance in figuring out what may work best for your setup. You may need to update the container commands in the scripts used throughout this guide in accordance with what works for your environment. However, the commands are all formulated the same way throughout the scripts and will therefore be easier to spot. We will go through the basics of how these commands are set up here. In general, the apptainer exec commands will be used the most often, these generally follow this format: apptainer exec . However, some flags can be added to this command to help limit the possibility of impacting directories outside of those strictly needed for running CLASSIC in the container. For example, we can mount the CLASSIC directory to a chosen directory path within the container and check its contents with the following command (all one command): apptainer exec --no-mount bind-paths --bind /home/classic_ops/CLASSIC:/work_zone/classic_tmp tools/apptainerContainerRecipe/CLASSIC_container.sif ls /work_zone/classic_tmp Here the --no-mount flag followed by the bind-paths option tells the container not to mount any paths that may have been set as defaults for apptainer in your environment (this might not be necessary to do for your set up but can usually be left in just in case). The --bind flag followed by : tells the container to mount the contents of to the location within the container (you can make up any location you want). This means you will have to navigate to the to access relevant material within container commands that have such a bind mount active (hence providing /work_zone/classic_tmp to the ls command above). The scripts used in this guide will be creating one or two bind mounts within the container: /work_zone/classic_tmp for the directory of the CLASSIC repository and /work_zone/run_tmp for the directory of the CLASSIC model run. Within the following scripts, these commands will frequently appear like this (all one command): apptainer exec --no-mount bind-paths --bind $rootdir:$runtime_rootdir --bind $runfolder:$runtime_outdir $rootdir/tools/apptainerContainerRecipe/CLASSIC_container.sif $runtime_rootdir/bin/$exec $runtime_outdir/$current/job_options_file.txt 0/0 You can see the same apptainer exec command and related flags, however, these are now accompanied by text starting with $. These are the bash syntax methods for accessing variables within the scripts which we have assigned to be the for the CLASSIC repository and CLASSIC model run directory, as well as the for the /work_zone/classic_tmp and /work_zone/run_tmp. We will show how to run the same command as above outside of the script in a later section of this guide. If you are comfortable with Apptainer and operating on a command line, you may also choose to "shell" into the container to run some commands. You can shell into the container using the following command, which also includes bind mounts (all one command): apptainer shell --no-mount bind-paths --bind /home/classic_ops/CLASSIC:/work_zone/classic_tmp --bind /home/classic_ops/quick_start_test_runs/all_sites_container_test_1:/work_zone/run_tmp tools/apptainerContainerRecipe/CLASSIC_container.sif Compiling the CLASSIC model We will compile the CLASSIC model using the container. A good first step is to make sure the work space is clean. This can be done with the following command (recall that we are still assuming we are located in the /home/classic_ops/CLASSIC directory)(all one command): apptainer exec --no-mount bind-paths --bind /home/classic_ops/CLASSIC:/work_zone/classic_tmp tools/apptainerContainerRecipe/CLASSIC_container.sif make -C /work_zone/classic_tmp mode=serial clean Since bind mounts are being used within the container we therefore have to tell the `make` command to use the right directory within the container (-C /work_zone/classic_tmp). Now we can compile the CLASSIC model with the following command (all one command): apptainer exec --no-mount bind-paths --bind /home/classic_ops/CLASSIC:/work_zone/classic_tmp tools/apptainerContainerRecipe/CLASSIC_container.sif make -C /work_zone/classic_tmp mode=serial Note that you may see the following warning appear on the command line as the model compiles, which is not a cause for concern: src/driver/prepareOutputs.f90:2032:26: 2032 | subroutine ctem_daily_aw (lonLocalIndex, latLocalIndex, nltest, nmtest, iday, ncount, nday, & | ^ note: variable tracking size limit exceeded with ‘-fvar-tracking-assignments’, retrying without... Setting up FLUXNET site-level runs The container is primarily designed to support site-level CLASSIC runs and the steps and scripts described in this guide are dedicated to that purpose. To prepare for a site-level run, we will first need to create a directory for the scripts and model to operate on using this command (you could name it whatever you wish): mkdir ../quick_start_test_runs/all_sites_container_test_1 Now we can begin preparing this directory for the CLASSIC model by running a script. The first script we will use is prep_jobopts.sh which is located in the tools/siteLevelFLUXNET directory of the CLASSIC repository. This script has one required input: the path to the directory we want to run the model in, which we created above. The command to prepare our directory with this first script is: tools/siteLevelFLUXNET/prep_jobopts.sh /home/classic_ops/quick_start_test_runs/all_sites_container_test_1 This script will generate the necessary subdirectories and files that the subsequent scripts and the CLASSIC model expect. One particular file of note is the job_options_file.txt file that is created for each site that is being run. The job_options_file.txt holds the different settings read in by the CLASSIC model. All model restart files (these are part of the files needed to initialize a model run) are provided in a ‘pre-spunup’ state. Still, running all sites can be a lengthy process on older machines, and sometimes you may not want or need all of them. To reduce the number of sites being run, remove the undesired site directories from inputFiles/FLUXNETsites_12PFT in the CLASSIC repository. For example, if you do not need to run site `DK-Sor`, you could move it up one directory level for the time being: mv inputFiles/FLUXNETsites_12PFT/DK-S