The optimization document defines objective function used in optimization task.
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:
<optimization_task xmlns="http://latitude.mmvar.helsinki.fi/simo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.simo-project.org/simo
../schemas/optimization_task.xsd">
An example of objective function:
The initial date is either a specific date or “today” and the time step applied will be yearly; i.e., later in the objective function definition the period 1 will refer to dates from 1.1.2007 to 31.12.2007 and the period 2 to dates from 1.1.2008 to 31.12.2008. Thus, it should be noted that the period definitions used in simulation are distinct from the period definitions in the optimization task definition. Let’s say that the initial date for simulation is 1.1.2007 and it consists of periods 1 year + 1 year + 1 year + 3 years + 3 years. In that case the simulation period 5 covers dates between 1.1.2011 and 31.12.2013, whereas the period 5 in optimization covers the dates between 1.1.2011 and 31.12.2011 and the period 6 the dates between 1.1.2012 and 31.12.2012 etc.
The data filter <data_filter> is an optional element for targeting only a subset of the whole data in the optimization. The syntax of the data filter is similar to constraint conditions, or to model chain condition and only units that pass the filter will be included in the optimization.
The discount rate is given as a percentage; i.e. 3.5 % as 3.5:
…
<initial_date>2007-01-01</initial_date>
<period_step>year</period_step>
<data_filter>comp_unit:SC eq 3</data_filter>
<discount_rate>3.5</discount_rate>
<objective_function>
If the optimization requires varying discount rates, for example for different geographical regions in the data, conditional discount rates can be defined:
…
<initial_date>2007-01-01</initial_date>
<period_step>year</period_step>
<discount_rate>3.5</discount_rate>
<conditional_discount>
<rate>
<condition>comp_unit:SC le 2</condition>
<value>4.0</value>
</rate>
<rate>
<condition>comp_unit:SC gt 4</condition>
<value>2.0</value>
</rate>
</conditional_discount>
<objective_function>
Here maximization with the additive function in global scope is used; i.e., the sub objective values are added together in search for a global maximum value. Should the scope be local, the maximum value for each simulation unit would be searched for:
…
<type>
<function>additive</function>
<target>max</target>
<scope>global</scope>
</type>
The objective is to maximize the Income during all periods. In sum[1:-1](operation:Income:discount), 1 indicates the first period and -1 the last period. ‘operation’ in ‘operation:Income’ indicates that the Income variable is an operation result variable. ‘:discount’ indicates that the values of the ‘operation:Income’ variable will be discounted with the discount rate defined above. If there are several sub objectives, they can be given different weights (<weight>):
…
<sub_objectives>
<sub_objective>
<weight>1.0</weight>
<expression>sum[1:-1](operation:Income:discount)</expression>
<utility_function>
<type>linear</type>
</utility_function>
</sub_objective>
</sub_objectives>
The constraint that the objective function must satisfy is that the discounted ‘Income’ is greater during the last ten years period than during the first ten years period:
…
<constraints>
<constraint>
sum[11:20](operation:Income:discount) gt
sum[1:10](operation:Income:discount)
</constraint>
…
</constraints>
</objective_function>
</optimization_task>
The variables in subobjective and constraint expressions can be conditional. Optional conditions for variables are defined after the variable definition. In the following example, the ‘[operation:SP eq 1 and operation:assortment eq pulp]’ defines that only the volume of pine (operation:SP eq 1) pulp wood is taken into account. The classifiers and the classifier values (e.g. assortment having values ‘log’ and ‘pulp’) for operation results are defined in the cash flow tables used for each operation:
…
<constraint>
sum[1:-1](operation:Volume[operation:SP eq 1 and operation:assortment eq pulp])
</constraint>
Operation results can be conditional also to operation name and operation group, as in the two following constraints:
…
<constraint>
sum[1:-1](operation:Volume[operation:op_name eq thinning]) gt 10500
</constraint>
<constraint>
sum[1:-1](operation:Volume[operation:op_group eq
final_harvest_artificial_regeneration]) gt 2000
</constraint>
Data values can also be conditional, as in the following example. In it only the volume of those units from the comp_unit data level that have the MAIN_GROUP attribute value of 4 or greater are added together. In the example the V variable is defined to contain the volume per hectare and therefore the V value is multiplied by the area:
…
<constraint>
sum[-1:-1](comp_unit:AREA * comp_unit:V[comp_unit:MAIN_GROUP ge 4]) ge 10000
</constraint>
NOTE: When using JLP optimization tools, the format for the constraints is rather limited. JLP constraints should: _not_ have division operators (‘/’), have a numerical value on the “right hand” side. A valid JLP constraint would be for example:
…
<constraint>
sum[6:10](operation:cash_flow:discount) - sum[1:5](operation:cash_flow:discount) gt 0
</constraint>
The objective function type can be ‘additive’, ‘conjunctive’ or ‘distance’, and the value of the objective function is either maximized (<target>max</target>) or minimized (<target>min</target>). For additive objective function the sub objective values are added together, for conjunctive they are multiplied with each other. The distance based objective function aims to maximize or minimize the distance to the optimal level given for each sub objective:
<objective_function>
<type>
<function>distance</function>
<target>max</target>
<scope>global</scope>
</type>
<sub_objectives>
<sub_objective>
<weight>1.0</weight>
<expression>sum[1:-1](operation:Income:discount)</expression>
<utility_function>
<type>linear</type>
</utility_function>
<optimal_level>100000</optimal_level>
</sub_objective>
</sub_objectives>
The utility function type given for each sub objective can be only linear. Optionally, a midpoint can be defined for the linear utility function defining a turning point for the piecewise linear function:
<utility_function>
<type>linear</type>
<midpoint>
<x>0.5</x>
<y>0.8</y>
</midpoint>
</utility_function>
The midpoint x and y coordinates are defined in the [0..1] range, if no midpoint is given, the utility function grows linearly from 0 to 1. Defining a midpoint for the linear utility function affects how fast or slow the utility value increases as the utility variable value increases. If no midpoint is given, the utility value increases with the same ratio as the utility variable value. If the utility function is concave (y > x), utility value increases faster than the utility variable value on the left side of the midpoint (< x) and slower on the right side (> x). If the utility function is convex (x > y), utility value increases slower than the utility variable value on the left side of the midpoint (< x) and faster on the right side (> x).
The expression begins with one of the aggregators ‘sum’, ‘mean’, ‘min’ or ‘max’and is followed by the time frame for the aggregation inside square brackets in the form of start period:end period; e.g. sum[1:2]:
sum[1:2]
1 indicates the first period, and -1 is reserved for the last period. After the aggregator and period definition, the variable for the expression is given inside parenthesis in the form of data level name:variable name:
sum[1:2](stratum:BA)
In addition to the attribute data (data levels and attributes defined in the Lexicon), the data values can also come from the operation results. After the operation variable definition an optional discounting definition follows:
sum[1:2](operation:Income:discount)
The operation result names are defined in the operation model xml definitions (Operation model)
Conditions for each data variable can also be defined giving the condition after the variable definition in square brackets:
sum[1:2](operation:Income[operation:SP eq 1]:discount)
NOTE! Operation result conditions can be both operation results, or from simulated data. For simulated data, the conditions can be only from simulated, and the same data level. Here’s two examples from which the first one is valid and the second one invalid.
Valid:
sum[1:2](operation:Income[operation:SP eq 1 and comp_unit:SC eq 3])
Invalid:
sum[1:2](comp_unit:V[operation:SP eq 1 and comp_unit:SC eq 3])
The latter one will cause an error when the simulator is built.
See above for different alternatives for the conditions. The allowed operators for conditions are ‘gt’, ‘ge’, ‘eq’, ‘ue’, ‘le’, ‘lt’ and ‘in’. For the ‘in’-operator the allowed values are given as a list after the operator:
sum[1:2](comp_unit:V[comp_unit:MAIN_SP in (3, 4, 5, 6, 7, 9)])
Several conditions can be given by connecting them with the operators ‘and’ and ‘or’:
sum[1:2](comp_unit:V[comp_unit:MAIN_SP in (3, 4, 5, 6, 7, 9) and DEVEL_CLASS eq 1])
The aggregation can also contain several variables combined with the operators ‘+’, ‘-‘, ‘*’ and ‘/’:
sum[1:2](comp_unit:V * comp_unit:AREA)
Several aggregations can be combined in an expression using the operators ‘+’, ‘-‘, ‘*’ and ‘/’:
sum[1:2](comp_unit:V[comp_unit:SP eq 1] * comp_unit:AREA) /
sum[1:2][comp_unit:V * comp_unit:AREA)
Naturally, also constants can be used instead of aggregations:
sum[1:2](comp_unit:V[comp_unit:SP eq 1] * comp_unit:AREA) - 10000
The for constraints the expression is finalized by defining the comparison operator, which is one of ‘gt’, ‘ge’, ‘eq’, ‘ue’, ‘le’ and ‘lt’:
sum[1:2](comp_unit:V * comp_unit:AREA) - 10000 gt 0
Splitting stands in JLP (LP relaxation) can cause constraint violations when SIMO selects the branches with max weights. In this case, SIMO can fall back back to heuristic optimizer that finds a real integer solution that conforms to the constraints.
For each constraint, user can define the maximum violation as an absolute value or percentage. The syntax for this is:
<constraint max_violation="10" violation_metric="percentage">sum[1:5](operation:Volume) lt 5000.0</constraint>
To activate these limits on constraint violations, .ini file needs to set optimization.jlp.do_fallback as True
It is a good idea to set the ‘keep_opt_data’ and ‘reuse_opt_data’ as true, as that will decrease the optimization times for big data sets considerably.