The Virtual Ecosystem core configuration#

The core configuration of the Virtual Ecosystem sets up the following parts of the simulation, which are shared across all of the science models. Each of these parts is configured in its own configuration section:

The core configuration section is also used to set the location of data input files for required forcing variables for the simulation, but the [core.data] section is discussed in the using your own data tutorial.

Tip

You may find it useful to create the core TOML configuration for your system as the first step in developing your own simulations. You can then load the TOML settings into data preparation scripts used to create other VE inputs. This can help keep the various data settings aligned across your project.

Validation of the core configuration#

Each of the model configuration options has specific validation settings that are enforced when a configuration is loaded. These constraints should be described in the documentation of each setting. If configuration data contains invalid values, then the simulation will exit and the log will contain a detailed breakdown of any configuration validation issues.

The spatial grid#

The [core.grid] configuration section is central to a Virtual Ecosystem simulation and defines a set of grid cells within which the simulation will run. Each cell can have its own climate and elevation and may contain different plant and animal communities. The relative elevations of the cells will also define the hydrology of the simulation.

At present, simulations only support rectangular arrays of square grid cells: you can set the number of cells and their area in square metres. You can also set an offset for the origin coordinates of the grid. This can be useful if you want to match your simulation coordinates to incoming data that has real world coordinates from a projected coordinate system.

[core.grid]
grid_type = "square"
cell_area = 8100.0
cell_nx = 9
cell_ny = 9
xoff = -45.0
yoff = -45.0
core.grid.grid_type

The grid cell type. The value must be one of the options supported by the :data:~virtual_ecosystem.core.grid.GRID_REGISTRY. Default = square

core.grid.cell_area

The area of each grid cell (m^2) Default = 8100.0

core.grid.cell_nx

Number of grid cells in x direction Default = 9

core.grid.cell_ny

Number of grid cells in y direction Default = 9

core.grid.xoff

The x offset of the grid origin Default = -45.0

core.grid.yoff

The x offset of the grid origin Default = -45.0

When running a simulation, the Virtual Ecosystem assigns a unique numeric cell id to each cell and these cell ids are widely used in data outputs. They are simply increasing integers starting from zero in the top left and increase across rows first ‘row major’ order. The default values above result in the grid layout, coordinates and cell id values shown below: a 9x9 grid of 90m resolution cells, with the coordinate origin in the centre of the lower left cell.

../../_images/a17f2dd712ffc08c518542587659fc0bc1ef492668751f6e00889c57acbcf0fe.png

Important

You need to make sure that all spatially structured input data - which is nearly all of the required starting variables for a simulation - is congruent with the grid configuration you use. That might be using the unique cell id codes or providing data as spatial grids in NetCDF format using the cell coordinates from your configuration.

The temporal extent and resolution#

The [core.timing] configuration section sets the temporal resolution of the simulation and the total number of time steps. You need to provide a start date, the time interval of updates and the total run length. The update interval and total run length can be provided as string descriptions.

[core.timing]
start_date = "2013-01-01"
update_interval = "1 month"
run_length = "2 years"
core.timing.start_date

The simulation start date. Default = 2013-01-01

core.timing.update_interval

The interval at which all models are updated. Default = 1 month

core.timing.run_length

The total run length of the simulation. Default = 2 years

Important

You need to make sure that all temporally structured input data is congruent with the timing configuration you use. That will typically be providing a time axis within a NetCDF file that matches the number of time steps defined above.

The vertical layer structure#

The [core.layers] configuration section defines the vertical layer structure of the simulation. The model uses a fixed number of layers along the vertical height axis: this configuration is used to set the actual heights of layers - sometimes relative to the canopy layer heights - and the number of layers. See the vertical structure implementation page for more details.

[core.layers]
soil_layers = [
    -0.25,
    -1.0,
]
canopy_layers = 10
above_canopy_height_offset = 2.0
subcanopy_layer_height = 1.5
surface_layer_height = 0.1
core.layers.soil_layers

