Copyright © 2006-2007 Christian Balkenius
This is the fincal 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 June 1, 2007 specification of the IKC file format.
The major part of this file format is recognized by Ikaros version 1.0. Some parts of the specification are not yet implemented and they are marked in the description.
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 replaced 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 except within the description element (See section 9). 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/2007/ikc.
To explicitly set this namespace use the following in the outer group element
<group xmlns = "http://www.ikaros-project.org/2007/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" ?>
All processing instructions are ignored by Ikaros 1.0.
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 by the Ikaros kernel and can be used for documentation (See section 9).
The attribute description is used to add a textual description to the group. This description should be all lowercase and as short as possible.
The attribute title is used to set a title for the group. This title may be displayed in a viewer.
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" />
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.
If the name of the input is given as "*", it indicates that any input name can be added to the module. This is useful when the number of inputs depends on other parameters and can not be specified when the module is written. This mechanism should be avoided in most cases.
If targetmodule and target are both set to the empty string "", which is not a legal name, the input will act as a placeholder. Any connection made to such an input will be ignored.
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.
If the name of the output is given as "*", it indicates that any output name can be added to the module. This is useful when the number of outputs depends on other parameters and can not be specified when the module is written. This mechanism should be avoided in most cases.
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.
In Ikaros 1.0, <view> elemnents do not inherit attributes from the ecnclosing elements.
<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, should have an IKC file which is used to document the features of the module. Such a file is used in three ways:
Example file "ADD.ikc"
<group name="ADD" description="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 another 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 advantage of this file format 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.
To further document a module, a number of elements have been defined that can be included in the top level group element.
The group element may contain at most one description element. The description element contains a description of the function of the module in plain text or as XHTML. A description element can have a type attribute that sets the type of description. The two possible values are text and xhtml. When no type is specified, plain text is assumed.
Example of a plain text description:
<description type="text"> This module calculates the sum of its two inputs. </description>
Example of an xhtml description:
<description type="xhtml">
<p>
This <b>module</b> calculates the <i>sum</i> of its two inputs.
</p>
</description>
Note that the enclosing <p> element is necessary to make the description valid xhtml.
The group element may contain several example elements that gives examples of how the module can be used. The intention of the example element is to show typical parameter settings for a module. Examples can also be used as templates that can be directly copied into an IKC file.
The example element may contain a descrition attribute that describes the example.
The example element must contain a single module element. The attributes and elements of this module element must be consistent with the parameter elements in the file. For example:
<example description="A simple example">
<module
class="Thalamus"
name="MyThalamus"
/>
</example>
The group element may contain one or several limitation elements. The limtation element contains a text description of a limitation of the module.
The group element may contain one or several bug elements. The bug element contains a text description of a bug in the current version of the module.
The group element may contain one or more change elements. The content is a text description of some change to the module. The change attribute has two required attributes. The who attribute specifies who did the change. The date attribute specifies when the change was done in the format YYYY-MM-DD.
<change date="2007-03-21" who="Jane Doe"> A new and interesting bug was introduced. </author>
The group element can contain one <:files> elements. This element, in tutrn, an contain one or several <file> elements. The file element specifices the file name of one file related to this modules such as the .h and .cc file.
<files> <files>ADD.h</file> <files>ADD.cc</file> <files>ADD.ikc</file> </files>
The group element can contain one or more author elements. It is recomended that each file contains at least one author element. The author element can contain the four elements name, email, affiliation and homepage. For example:
<author> <author>Jane Doe</author> <email>jane.doe@ikaros-project.org</email> <affiliation>The Ikaros Project</affiliation> <homepage>http://www.ikaros-project.org</homepage> </author>
Christian Balkenius, Jan Moren & Birger Johansson. (2007). System-level cognitive modeling with Ikaros. Lund University Cognitive Studies, 133. [PDF].
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