1. Model Overview

1.1. Structure

dvmdostem is multi-dimensional. It operates across spatial and temporal dimensions, soil layers, and plant functional types.

1.1.1. Spatial

TEM is a spatially explicit model. The run domain is divided into grid cells, or pixels. There is no communication between the grid cells. TEM itself is agnostic to the spatial resolution - the resolution is controlled by the input files provided. Recent work has been done with 1km spatial resolution.

1.1.2. Temporal

TEM is a temporal model in the sense that a run operates processes at consecutive time-steps. In addition, with TEM, the concept of a “run stage” is used to run the model over different climatic periods of generally increasing complexity. There are 5 possible “run stages”:

• Pre-run (pr)

• Equilibrium (eq)

• Spinup (sp)

• Transient (tr)

• Scenario (sc)

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 of the previous run stages to stabilize the system. Typically the ending state from each stage is used as the beginning state for each subsequent stage.

A complete run utilizes all 5 stages. It is possible to work with any subset of the stages.

pre-run (pr)

The pre-run is an equilibrium run for the physical variables of the model. It is typically 100 years, uses constant climate (typically monthly average computed from the [1901-1930] period).

equilibrium (eq)

In the equilibrium 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. Equilibrium run stage is used in the calibration mode, and is typically the first stage run for any complete simulation. 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.

Note

Automatic equilibrium detection. TEM does not have an 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 and constant names and the command line flag --max-eq are vestigial remains of an attempt at “automatic equilibrium detection”.

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.

A complete run utilizes all 5 stages. It is possible to work with any subset of the stages

1.1.3. Community Types (CMTs)

Each TEM grid cell can be assigned one “community type” (CMT). A community type is essentially a parameterization that specifies many properties for vegetation, and soil.

1.1.4. Vegetation Types (PFTs)

WRITE THIS…

1.1.5. Soil (Layers)

WRITE THIS…

1.2. Processes

WRITE THIS…

1.2.1. Carbon

WRITE THIS…

1.2.2. Water

WRITE THIS…

1.2.3. Nitrogen

WRITE THIS…

1.2.4. Energy Balance

WRITE THIS…

1.2.5. Permafrost

WRITE THIS…

1.2.6. Disturbance

WRITE THIS…

1.2.7. Methane

WRITE THIS…

1.3. Inputs/Outputs (IO)

1.3.1. Inputs

Generally TEM requires several types of inputs:

• Spatially explicit - varies over spatial dimensions.

  Examples are the topography variables, slope, aspect and elevation, which change for geographic location, but are fixed through time.

• Temporally explicit - varies over time dimension.

  An example (and in fact the only such input for TEM) is atmospheric CO2 concentration, which is roughly the same across the globe, but varies over time.

• Temporally and spatially explicit - varies over time and spatial dimensions.

  Examples are climate variables like air temperature and precipitation.

The dvmdostem code is neither particularly smart nor picky about the input files. There is minimal built-in error or validity checking and the program will happily run with garbage input data or fail to run because of an invalid attribute or missing input data value. It is up to the user to properly prepare and validate their input data. There is a helper program specifically for generating inputs from data provided by SNAP. This data was prepared as part of the Alaska IEM project (more info here). It remains an open project to generate input data from another source, e.g. ERA5 or a different soil database, etc.

Here some things that are generally assumed (program will likely run; results will likely be invalid) or expected (program unlikely to run if condition not met) of dvmdostem input files:

• The model assumes the dimension order to be (time, Y, X), as per CF Conventions.

• The time axes of the files are assumed to align exactly.

• Input file spatial extents are assumed to align exactly.

• The model expects inputs in NetCDF format.

• The variables names are expected to exactly match the names as shown in the table below.

While there is full support for geo-referenced files, this is not a requirement. Internally, the model requires the latitude for only a single calculation. The geo-referencing information is simply passed along to the output files. It is not used internally and is primarily for provenance and to enable pre and post processing steps. In the event that the file(s) are projected and or geo-referenced, they should contain extra variables and attributes for projection coordinate data, unprojected coordinate data, and grid mapping strings.

The complete list of required TEM input variables is shown below.

file	variable name	dimensions	units
run-mask.nc
	run	Y X
drainage.nc
	drainage_class	Y X
vegetation.nc
	veg_class	Y X
topo.nc
	slope	Y X
	aspect	Y X
	elevation	Y X
soil-texture.nc
	pct_sand	Y X
	pct_silt	Y X
	pct_clay	Y X
co2.nc projected-co2.nc
	co2	year
historic-climate.n c projected-climate. nc
	tair	time Y X	celcius
	precip	time Y X	mm month-1
	nirr	time Y X	W m-2
	vapor_press	time Y X	hPa
	time	time	days since YYYY-MM-DD HH:MM:SS