A list of negative float values that provides the depth in metres of the soil horizons to be used in the simulation, hence also setting the number of soil layers and the horizon depth for each layer relative to the surface. The values must be unique and strictly decreasing. Default = [-0.25, -1.0]

core.layers.canopy_layers

The maximum number of canopy layers to simulate. This is used to control the number of layers with the canopy role. Not all of these layers necessarily contain canopy during a simulation as the canopy structure within these layers is dynamic. Default = 10

core.layers.above_canopy_height_offset

A height offset relative to the canopy top that is used as the measurement height of reference climate data. It sets the the height above the canopy top of the first layer role above (metres). Default = 2.0

core.layers.subcanopy_layer_height

The height above ground level of the ground surface atmospheric layer, used to calculate subcanopy microclimate conditions (metres). Default = 1.5

core.layers.surface_layer_height

The height above ground level of the ground surface atmospheric layer (metres). Default = 0.1

Data output settings#

The [core.data_output_options] section is used to control when data is exported from the simulation.

[core.data_output_options]
save_initial_state = false
save_continuous_data = true
save_final_state = true
save_merged_config = true
out_path = "<DIRPATH_PLACEHOLDER>"
out_initial_file_name = "initial_state.nc"
out_folder_continuous = "."
out_continuous_file_name = "all_continuous_data.nc"
out_final_file_name = "final_state.nc"
out_merge_file_name = "ve_full_model_configuration.toml"
core.data_output_options.save_initial_state

Whether the initial state should be saved Default = False

core.data_output_options.save_continuous_data

Whether continuous data should be saved Default = True

core.data_output_options.save_final_state

Whether the final state should be saved Default = True

core.data_output_options.save_merged_config

Whether to save a merged TOML file containing all config options Default = True

core.data_output_options.out_path

Directory path for output files Default = <DIRPATH_PLACEHOLDER>

core.data_output_options.out_initial_file_name

File name for initial state output file Default = initial_state.nc

core.data_output_options.out_folder_continuous

Folder to save states of simulation with time to Default = .

core.data_output_options.out_continuous_file_name

Name of file to save combined continuous data to Default = all_continuous_data.nc

core.data_output_options.out_final_file_name

File name for final state output file Default = final_state.nc

core.data_output_options.out_merge_file_name

Name for TOML file containing merged configs Default = ve_full_model_configuration.toml

Core constants#

The [core.constants] section defines a set of constants values that are shared across the whole simulation. This includes some global constants, as well as some values that are required across multiple models.

[core.constants]
standard_pressure = 101.325
standard_mole = 44.642
molar_heat_capacity_air = 29.19
gravity = 6.6743e-11
boltzmann_constant = 1.380649e-23
stefan_boltzmann_constant = 5.6703744191844314e-08
von_karmans_constant = 0.4
max_depth_of_microbial_activity = 0.25
meters_to_mm = 1000.0
mm_to_kg = 0.001
molecular_weight_air = 28.96
gas_constant_water_vapour = 461.51
seconds_to_day = 86400.0
seconds_to_hour = 3600.0
hours_per_day = 24
characteristic_dimension_leaf = 0.01
specific_gas_constant_dry_air = 287.05
molecular_weight_ratio_water_to_dry_air = 0.622
conductance_to_resistance_conversion_factor = 40.9
density_water = 1000.0
fungal_fruiting_bodies_c_n_ratio = 10.0
fungal_fruiting_bodies_c_p_ratio = 75.0
fungal_fruiting_bodies_decay_rate = 0.013862943611198907
air_volumetric_heat_capacity = 1200.0
initial_aerodynamic_resistance_canopy = 12.1
core.constants.standard_pressure

Standard atmospheric pressure, [kPa] Default = 101.325

core.constants.standard_mole

Moles of ideal gas in 1 m^3 air at standard atmosphere. Default = 44.642

core.constants.molar_heat_capacity_air

Molar heat capacity of air, [J mol-1 K-1]. Default = 29.19

core.constants.gravity

Newtonian constant of gravitation, [m s-1]. Default = 6.6743e-11

