The simulation XML document is used to drive the simulation. It contains the simulation span definitions, the model chains (Model chain) used in each span, and optionally the alternative stopping logic for the simulation. In addition to those parameter values and initial attribute values are set using the simulation document.
An example of the document contents is given below, for a comprehensive description of all the possible content options see the schema document. Data continuation and abbreviated content expressed as …:
The root level tag contains a reference to the schema document which is used to validate the content of the XML document:
<simulation xmlns="http://www.simo-project.org/simo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.simo-project.org/simo
../xml/schemas/simulation.xsd" desc="forest plan">
The definition begins by fixing the simulation data level; i.e., object at the given <main_level> form the simulation units for the simulation. The data levels are defined in the lexicon (Lexicon). There are a few built-in attributes: ‘time_step’ and ‘year’, which are based on time_span definitions and are automatically updated by the simulator. Attribute ‘time_step’ is on simulation-level and ‘year’ on simulation main-level:
…
<main_level>comp_unit</main_level>
<built_in_attributes>
<time_step>time_step</time_step>
<year>year</year>
</built_in_attributes>
The control part defines the start and end of the growth season end date (here 1st june and 1st August each year). If the data date for a simulation unit is past that date during the first simulation year, simulation chains are not executed for the unit. There can be several spans for a simulation. Each has its own time definition: time step for simulation chains (time_step) and forestry operations (operation_step) and how many time steps the span consists of (steps):
…
<control>
<growth_season_start_date>--06-01</growth_season_start_date>
<growth_season_end_date>--08-01</growth_season_end_date>
<span>
<time>
<time_step>2</time_step>
<operation_step>2</operation_step>
<time_unit>year</time_unit>
<steps>1</steps>
</time>
NB! the <time_unit> (year or month) must match the time dependent attribute handling in your modelchains, e.g. if you’re assuming in the modelchain that the age of the trees is updated with years, you shouldn’t use month-based spans in the simulation control.
Some of the data in a simulation is interesting, but some of it is not. Thus, not all data need to be stored in the result database. The saving of data is controlled with ‘<save_steps_to_db>’ element. The element can have one of three enumerated values: ‘all’, ‘none’ or ‘last’. These values refer to time steps and which time steps should be saved in the db. Value ‘all’ saves all time steps of the current time span. Value ‘none’ means that no data at all is stored from the current time span. Value ‘last’ means that only the last time step will be saved in the db from the current time span:
…
<save_steps_to_db>all</save_steps_to_db>
Note that branching_graph output does not work quite right if ‘<save_steps_to_db>’ was ‘last’ or ‘none’ in your simulations. This is because in the case of ‘last’ and ‘none’ the result database does not include date information. So, if you want to output branching graphs, make sure that ‘<save_steps_to_db>’ is set to ‘all’.
There are four different types of model chains for the span, each being optional. init_chains are executed only once at the beginning of the span. simulation_chains are executed at every step (except possibly for the first step, see above). forced_operation_chains contain the chains used to implement the predetermined forestry operations (note that these chains are automatically augmented with the chains defined in the operation mapping document (Operation mapping)). operation_chains contain the operations that the simulator will assign to the simulation units automatically in case there are no forced operations. If there are, operation_chains will not be executed. Model chain names are the XML document names, but without the xml-extension:
…
<init_chains>
<chain>Chain_complete_data</chain>
<chain>Chain_calculate_missing_attributes</chain>
<chain>Chain_generate_trees</chain>
<chain>Chain_calculate_basic_attributes</chain>
</init_chains>
<simulation_chains>
<chain>Chain_regeneration</chain>
<chain>Chain_grow_seedling_stratum</chain>
<chain>Chain_grow_little_tree</chain>
<chain>Chain_grow_big_tree</chain>
<chain>Chain_update_basic_attributes</chain>
<chain>Chain_calculate_stand_value_growth</chain>
<chain>Chain_calculate_stand_productive_value</chain>
</simulation_chains>
<forced_operation_chains>
<chain>Chain_forced_operations</chain>
</forced_operation_chains>
<operation_chains>
<chain>Chain_harvests_branching</chain>
</operation_chains>
</span>
…
</control>
Simulation can be set to stop when given conditions are met. These stopping conditions can be set with ‘<stop_logic>’ element. The syntax of the stopping conditions is the same as in model chain condition elements. Here’s an example how simulation is set to stop after the first regeneration harvest, either clearcut or seedtree position:
…
<stop_logic>
comp_unit:clearcut times_gt 0 or
comp_unit:seedtree_position times_gt 0
</stop_logic>
Initial attribute values, values set for each unit at the beginning of simulation, are set by defining the values at init_variables section. For init_variables the data level is specified in addition to the name and value of the attribute:
…
<init_variables>
<variable>
<name>passed_thinning_limit</name>
<level>comp_unit</level>
<value>0</value>
</variable>
…
</init_variables>
The last setting in the simulation document applies to the attribute values that are stored in the simulation result database. If the active-attribute for the output_constraints-element is set to “off”, every attribute from every data level is stored in the result database. Since this is usually not what is desired (there are usually a lot of attributes…), the ones wanted can be speciefied for each data level:
…
<output_constraints active="on">
<level>
<name>comp_unit</name>
<variables>
<variable>AREA</variable>
<variable>TS</variable>
…
</variables>
</level>
<level>
<name>stratum</name>
<variables>
<variable>BA</variable>
<variable>N</variable>
…
</variables>
</level>
</output_constraints>
</simulation>