D.3 | Initialize a Spatial Data Pool Using an Ascii Grid

General Procedure

VELMA Simulator spatial data pools may be initialized by specifying "Set Spatial Data By Map" disturbances as part of a simulator run's simulation configuration. Each spatial data pool (and each layer of that pool for multi-layer pools) that is initialized must have a separate disturbance specified for it, and its own Grid Ascii (.asc) map file available for the disturbance to use as a data source1.

Assuming an otherwise already configured VELMA application, load the configuration (XML file) into JVelma. To initialize a spatial data pool (using the leaf biomass pool as our example), add a "Set Spatial Data By Map" disturbance event to the configuration:

Note

It's assumed that before configuring the simulation, you've already created a Grid Ascii map file (.asc) for the disturbance to use. How you create the map is up to you, but it must in standard Grid Ascii format, and have the same dimensions as the Grid Ascii map of DEM data that the simulation will use. For this example, each cell value in the Grid Ascii map file is assumed to be an amount of leaf biomass (in grams per square meter).

Add the New Disturbance Parameters to the Simulation Configuration

1. In JVelma, with the simulation configuration loaded, Click/open the "Edit" menu and Click/Select "Disturbances " -> "Add a Disturbance".
2. In the Disturbance Model Selector dialog, use the drop-down selector to find the "SetSpatialDataByMapDisturbanceModel" and Click/Set it as the Disturbance Type.
3. In the text box next to the "DisturbanceName" prompt, type in a name for this particular disturbance. The name should be unique (the dialog will warn you if you enter a name already in use) and it is better to avoid whitespace and non-alphanumeric characters. For this is example, the name will be "Init_Leaf_Biomass".
4. Click the "OK" button. The dialog closes, the parameters for a new Set Spatial Data By Map disturbance are added to the simulation configuration, and the view should shift to these new parameters in JVelma's "All Parameters" tab window.

1 Two or more Set Spatial Data By Map disturbances may be set to use the same Grid Ascii map file as their input data source, but it's more likely that a given spatial data pool to have its own unique input data source.

Configure the New Disturbance Parameters

The parameters for the Set Spatial Data By Map disturbance tell the disturbance when it should occur, What its data source is, and Which Spatial Data Pool to apply that data source to.

The initializeActiveLoops, initializeActiveYears" and initializeActiveJdays parameters, plus the occursAtStepStart parameter specify when this disturbance should occur. To initialize the leaf biomass pool before any simulation steps, set them as follows:

Parameter Name	Set Value As …	Comment
initializeActiveLoops	1	Occurs during the first loop
initializeActiveYears	2000	Assumes 2000 is the simulation's start year
initializeActiveJdays	1	Occurs during the first Julian day
occursAtStepStart	true	Disturbance will occur before any simulation work is performed on the day when it occurs

Set the spatialDataFileFullName parameter to the fully-qualified path and name of the Grid Ascii file that you plan to use as the input data source for biomass leaf values.

For this example, suppose that file is named "LeafBiomassData.asc" and resides in directory "C:\My Data\". The spatialDataFileName value should then be set to: "C:/My Data/LeafBiomassData.asc" (without the double-quotes).

Note

Instead of Windows backslash "\" path separators, use forward slash "/" characters as path separators. Also, be very careful with whitespace; if there is any, it must exactly match whatever whitespace is present in the actual path and filename.

Set the spatialDataName parameter to the Spatial Data Pool that will receive data from the file. For our example of leaf biomass, the pool name is "BIOMASS_LEAF_N" (without the double-quotes). Note

A table containing the names of the Velma Simulator's spatial data pools is available at the end of this document.

Set the spatialDataLayer parameter to the (one-based) layer index number of the spatial data pool layer that will receive data from the file.

For single-layer spatial data pools this value MUST be set to "1" see the table of spatial data at the end of this document for a summary of how many layers each pool has.