core.constants.boltzmann_constant

The Boltzmann constant, [J K-1] Default = 1.380649e-23

core.constants.stefan_boltzmann_constant

Stefan-Boltzmann constant, [W m-2 K-4].

The Stefan-Boltzmann constant relates the energy radiated by a black body to its temperature. Default = 5.6703744191844314e-08

core.constants.von_karmans_constant

Von Karman’s constant, [unitless].

The von Karman’s constant describes the logarithmic velocity profile of a turbulent fluid near a no-slip boundary. Default = 0.4

core.constants.max_depth_of_microbial_activity

Maximum depth of microbial activity in the soil layers [m].

The soil model needs to identify which of the configured soil layers are sufficiently close to the surface to contain significant microbial activity that drives nutrient processes. The default value is taken from Fatichi et al. (2019). No empirical source is provided for this value. Default = 0.25

core.constants.meters_to_mm

Factor to convert variable unit from meters to millimeters. Default = 1000.0

core.constants.mm_to_kg

Factor to convert variable unit from millimeters to kilograms of water per square metre. Default = 0.001

core.constants.molecular_weight_air

Molecular weight of air, [g mol-1]. Default = 28.96

core.constants.gas_constant_water_vapour

Gas constant for water vapour, [J kg-1 K-1] Default = 461.51

core.constants.seconds_to_day

Factor to convert variable unit from seconds to day. Default = 86400.0

core.constants.seconds_to_hour

Factor to convert variable unit from seconds to hours. Default = 3600.0

core.constants.hours_per_day

Number of hours per day. Default = 24

core.constants.characteristic_dimension_leaf

Characteristic dimension of leaf, typically around 0.7 * leaf width, [m]. Default = 0.01

core.constants.specific_gas_constant_dry_air

Specific gas constant for dry air, [J kg-1 K-1]. Default = 287.05

core.constants.molecular_weight_ratio_water_to_dry_air

The molecular weight ratio of water to dry air.

The ratio of the molar mass of water vapour (18.015 g/mol) to the molar mass of dry air (28.964 g/mol), which is approximately 0.622. This ratio is used in atmospheric calculations, particularly in determining the mixing ratio of water vapour to dry air. Default = 0.622

core.constants.conductance_to_resistance_conversion_factor

Conductance to resistance conversion factor.

This factor is used to convert between stomatal conductance in mmol m-2 s-1 and stomatal resistance in s m-1. Default = 40.9

core.constants.density_water

Density of water, [kg m-3]. Default = 1000.0

core.constants.fungal_fruiting_bodies_c_n_ratio

Carbon to nitrogen ratio of fungal fruiting bodies, [unitless].

This constant is stored in the CoreConsts as it is used by both the animal model (to work out consumption flows) and the soil model (to work out production rates). The current default value is very much a guess. Default = 10.0

core.constants.fungal_fruiting_bodies_c_p_ratio

Carbon to phosphorus ratio of fungal fruiting bodies, [unitless].

This constant is stored in the CoreConsts as it is used by both the animal model (to work out consumption flows) and the soil model (to work out production rates). The current default value is very much a guess. Default = 75.0

core.constants.fungal_fruiting_bodies_decay_rate

Rate constant for the decay of fungal fruiting bodies, [day^-1].

This is calculated based on the assumption that fungal fruiting bodies decay with a half-life of 50 days. This estimate should be improved based on empirical data. Default = 0.013862943611198907

core.constants.air_volumetric_heat_capacity

Volumetric heat capacity of air at constant pressure, [J m-3 K-1].

This represents the amount of heat energy required to raise the temperature of one cubic meter of air by 1 Kelvin. Default = 1200.0

core.constants.initial_aerodynamic_resistance_canopy

Initial aerodynamic resistance of the canopy, [s m-1].

This parameter is an initial estimate of the resistance to the transfer of momentum, heat, and water vapour between the leaf surface and the atmosphere. The value is based on Australian evergreen forest, taken from Su et al. (2021); note that this assumes a dense canopy. Default = 12.1