Copyright © 2006 Christian Balkenius
This is the tentative specification for Ikaros Control Files that controls the execution of Ikaros processes. The new file types introduces several new constructs that are useful for building more complex models with Ikaros.
This document is the May 23, 2006 tentative specification of the IKC file format.
This file format is planned to be used by Ikaros version 0.8.3.
Earlier versions of Ikaros have used am XML file with a flat structure using the three elements network, modules, and connections. This specification describes a new file format which includes support for hierachical models, different forms of encapsulation and the use of groups to define classes in external files. In addition, the new file format also defines processing instructions that can be used to control the execution of Ikaros.
One great advantage of the file format is that it can support graphical editors where models can be built interactively. In this case, additional graphical data is added to the different elements. Such extensionas are not documented here however.
Another new feature is that IKC files can be used both as a class description for a particular module and to document the features of a module.
In the simplest case, an Ikaros control file can look like this:
<?xml version="1.0" ?>
<group>
<module
class="Thalamus"
name="MyThalamus"
/>
<module
class="Cortex"
name="MyCortex"
/>
<connection
sourcemodule="MyThalamus"
source="OUTPUT"
targetmodule="MyCortex"
target="INPUT"
/>
</group>
Note that the group element has replaed the older network elements as the main element in the file. In addition, the elements modules and connections have been removed.
An Ikaros control file has the file extension "ikc". The main advantage of not using xml is that the file can more easily be connected to the Ikaros executable to allow double-clickable files.
The file format is compatible with the XML format with some restrictions. An IKC file is always a legal XML file.
The file should start with an xml declaration.
<?xml version="1.0" >
No DOCTYPE is allowed. The reason for this is that the attributes and elements that are supported by the file format is extended every time a new module is added to Ikaros. It would be impractical to rewrite the dtd in each case. Instead, Ikaros takes a looser approach and ignores attributes that it does not recognize.
Element and attribute names must be in ASCII.
Mixed content is not allowed. This restriction makes it possible to produce much better error messages.
All whitespace is ignored.
An ikaros control file uses the namespace http://www.ikaros-project.org/2006/ikc.
To explicitly set this namespace use the following in the outer group element
<group xmlns = "http://www.ikaros-project.org/2006/ikc">
The namespace declaration is ignored by Ikaros but allows Ikaros code to be embedded in other XML code.
An IKC file may include processing instructions starting with "ikaros". For example, the web user interface is started at the specified port with
<?ikaros web="8000" ?>
To also start the web browser automatically it is possible to write
<?ikaros web="8000" browser="Firefox" ?>
This makes it potentially possible to start ikaros with a particular file by double clicking on it.
The following turns threads on were possible:
<?ikaros threads="yes" ?>
The following executes Ikaros in real-time mode with the specified time base:
<?ikaros timebase="100" ?>
The following prints out profiling information after execution:
<?ikaros profile="yes" ?>
The following sets the print level to verbose:
<?ikaros printlevel="verbose" ?>
The following runs Ikaros in test mode. This will build the model descibes in the IKC file and report any error, but will note execute the model:
<?ikaros test="yes" ?>
Other processing instructions are allowed but ignored. More may be defined in the future.
It is planned that the command line options for Ikaros will coincide with the processing instructions in the future.
Standard XML comments are allowed and retained.
The document element must be <group>. Ikaros recognizes the following elements within a group: <input>, <output>, <parameter>, <module>, <connection>, and <views>. These elements are allowed in any order but are recommended to be declared in the above order. Other elements are allowed but ignored.
The attribute description is used to add a textual description to the group.
The attribute author names the author of the group.
As an alternative to the description attribute, it is possible to instead use the <description> element in a group to include a HTML description of the group. Such a description should use <h2> and below for headings as <h1> is reserved for the title of the page. In a similar way the element <example> can be used to give an example, in HTML, of the use of the group when it is considered as a class description.
Other documentation attributes will probably be described in the future.
The module element specifies that a particular Ikaros module should be included in the group. The module element must contain a class attribute. The module can (and mostly need to) include a name attribute which makes it possible to refer to the module. The module element may include other attributes, the meaning of which depends on the particular module. Attributes that are not recognized by the module are allowed but ignored. The attribute description is used to add a textual description to the module.
Ikaros will search for a class implemention in the following way. If class = "ABC" is specified:
See section 9 for a further discussion of these features as a means of defining classes.
The connection element must have four attributes: sourcemodule, source, targetmodule, taget. The attribute description is used to add a textual description to the connection.
The input elemement defined an input to a group. It assigns an external name to an input of one of the modules in the group. For example,
<input name="A" targetmodule="M" target="X" />
sets connects the input A of the group the input X of module M. If the target attribute is omitted its value defaults to the value of the name attribute. If the targetmodule attribute is omitted, the input refers to the first module in the group. The attribute description is used to add a textual description to the input.
The output element defines an output from a group. It assigns an external name to an output from one of the mdoules in a group. For example,
<output name="B" sourcemodule="M" source="Y" />
sets connects the output Y of module M in the group to its output named B. If the source attribute is omitted, it defaults to the value of the name attribute. If the sourcemodule attribute is omitted, the output refers to the first module in the group. The attribute description is used to add a textual description to the output.
The parameter attribute defines a parameter for the group which is used by one or several modules in the group.
To make a parameter with a particular name visible outside the group use:
<parameter name="alpha" />
To make a parameter of only a particular module M visible use
<parameter name="alpha" targetmodule="M" />
To rename the parameter use the following
<parameter name="beta" target="alpha" targetmodule="M" />
If the attribute name is not specified, its value defaults to the value of the attribute internal.
In addition, a parameter element may include a number of attributes that documents the allowed values of the parameter. These atributes are:
Conceptually, parameters are similar to inputs except that they are used at start-up and not during execution.
The view element is only used by the WebUI and is not documented here.
If an attribute is not found in an attribute, it will be searched for in the enclosing group. If the attribute is renamed using a parameter element in the group, an attribute with the new name will be searched for instead.
The attribute description is not inherited.
<group alpha="7"> <module name="A" ... /> <module name="B" ... /> </group>
is equivalent to
<group> <module name="A" alpha="7" ... /> <module name="B" alpha="7" ... /> </group>
<group alpha="7"> <parameter name="alpha" target="beta" /> <module name="A" ... /> <module name="B" ... /> </group>
If module A and/or B have attributes called beta they will get the value of alpha, that is, 7. This is thus equivalent to
<group> <module name="A" beta="7" ... /> <module name="B" beta="7" ... /> </group>
This method can also be used to set multiple attributes of different modules to the same value,
<group alpha="7"> <parameter name="alpha" module="A" target="beta" /> <parameter name="alpha" module="B" target="gamma" /> <module name="A" ... /> <module name="B" ... /> </group>
is equivalent to
<group> <module name="A" beta="7" ... /> <module name="B" gamma="7" ... /> </group>
When using many modules, it can be useful to build groups that themselves function as modules.
<group name="G" alpha="7"> <parameter name="alpha" /> <output name="OUTPUT" sourcemodule="M" source="X"> <module name="M" ... /> </group> <module name="N" ... /> <connection sourcemodule="G" source="OUTPUT" targetmodule="N" target="INPUT" />
Is equivalent to
<module name="M" ... /> <module name="N" ... /> <connection sourcemodule="M" source="X" targetmodule="N" target="INPUT" />
A group in an external file can be treated as a class.
File G.ikc
<group> <parameter name="alpha" /> <module ... /> </group>
File H.ikc
<module class="G" ... />
This will load the group in G.ikc and treat it as a module of class G.
Each module in ikaros, whether it is a standard module or user module, can have a class file which is used to document the features of the module. Such a file can also be used by the GUI and to generate documentation for a class.
Example file "ADD.ikc"
<group name="ADD" description="This module adds two inputs."> <input name="INPUT1" description="The first input." /> <input name="INPUT2" description="The second input." /> <output name="OUTPUT" description="The output." /> <parameter name="scale" description="How to scale the sum." default="1" /> <module class="ADD"> </group>
This file is places in the Ikaros class directory, or the user class directory, and will be searched when a module names ADD is used in a an other IKC file. Using the search path described in section 6.2.1 it becomes possible for IKC files to act as class declarations.
Another possibility is to build new classes from already existing modules by defining an IKC file with a group of modules that are internally interconnected.
An advantageof this file fomrat is that a group that is first defined within a model can easily be saved to its own file and be used later as a class.
Extensible Markup Language (XML) 1.0 (Third Edition) W3C Recommendation 4th February 2004, François Yergeau, Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler
Namespaces in XML W3C Recommendation 14 January 1999, Tim Bray, Dave Hollander, Andrew Layman