fri-fire.nc
	fri	Y X
	fri_severity	Y X
	fri_jday_of_bur n	Y X
	fri_area_of_bur n	Y X
historic-explicit- fire.nc projected-explicit -fire.nc
	exp_burn_mask
	exp_jday_of_bur n
	exp_fire_severit y
	exp_area_of_bur n
	time	time	days since YYYY-MM-DD HH:MM:SS

Note

Example code to generate the above table.

import os; import netCDF4 as nc
indir_path = "demo-data/cru-ts40_ar5_rcp85_ncar-ccsm4_toolik_field_station_10x10"
for f in filter(lambda x: '.nc' in x, os.listdir(indir_path)):
    ds = nc.Dataset(os.path.join(indir_path, f))
    print(f)
    for vname, info  in ds.variables.items():
        if 'units' in info.ncattrs():
            us = info.units
        else:
            us = ''
        print("  {:25s},{:15s},{:25s}".format( vname, ' '.join(info.dimensions),us))

1.3.2. Outputs

The outputs that are available for DVM-DOS-TEM are listed in the config/output_spec.csv file that is shipped ith the repo. The following table is built from that csv file:

output_spec.csv

Name	Description	Units	Yearly	Monthly	Daily	PFT	Compartments	Layers	Data Type	Placeholder
ALD	Soil active layer depth	m		invalid	invalid	invalid	invalid	invalid	double
AVLN	Total soil available N	g/m2			invalid	invalid	invalid		double
BURNAIR2SOILN	Nitrogen deposit from fire emission	g/m2/time			invalid	invalid	invalid	invalid	double
BURNSOIL2AIRC	Burned soil C	g/m2/time			invalid	invalid	invalid	invalid	double
BURNSOIL2AIRN	Burned soil N	g/m2/time			invalid	invalid	invalid	invalid	double
BURNTHICK	Ground burn thickness	m			invalid	invalid	invalid	invalid	double
BURNVEG2AIRC	Burned vegetation C to atmosphere	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2AIRN	Burned vegetation N to atmosphere	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2DEADC	Burned vegetation C to standing dead C	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2DEADN	Burned vegetation N to standing dead N	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2SOILABVC	Burned vegetation C to soil above	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2SOILABVN	Burned vegetation N to soil above	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2SOILBLWC	Burned vegetation C to soil below	g/m2/time			invalid	invalid	invalid	invalid	double
BURNVEG2SOILBLWN	Burned vegetation N to soil below	g/m2/time			invalid	invalid	invalid	invalid	double
CMTNUM	Community Type Number	m		invalid	invalid	invalid	invalid	invalid	int
DEADC	Standing dead C	g/m2			invalid	invalid	invalid	invalid	double
DEADN	Standing dead N	g/m2/time			invalid	invalid	invalid	invalid	double
DEEPC	Amorphous SOM C	g/m2			invalid	invalid	invalid	invalid	double
DEEPDZ	Amorphous SOM horizon thickness	m		invalid	invalid	invalid	invalid	invalid	double
DRIVINGNIRR	Input driving NIRR	W/m2	invalid	invalid		invalid	invalid	invalid
DRIVINGRAINFALL	Input driving precip data after being split from snowfall	mm				invalid	invalid	invalid	float
DRIVINGSNOWFALL	Input driving precip data after being split from rainfall	mm				invalid	invalid	invalid	float
DRIVINGTAIR	Input driving air temperature data	degree_C	invalid	invalid		invalid	invalid	invalid	float
DRIVINGVAPO	Input driving vapor pressure	hPa	invalid	invalid		invalid	invalid	invalid	float
DWDC	Dead woody debris C	g/m2/time			invalid	invalid	invalid	invalid	double
DWDN	Dead woody debris N	g/m2/time			invalid	invalid	invalid	invalid	double
DWDRH	Dead woody debris HR	g/m2/time			invalid	invalid	invalid	invalid	double
EET	Actual ET	mm/m2/time					invalid	invalid
FRONTSDEPTH	Depth of fronts	mm				invalid	invalid		double
FRONTSTYPE	Front types					invalid	invalid		int
GPP	GPP	g/m2/time	y		invalid			invalid	double
GROWEND	Growing ending day	DOY		invalid	invalid	invalid	invalid	invalid	int
GROWSTART	Growing starting day	DOY		invalid	invalid	invalid	invalid	invalid	int
HKDEEP	Hydraulic conductivity in amorphous horizon	mm/day				invalid	invalid	invalid	double
HKLAYER	Hydraulic conductivity by layer	mm/day			invalid	invalid	invalid	forced	double
HKMINEA	Hydraulic conductivity top mineral	mm/day				invalid	invalid	invalid	double
HKMINEB	Hydraulic conductivity middle mineral	mm/day				invalid	invalid	invalid	double
HKMINEC	Hydraulic conductivity bottom mineral	mm/day				invalid	invalid	invalid	double
HKSHLW	Hydraulic conductivity in fibrous horizon	mm/day				invalid	invalid	invalid	double
INGPP	GPP without N limitation	g/m2/time			invalid			invalid	double
INNPP	NPP witout N limitation	g/m2/time			invalid			invalid	double
INNUPTAKE	Unlimited N uptake by plants. N uptake by happy plants when N is not limited.	g/m2/time			invalid		invalid	invalid	double
IWCLAYER	IWC by layer	m3/m3			invalid	invalid	invalid	forced	double
LAI	LAI	m2/m2			invalid		invalid	invalid	double
LAYERDEPTH	Layer depth from the surface	m			invalid	invalid	invalid	forced	double
LAYERDZ	Thickness of layer	m			invalid	invalid	invalid	forced	double
LAYERTYPE	0:moss 1:shlw 2:deep 3:mineral				invalid	invalid	invalid	forced	int
LTRFALC	Litterfall C	g/m2/time			invalid			invalid	double
LTRFALN	Litterfall N	g/m2/time			invalid			invalid	double
LWCLAYER	LWC by layer	m3/m3			invalid	invalid	invalid	forced	double
MINEC	Mineral SOM C	g/m2			invalid	invalid	invalid	invalid	double
MOSSDEATHC	Moss death carbon	g/m2			invalid	invalid	invalid	invalid	double
MOSSDEATHN	Moss death nitrogen	g/m2			invalid	invalid	invalid	invalid	double
MOSSDZ	Moss thickness	m		invalid	invalid	invalid	invalid	invalid	double
NDRAIN	N losses from drainage (AVLN)	g/m2/time	invalid	invalid	invalid	invalid	invalid	invalid	double
NETNMIN	Soil net N mineralization	g/m2/time			invalid	invalid	invalid		double
NIMMOB	Nitrogen immobilization	g/m2/time			invalid	invalid	invalid		double
NINPUT	N inputs into soil (AVLN)	g/m2/time			invalid	invalid	invalid	invalid	double
NLOST	N losses from soil (AVLN)	g/m2/time			invalid	invalid	invalid	invalid	double
NPP	NPP	g/m2/time			invalid			invalid	double
NRESORB	NRESORB	??			invalid			invalid	double
NUPTAKELAB	Labile N uptake by plants	g/m2/time			invalid		invalid	invalid	double
NUPTAKEST	Structural N uptake by plants	g/m2/time			invalid			invalid	double
ORGN	Total soil organic N	g/m2			invalid	invalid	invalid		double
PERCOLATION	Percolation by layer		invalid	invalid		invalid	invalid	forced	double
PERMAFROST	Permafrost (1 or 0)			invalid	invalid	invalid	invalid	invalid	int
PET	Potential ET	mm/m2/time					invalid	invalid	double
QDRAINAGE	Water drainage quotient (~ratio)				invalid	invalid	invalid	invalid	double
QDRAINLAYER	Qdrain per layer	mm	invalid	invalid		invalid	invalid	forced	double
QINFILTRATION	Water infiltration quotient (~ratio)				invalid	invalid	invalid	invalid	double
QRUNOFF	Water runoff quotient (~ratio)				invalid	invalid	invalid	invalid	double
RAINFALL	Total rainfall	mm			invalid	invalid	invalid	invalid	double
RG	Growth respiration	g/m2/time			invalid			invalid	double
RH	Heterotrophic respiration	g/m2/time			invalid	invalid	invalid		double
RM	Maintenance respiration	g/m2/time			invalid			invalid	double
ROLB	Relative organic horizon burned ratio C	g/g			invalid	invalid	invalid	invalid	double
ROOTWATERUPTAKE	Water uptake by roots per layer		invalid	invalid		invalid	invalid	forced	double
SHLWC	Fibrous SOM C	g/m2			invalid	invalid	invalid	invalid	double
SHLWDZ	Fibrous SOM horizon thickness	m		invalid	invalid	invalid	invalid	invalid	double
SNOWEND	DOY of last snow fall	DOY		invalid	invalid	invalid	invalid	invalid	int
SNOWFALL	Total snowfall	mm			invalid	invalid	invalid	invalid	double
SNOWLAYERDZ	Snow pack thickness by layer	m			invalid	invalid	invalid	forced	double
SNOWLAYERTEMP	Snow temperature by layer	degree_C			invalid	invalid	invalid	forced	double
SNOWSTART	DOY of first snow fall	DOY		invalid	invalid	invalid	invalid	invalid	int
SNOWTHICK	Snow pack thickness	m				invalid	invalid	invalid	double
SOMA	Soil organic C active	g/m2			invalid	invalid	invalid		double
SOMCR	Soil organic C chemically resistant	g/m2			invalid	invalid	invalid		double
SOMPR	Soil organic C physically resistant	g/m2			invalid	invalid	invalid		double
SOMRAWC	Soil organic C raw	g/m2			invalid	invalid	invalid		double
SWE	Snow water equivalent	kg/m2				invalid	invalid	invalid	double
TCDEEP	Thermal conductivity in amorphous horizon	W/m/K				invalid	invalid	invalid	double
TCLAYER	Thermal conductivity by layer	W/m/K			invalid	invalid	invalid	forced	double
TCMINEA	Thermal conductivity top mineral	W/m/K				invalid	invalid	invalid	double
TCMINEB	Thermal conductivity middle mineral	W/m/K				invalid	invalid	invalid	double
TCMINEC	Thermal conductivity bottom mineral	W/m/K				invalid	invalid	invalid	double
TCSHLW	Thermal conductivity in fibrous horizon	W/m/K				invalid	invalid	invalid	double
TDEEP	Temperature in amorphous horizon	degree_C				invalid	invalid	invalid	double
TLAYER	Temperature by layer	degree_C			invalid	invalid	invalid	forced	double
TMINEA	Temperature top mineral	degree_C				invalid	invalid	invalid	double
TMINEB	Temperature middle mineral	degree_C				invalid	invalid	invalid	double
TMINEC	Temperature bottom mineral	degree_C				invalid	invalid	invalid	double
TRANSPIRATION	Transpiration	mm/day				invalid	invalid	invalid	double
TSHLW	Temperature in fibrous horizon	degree_C				invalid	invalid	invalid	double
VEGC	Total veg. biomass C	g/m2			invalid			invalid	double
VEGN	Total veg. biomass N	g/m2			invalid			invalid	double
VWCDEEP	VWC in amorphous horizon	m3/m3				invalid	invalid	invalid	double
VWCLAYER	VWC by layer	m3/m3			invalid	invalid	invalid	forced	double
VWCMINEA	VWC top mineral	m3/m3				invalid	invalid	invalid	double
VWCMINEB	VWC middle mineral	m3/m3				invalid	invalid	invalid	double
VWCMINEC	VWC bottom mineral	m3/m3				invalid	invalid	invalid	double
VWCSHLW	VWC in fibrous horizon	m3/m3				invalid	invalid	invalid	double
WATERTAB	Water table depth below surface	m				invalid	invalid	invalid	double
YSD	Years since last disturbance	Years		invalid	invalid	invalid	invalid	invalid	int

