Task configuration

A configuration file is used to specify the tasks to be conducted. The configuration file is written in the Extensible Markup Language (XML). Below is an example configuration for RollDice:

<Tasks>
  <name val="rolldice"/><usage val="0.9"/><nRepeats val="2000"/><checkInterval val="4"/>
  <variables class="org.leores.task.app.RollDice">    
    <nSide val="2;4;6"/>
    <nDice val="2:1:5"/>
  </variables>
  <statistics>
    <members>
      <i><info val="Fig1%pltm+@afterRept@"/>
          <valVar val="sum;#$sum$/$nDice$#"/><parVars val="nSide;nDice"/></i>
      <i><info val="Fig2%plt+@afterRept@"/><valVar val="sum"/><parVars val="nSide"/></i>
      <i><info val="Fig3%plt+@afterRept@"/><valVar val="sum"/><parVars val="nDice"/></i> 
    </members>
  </statistics>
</Tasks>

The configuration has three sections. The first section includes the values for the parameters of the framework. The example configuration entitles (name) the tasks ``rolldice'', allocates (usage) 90% CPU cores to run the tasks, sets each task to repeat (nRepeats) 2000 times, and set checkpoint files (checkInterval) to be saved very 4 tasks.

The second section is the variables block, setting up the parameters of the task. The values of each task parameter can be configured using the expressions in Table 1. In the example, the task is set to be org.leores.task.app.RollDice. The values of RollDice's two parameters are provided. nSide has 3 values: 2, 4, and 6. nDice has 4 values:2, 3, 4, and 5. There are 12=3x4 combinations of parameter values in this configuration. 12 tasks each with a different combination of parameter values will be conducted in parallel. Checkpoint files will be saved when the 4th, 8th, and 12th task starts.

Table 1. Value expressions.

Expression	Usage	Example
Enumerated values	value1;value2;...	1;2;3;4 = [1, 2, 3, 4]
Repeated values	value@times	2@3 = [2, 2, 2]
Stepped values	from:step:to	1:0.5:3 = [1, 1.5, 2, 2.5, 3]
Nested expressions	Use repeated and stepped expressions within enumerated expressions	0:1:3;5@2;4;8 = [0, 1, 2, 3, 5, 5, 4, 8]
Value blocks	block1}block2}... content in each block will NOT be expanded!	0:1:3}5@2}4}8 = [0:1:3, 5@2, 4, 8]

The third section is the statistics block, describing how and when the task results are aggregated. Each statistic (result) has three parameters: info, valVar, and parVars. Parameter info includes the time point(s) relevant to the statistic. There are 6 default time points shown in Fig. 1 to decide when the statistic is collected. Each time point ends with ``@''. The 6 default built-in time points for result collection are: 1) beforeTask: before the start of a task, 2) beforeRept: before starting a repeated run of a task, 3) beforeStep: before starting a step in a run, 4) afterStep: after finishing a step in a run, 5) afterRept: after finishing a repeated run of a task, 6) afterTask: after finishing a task.

Fig. 1. Default method flow and time points for a task.

There are some optional special time points, shown in Table 2, to set additional output of the statistics.

Table 2. Special time points

Name	Description
%plt+	Output the statistic as Gnuplot figure script.
%pltm+	Same as %plt+ but draw multiple variables in one figure when valVar includes more than one variable.
%print+	Print the statistic on the screen.
%printm+	Same as %print but print multiple variables together when valVar includes more than one variable.

All statistics will be saved in a Comma Separated Values (CSV) file by default. Parameter valVar and parVars together decide how the results are aggregated. For example, a statistic with valVar=y and parVars=x analyse y conditioned on x. valVar and parVars can include 1) the variables of the task class (e.g. RollDice), and 2) evaluation expressions shown in Table 3.

Table 3. Evaluation expressions.

Expression	Usage
Variable	$variable$
Function	$function(parameter list)$
Calculation	#mathematical expression#
Nested	Put variable and functions in calculation. For example: #$v1$+$f1(100)$#

In the example, there are 3 statistics. They respectively analyse: 1) sum and #$sum$/$nDice$# (average outcome of a roll of a dice) conditioned on (nSide, nDice) pair after each repeat of a task; 2) sum conditioned on nSide after each repeat of a task; and 3) sum conditioned on nDice after each repeat of a task.

Appendix

The mathematical expression in Table 3 supports 1) mathematical operators +,-,*,/,%,^; 2) boolean operators ==,!=,<>,<,<=,>,>=,&&,||; and 3) functions NOT(exp), RANDOM(), MIN(e1, e2), MAX(e1, e2), ABS(exp), ROUND(exp, precision), LOG(exp), SQRT(exp), SIN(exp), COS(exp), TAN(exp), SINH(exp), COSH(exp), TANH(exp), RAD(exp), DEG(exp).