EDL Runner (`edlrun`)

Introduction

EDL Runner (edlrun) is a program that runs experiments built in software, i.e. computer simulations. Its main purpose is to make working with Experiment Description Language (EDL) easier. edlrun achieves this by defining a standard way of handling input and output parameters to an experiment. As long as an experiment developer sticks to this standard, edlrun will handle reading input parameters from, and writing output parameters to, EDL documents. The experiment developer need not know anything about EDL (or even XML), yet is able to process EDL documents using edlrun.

For experiment developers that do know how to handle EDL (and XML) documents, edlrun is still a useful utility. It handles the EDL/XML part, leaving only the experiment part to the developer. Concentrating the handling of EDL/XML into a single utility means that not every simulation needs XML handling capabilities, resulting in smaller programs. It also means there is only a single utility that needs to be changed whenever EDL evolves.

Using an EDL document to perform an experiment

When an EDL document is available, calling edlrun with the name of the EDL document as a parameter on the command-line will cause edlrun to perform the experiment that is described in the EDL document. Wildcards (*, ?) are supported in filenames, so calling edlrun *.edl will perform the experiments described in all the EDL documents in the current directory. edlrun's ability to perform experiments depends on a standard way of dealing with input and output parameters.

Input parameters

As stated before, edlrun presents the input parameters to the simulation program in a standard format. It does so by providing each input parameter on the command-line, using the following syntax: -i<name>[(<index>)]=<value><unit>. The part between [] is optional, and is used to specify indexed values.

For example, a "simulation program" called calcArea that calculates the area of a rectangle would expect two input parameters: width and height. When fed an EDL document containing the following input fragment:

<input>
  <inputItem id="I1" name="width" unit="m" value="3"/>
  <inputItem id="I2" name="height" unit="dm" value="40"/>
</input>

edlrun will issue the following call: calcArea -iwidth=3m -iheight=40dm.

And when fed an EDL document containing the following input fragment:

<input>
  <inputRangeItem id="I1" name="size" unit="m">
    <inputRangeItem index="0" value="3"/>
    <inputRangeItem index="1" value="4"/>
  </inputRange>
</input>

edlrun will issue the following call: calcArea -isize(0)=3m -isize(1)=4m.

Output parameters

edlrun expects the output parameters of the experiment to be written to a result file. This allows both console programs and GUI ones to be used as simulation programs. The name of the result file should be the same as that of the simulation program, but with the .out extension, e.g. calcArea.out. Each output parameter should be written on a separate line in this file, using the following format: <name>[(<index>)]=<value><unit>. The part between [] is optional, and is used to specify indexed values.

For example, when the calcArea program creates the following calcArea.out result file:

area=12m

edlrun will update the EDL document with the following output fragment:

<output>
  <outputItem id="O1" name="area" unit="m" value="12"/>
</output>

And when a simulation program creates the following result file:

temperature(0)=273K
temperature(1)=283K