Canadian Land Surface Scheme including Biogeochemical Cycles
How do I ... / Something has gone wrong!
  1. Change the number/depth/etc of soil layers?
  2. My run starts and I get an immediate fail!
  3. My run won't compile but I didn't do anything I can think of.
  4. initFileConverter tells me I need a soil colour index
  5. Run on a Windows Machine
  6. Gotcha for Windows users
  7. My site-level run fails with IZREF = 1 but is okay with IZREF = 2

Change the number/depth/etc of soil layers?

Information about the soil layers is taken in from the initialization netcdf file. model_state_drivers::read_modelsetup reads the netcdf for the number of soil layers (ignd). The DELZ variable in the intialization file is the thickness of each layer. So change the initialization file for the number and thicknesses of the soil layers as required and CLASSIC will simply read them in.

My run starts and I get an immediate fail!

If you start a new run and it immediately fails with an output something like:

    Singularity jormelton-containerCLASSIC-master-latest.simg:~/Documents/CLASSIC> bin/CLASSIC configurationFiles/template_job_options_file.txt 254.85/53.98
     in process           0           1           1   254.84999999999999        53.979999999999997                1           1           1           1
      CANOPY ENERGY BALANCE         1       8092.77620036       8077.49643236
             0.000000       1.875648      -2.045030      -0.189964       0.000000    8073.385790
             0.000000       1.339229     257.925000
     died on   254.84999999999999        53.979999999999997 

This is a general indication of a problem in your initialization file. Often it is fixed by setting snow/liquid in the canopy to zero (see Initialization of Physics Prognostic Variables). You may also get snow energy/water balance failing, again look to Initialization of Physics Prognostic Variables for advice with setup.

My run won't compile but I didn't do anything I can think of.

Sometimes you need to run a 'make mode=???? clean' (where mode is the one you used to compile the code, for site-level it is typically serial) to clean out old .mod and .o files that might be causing issues. Do that and then recompile.

initFileConverter tells me I need a soil colour index

Soil colour index is described in Input Soil Data and used in soilProperties.f90. A global file of soil colour index produced by Peter Lawrence (NCAR) can be obtained from

Run on a Windows Machine

Courtesy of E. Humphreys.

  1. Install Oracle VirtualBox
  2. Install Ubuntu as a virtual machine with ~ 100GB drive space
  3. Install Dropbox on Ubuntu (to share files between machines but there are other ways to do this)
  4. Install Singularity.
    1. In Terminal, type: >sudo apt install singularity-container
  5. Download our container into a working directory that is shared via Dropbox with the windows machine, e.g. ~/Dropbox/CLASSIC_working/:
    1. In Terminal, cd to your working directory and type: >singularity pull shub://jormelton/containerCLASSIC
  6. Shell into the container: >singularity shell jormelton-containerCLASSIC-master-latest.simg
  7. In this container, get CLASSIC code and folders:

**Note the text files need to have unix line endings if created in Windows (see Gotcha for Windows users), make sure to convert to Unix (LF) from Windows (CR LF).**

Gotcha for Windows users

Text files created on DOS/Windows machines have different line endings than files created on Unix/Linux. DOS uses carriage return and line feed ("\r\n") as a line ending, which Unix uses just line feed ("\n"). You need to be careful about transferring files between Windows machines and Unix machines to make sure the line endings are translated properly.(from

Any CLASSIC tool that reads in ASCII expects the Linux/Unix line endings.

My site-level run fails with IZREF = 1 but is okay with IZREF = 2

Site-level runs should use IZREF = 1 with appropriate values of ZRFM and ZRFH for your site (described in Setting up the joboptions file). However it is possible, especially with CTEM (biogeochemistry) on that the vegetation will grow taller than ZRFM/ZRFH causing the model to crash. The model may simulate vegetation at the site taller than reality due to prior land use history at the site, model bias, etc. In this case you will need to raise the ZRFM/ZRFH heights to remain above the canopy.