Output Selection

WRITE THIS…

Note

draft thoughts: NetCDF outputs are specified in a csv file named in config/config.js. The csv file specifies a variable name (for identification only - it does not correspond to the variable name in the code), a short description, units, and what level of detail to output on (timestep and variable part). [Link to default file after PR merge] Variable name, Description, Units, Yearly, Monthly, Daily, PFT, Compartment, Layer, Example entry: VEGC,Total veg. biomass C,gC/m2,y,m,,p,c,, This will output VegC every month, and provide both PFT and PFT compartment values. The file is more user-friendly when viewed in a spreadsheet. [example] A complete list of output combinations is below The initial list of outputs can be found at Issue #252 LAYERDEPTH, LAYERDZ, and LAYERTYPE should be automatically output if the user specifies any by-layer output. They are not currently, so ensure that they are specified on the same timestep as the desired output. HKLAYER, LAYERDEPTH, LAYERDZ, LAYERTYPE, TCLAYER, TLAYER, and VWCLAYER must have the layer option specified or they will generate NetCDF dimension bound errors.

Process

WRITE THIS…

Note

draft thoughts: A single output file will be produced for each entry in the specifying file, based on variable name, timestep, and run stage. VEGC_monthly_eq.nc At the beginning of the model run, an output file will be constructed for each variable specified, for each run stage where NetCDF output is indicated and that has more than 0 years of run time. Currently the model tracks the variables specified for each timestep as separate sets (i.e. monthly separate from yearly, etc). This reduces the number of map lookups every time the output function is called, but increases the number of monthly vs. yearly string comparisons.

Variable Output Combinations

WRITE THIS…

Note

draft thoughts: ‘-’ indicates that the combination is not an option ‘x’ indicates that the combination has been implemented in the code ‘?’ indicates that it is undecided if the combination should be made available, or that structure in the code needs to be modified to make data available for output. Three variables should be automatically written out if any by-layer variable is specified: Layer type Layer depth Layer thickness Currently they are written out like standard variables. Automation will need to be added in the future.