The operation model document contains the definitions for the forestry operation models used in the simulation. It serves two purposes: as a documentation for the models, and as “glue” between the simulator and the model libraries (Operation model library).
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:
<operation_modelbase xmlns="http://www.simo-project.org/simo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.simo-project.org/simo
../schemas/operation_modelbase.xsd">
The models are divided into named operation groups, each group containing several model definitions:
…
<operation_group name="thinning">
<operation>
The model definition begins with the name of the model, which must match the name of the model in the model library. In case the type of the model is model (see below for alternatives), the model library name and implementation language are given. The cash flow handler may either be the model itself, the simulator or none. In the model-case the model itself returns the prediction of the cash flow associated with the operation. In case of simulator the simulator get’s the cash flow prediction from a cash flow table (Cash flow), and if the cash flow handler is set to none there won’t be any cash flow results stored for the operation model. If interaction is set “on”, the model can modify the simulation data objects at different levels; i.e., the thinning model removes trees from the simulation. To put it in other words, if interaction is “off”, only operation results are processed (not cashflows, simulation effects etc.):
…
<name>low_thinning</name>
<type>
<model>
<implemented_at>SimoOperations.py</implemented_at>
<implemented_in>python</implemented_in>
<cash_flow_handler>model</cash_flow_handler>
<interaction>on</interaction>
</model>
</type>
Metadata about the operation models consists of the verbal description of the model:
…
<description>Basic implementation of a thinning model. Removes
diameter classes systematically starting from the
smallest diameter class.
</description>
Next up is the definition about the data that is passed to the operation model. For each data level a group is defined which contains the level name and the level attributes collected for each object on the data level:
…
<data>
<group>
<level>comp_unit</level>
<variables>
<variable>
<name>Remainlimit_upper</name>
</variable>
<variable>
<name>Remainlimit_lower</name>
</variable>
</variables>
</group>
<group>
<level>stratum</level>
<variables>
<variable>…</variable>
</variables>
</group>
<group>
<level>tree</level>
<variables>…</variables>
</group>
</data>
Another operation model input data category is parameters. The parameter values are set in the model chain documents (Model chain); i.e., they do not get their values from the simulation data:
…
<parameters>
<parameter>
<name>target_density</name>
</parameter>
<parameter>
<name>track_width</name>
</parameter>
…
</parameters>
Operation models can also get parameter tables as input data. Parameter tables are defined in model interface like this:
…
<parameter_tables>
<parameter_table>thinning_preference_order</parameter_table>
<parameter_table>log_reduction</parameter_table>
</parameter_tables>
A weight to be applied to the operation results can also be defined; i.e., it’s the multiplier for the result attribute values:
…
<operation_result_weight>
<name>AREA</name>
<level>comp_unit</level>
</operation_result_weight>
The operation model results are either operation results (operation_result) or data attribute values (data, see below). The operation results can have classifier values associated with then; e.g., the harvested volume classified by the species and the timber assortment. The classifier values can be taken either from data (variable name, data level) of from the cash flow tables used for the operation model (cashflow_classifier):
…
<results>
<type>
<operation_result/>
</type>
<variables>
<variable>
<name>Volume</name>
<classifiers>
<classifier>
<variable>SP</variable>
<level>stratum</level>
</classifier>
<classifier>
<cashflow_classifier>
<variable>assortment</variable>
</cashflow_classifier>
</classifier>
</classifiers>
</variable>
…
</variables>
</results>
</operation>
</operation_group>
</operation_modelbase>
If the model type is cash_flow, the model definition is straightforward: the vital details are the model name and the optional result weight. The actual cash flow table (Cash flow) used for the model is set in the model chain (Model chain):
…
<operation>
<name>grass_suppression</name>
<type>
<cash_flow/>
</type>
<description>Mechanical grass_suppression - heinays</description>
<operation_result_weight>
<name>AREA</name>
<level>comp_unit</level>
</operation_result_weight>
</operation>
If the model result type is data, the data level is defined for the results as well as the data attributes that the operation model returns:
…
<results>
<type>
<data>
<target>existing</target>
<level>stratum</level>
</data>
</type>
<variables>
<variable>
<name>stand_value</name>
</variable>
<variable>
<name>LOGp</name>
</variable>
<variable>
<name>COMWOOD</name>
</variable>
<variable>
<name>V_LOG</name>
</variable>
</variables>
</results>
Default result variable type is scalar, but if operation results should be distributed to different points in time, result variable type should be date_array. The result data structure constructed by the simulator will be different for scalar and date_array variables. It is the responsibility of the operation model implementation to return correctly built result data structures back to the simulator.
Below is a scalar result variable (it would be scalar also without the type attribute):
…
<variables>
<variable type="scalar">
<name>stand_value</name>
</variable>
<variables>
Below is a date_array result variable:
…
<variables>
<variable type="date_array">
<name>C_flow</name>
</variable>
<variables>