Run Stages

Descriptions of the Run Stages

In dvmdostem, the concept of a "run stage" is used to run the model over different climatic periods of generally increasing complexity.

The primary difference between the run stages is the nature of the input climate dataset, and specifically whether there is annual variability in the driving climate data that the model uses.

A complete, future projecting, simulation is usually only made after advancing the model through several previous "run stages" to stabilize the system. Typically the ending state from each stage is used as the beginning state for each subsequent stage.

equlibrium (eq)

In the equlibrium stage, the climate is fixed. That is, the climate does not vary from year to year. There will be intra-annual variability to represent the seasons, but from year to year the calculations will be carried out using the same annual cycles. Equlibrium run stage is used in the calibration mode, and is typically the first stage run for any complete simulation. There are constants set in the model's source code that define the minimum and maximun number of years to run in eq stage in the event that an internal equilibrium is not reached.

Note, as of 8/19/2016, I (tbc) don't think there is any kind of internal test for whether or not equilibrium has been reached. In other words, if you specify --max-eq=20000, the model will run for 20,000 years no matter what internal state it reached. It appears that some of the variable names and the command line flag --max-eq are vestigial remains of an attempt at "automatic equilibrium detection".

During the eq stage, the annual climate inputs used are actually calculated as the mean of the first 30 years of the historic climate dataset, so the mean of the values from 1901-1930.

spinup (sp)

In the spinup stage, the climate is not fixed. In the sp stage, the driving climate is used from the first 30 years of the historic climate dataset. Should the spstage be set to run longer than 30 years, the 30 year climate period is re-used. Another difference between eq and sp stages is that the sp stage is set to run for a fixed number of years, regardless of the internal state that the model reaches. In the sp stage the fire date is fixed, occuring at an interval equal to the Fire Recurrence Interval (FRI).

transient (tr)

In the transient stage, the climate varies from year to year. The tr stage is used to run the model over the period of historical record. The input climate data for the tr stage should be the historic climate. This is typically the climate data for the 20th century, so roughly 1901-2009.

scenario (sc)

In the scenario stage, the climate also varies from year to year, but rather than observed variability, a predicted climate scenario is used.

How to run different stages

1. Change the config file, stage_settings section. For run_stage, supply the two letter key for the stages you want to run (eq, sp, tr, sc). The order you provide the keys does not matter, the model will always follow this order:

    pre-run -> equilibrium -> spinup -> transient -> scenario
   

2. Create the template restart files. Use the python utility scripts/create_region_input.py to make your template files for the size of area you are working on. For instance:

    $ ./scripts/create_region_input.py  --crtf-only --xsize 10 --ysize 10 --tag Toolik
   

This should create 4 files that you can then copy into dvmdostem's output directory.

3. Run the model with approproate command line flags. For example:

    $ ./dvmdostem --pre-run-yrs 10 --max-eq 150 --sp-yrs 45
   

There is not an abundance of safety code that verifies the validity of differenent combinations of options from the config file, command line, and state of the input files. Caveat emptor - it is possible to specifiy combinations that don't make sense and to set up model runs that may fail later.

Diagram of run-stage I/O:

Dot code to make the diagram:

// run-stages-io.dot

digraph run_stages {

  rankdir = LR;
  rank = same;

  subgraph stages {
    "pre-run" -> equlibrium -> spinup -> transient -> scenario
  }

  subgraph files {
    node [shape=box style=filled, color=green];
    "restart-eq.nc"
    "restart-sp.nc"
    "restart-tr.nc"
    "restart-sc.nc"
  }

  edge [label="writes", color=red];
  equlibrium -> "restart-eq.nc" 
  spinup -> "restart-sp.nc"
  transient -> "restart-tr.nc"
  scenario -> "restart-sc.nc"

  edge [label="reads", color=black];
  "restart-eq.nc" -> spinup
  "restart-sp.nc" -> transient
  "restart-tr.nc" -> scenario

}

Run with:

$ dot -Tpng -o "run-stages-io.png"