Simulation

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>

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. 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>

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>