Ikaros Control Files
The execution of IKAROS is controlled by an IKC file that defines what modules to instantiate, their parameters and their connections. The experiment file starts with the standard XML tag and is followed by the main element in the file which is named <group>. This element in turn contains the two main elements types <module> and <connection>.
This document only describes the basic aspects of an Ikaros Control File. A complete specification of the file format is also available.
A typical IKC file is shown below that instantiates two modules and connects them together:
<?xml version="1.0"?> <group> <module class = "InputFile" name = "IN" filename = "input.txt" /> <module class = "Integrator" name = "INT" /> <connection sourcemodule = "IN" source = "X targetmodule = "INT" target = "INPUT" /> </group>
The group element contains a list of module element that describes the modules that should be instantiated by the Ikaros kernel at start-up. In the example, the first module is of class "InputFile" and the second is of class "Integrator". The class names refer to the names of the source code files used to generate these module classes. The two modules are also given instance names, in this case "IN" and "INT". These names must be unique for the control file. The attribute "filename" is a parameter to the first modules. These parameters are specific for each module class.
Structure of the network described in the XML file above
The connection element describes a connection between the modules. In the example, there is a single connection between the module "IN" and the module "INT". The attributes "source" and "target" specifices the input and output to use for the connection.
There are several examples of experiment files in the Example folders for the individual modules.
There are two of attributes that all modules must have. These are "class" and "name". In addition, it is possible to set two additional attributes: "period" and "phase". These parameters set when and how often the module should run.
For connections, there is the additional attribute "delay" that sets how long the data on that connection should be delayed. The default is 1. It is also possible to set the delay between two modules to 0, but in this case it is necessary to make sure there are no connection loops without delay since this would mean that the input would receive its output before it is generated.
In addition to the general attributes, each module also has a number of attributes that are specific to each class of module. These attributes are read by each module at start up and are used to set parameters in each module instance. The attributes for each module can be found in the module documentation.
Describing a class
IKC-files are also used to describe the input and outputs of module and to declare the parameters used and their default values. An IKC-file of this type has the following structure:
<?xml version="1.0"?> <group> <input name = "INPUT" description = "The input to the module" /> <output name = "OUTPUT" description = "The output from the module" set_size="INPUT" /> <parameter name = "alpha" type = "float" default = "3.14" description = "The parameter alpha" /> <module class="MyModule" /> </group>
The input element describes an input called INPUT. The output element describes an output called OUTPUT. The set_size attribute tells Ikaros that the output should have exactly the same size as the input called INPUT. Other ways to set the size of an output is describes below.
The element parameter describes the name of a parameter, its type and default value. This is the value the parameter will get unless it is set otherwise in the IKC-file where the module is used.
The final module element connects this file to the compiled code for MyModule. A module statement like this can also be used to include another IKC-file to build heirarchical systems of modules, but this functionality will not be described further here.
Setting the size of an output
The size of an output can be set in several different ways. The simplest alternative is to use the attribute size to simply define the size for an array. If the output is a matrxi, the two attributes size_x and size_y are used instead. The example below would create an output matrix of size 5 x 3.
<output name = "OUTPUT" description = "The output from the module" size_x="3" size_y="5" />
If the size is to be set with a parameter one of the attributes size_param, size_param_x and size_param_y can be used instead. In this case, Ikaros seaches for the specified parameter and uses its value to set the corresponding size. In the example below, the output array would get the size 7. This functionality is most useful when the value is not sepcified in the module but instead in the group element so that several modules can use the same value.
<output name = "OUTPUT" z = "7" description = "The output from the module" size_param="z" />
Types of parameters
The parameter elements of the class description can specify a number of types. There are float, int, bool, and list. The first three types are used as in the example above, but the list parameter is a little different. It allows a number of string arguments to be specified as values and when Ikaros reads these values, they will be replaced with an integer corresponding to the position of that value in the list. Examples of all the different types of parameters are shown below.
<parameter name = "alpha" type = "float" default = "5" /> <parameter name = "beta" type = "int" default = "3" /> <parameter name = "gamma" type = "bool" default = "true" /> <parameter name = "delta" type = "list" values = "slow/medium/fast" default = "medium" />