In summary, here is the full parameterization for our example Set (Leaf Biomass) Spatial Data Pool By Map disturbance:

ID Key	Value
/disturbance/Init_Leaf_Biomass/initializeActiveJdays	1
/disturbance/Init_Leaf_Biomass/initializeActiveLoops	1
/disturbance/Init_Leaf_Biomass/initializeActiveYears	2000
/disturbance/Init_Leaf_Biomass/modelClass	SetSpatialDataByMapDisturbanceModel
/disturbance/Init_Leaf_Biomass/occursAtStepStart	true
/disturbance/Init_Leaf_Biomass/spatialDataFileFullName	C:/My Data/LeafBiomassData.asc
/disturbance/Init_Leaf_Biomass/spatialDataLayer	1
/disturbance/Init_Leaf_Biomass/spatialDataName	BIOMASS_LEAF_N

Configured as specified by the parameters above, this SetSpatialDataByMapDisturbanceModel disturbance occurs once during the simulation; in the first loop, on the first day of 2000 (assumed to be the first year of simulation for our example) and before any simulation work is done on that day.

When the disturbance occurs, it will open the Grid Ascii spatial data file

"C:/My Data/LeafBiomassdata.asc", and set each cell of the BIOMASS_LEAF_N spatial data pool in layer

1 to the value for that cell read from the .asc spatial data file.

That's all there is to it!

Although SetSpatialDataByMapDisturbanceModel disturbances may be used for other purposes, by varying when they occur, this example shows the commonest use-case; initializing specific non- uniform values into a spatial data pool at the start of a simulation.

Caveat

There is no cross-checking of user-specified SetSpatialDataByMapDisturbanceModel disturbances. This means that it is possible to configure a simulation with multiple SetSpatialDataByMapDisturbanceModel disturbances targeting a single spatial data pool. In such circumstances, all multiple maps' values are applied to a single pool in succession, and the last map's values are the pool's "initialization". However, it is not possible to specify the sequence for the application of the multiple maps; hence what the pool is actually initialized to is ill-defined.

Cross-checking is automatically performed when the simulator's setStartStateSpatialDataFullDir parameter is specified, but under no other conditions.

The user, is therefore responsible for confirming that a collection of SetSpatialDataByMapDisturbanceModel distrubances do not "step on each other" with regard to the spatial data pools they modify.

A Partial List of Velma Simulator Spatial Data Pools (see Tutorial D.8 for full list)

Spatial Data Pool Name	Layers	Unit Type
BIOMASS_AG_STEM_N	1	N g/m^2
BIOMASS_BG_STEM_N	1	N g/m^2
BIOMASS_DELTA_AG_STEM_N	1	N g/m^2
BIOMASS_DELTA_BG_STEM_N	1	N g/m^2
BIOMASS_DELTA_LEAF_N	1	N g/m^2
BIOMASS_DELTA_ROOT_N	1	N g/m^2
BIOMASS_HARVESTED_TO_OFFSITE_C	1	C g/m^2
BIOMASS_LEAF_N	1	N g/m^2
BIOMASS_ROOT_N	4	N g/m^2
CO2	4	Carbon
DENITRIFICATION	4	N g/m^2
DETRITUS_AG_STEM_N	1	N g/m^2
DETRITUS_BG_STEM_N	4	N g/m^2
DETRITUS_BURNED_C	1	C g/m^2
DETRITUS_LEAF_N	1	N g/m^2
DETRITUS_ROOT_N	4	N g/m^2
DOC	4	C g/m^2
DON	4	N g/m^2
GROUND_SURFACE_TEMPERATURE	1	Degrees C
GROUND_TEMPERATURE_LAYERS	4	Degrees C
HUMUS	4	N g/m^2
NH4	4	N g/m^2
NITRIFICATION	4	N g/m^2
NO3	4	N g/m^2
NPP_C	1	C g/m^2
NPP_N	1	N g/m^2
UPTAKE_N	4	N g/m^2