+

Appendix 2: Initializing a Spatial Data Pool Using an ASCII Grid


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

Assuming an otherwise already configured simulation configuration is loaded into JVelma, here is how toinitialize a spatial data pool (using the leaf biomass pool as our example) by adding a Set Spatial By Mapdisturbance event to the configuration:

Note

It's assumed that before configuring the simulation, you've already created a Grid ASCII map file (.asc) for thedisturbance to use. How you create the map is up to you, but it must in standard Grid ASCII format, and have thesame 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 gramsper 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 nameshould be unique (the dialog will warn you if you enter a name already in use) and it is better to avoidwhitespace 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 areadded to the simulation configuration, and the view should shift to these new parameters in JVelma's "AllParameters" tab window.

Configure the New Disturbance Parameters

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


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

The initializeActiveLoops, initializeActiveYears" and initializeActiveJdays parameters, plusthe occursAtStepStart parameter specify when this disturbance should occur. To initialize the leafbiomass pool before any simulation steps occur, 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 thatyou 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\". ThespatialDataFileName 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 ispresent in the actual path and filename.

Set the spatialDataName parameter to the Spatial Data Pool that will receive data from the file. For ourexample 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 thisdocument.

Set the spatialDataLayer parameter to the (one-based) layer index number of the spatial data pool layerthat 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 ofthis 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 Mapdisturbance:


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.