Ikaros Control File Specification

June 15, 2010

This version:
http://www.ikaros-project.org/2010/IKC12-20100615/
Previous version:
http://www.ikaros-project.org/2007/IKC10-20070601/
Authors:
Christian Balkenius <christian.balkenius@lucs.lu.se>
Birger Johansson <birger.johansson@lucs.lu.se>
Jan Moren

Abstract

This is the final 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.

Status of this document

This document is the June 15, 2010 specification of the IKC file format.

This file format is recognized by Ikaros version 1.2.

1 Introduction

This specification describes the file format which includes support for hierachical models, different forms of encapsulation and the use of groups to define classes in external files.

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.

IKC files can be used both as a class description for a particular module and to document the features of a module. As of version 1.2 of Ikaros, every module class must have a corresponding ikc-file that describes its features and sets its default parameters.

2 Introductory Example

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>

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.

3.1 XML Declaration

The file should start with an xml declaration.

<?xml version="1.0" ?>

3.2 No DOCTYPE

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.

3.3 Character set

Element and attribute names must be in ASCII.

3.4 No mixed content

Mixed content is not allowed except within the description element (See section 9). This restriction makes it possible to produce much better error messages.

3.5 Whitespace

All whitespace is ignored.

3.6 Namespace

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/2010/ikc">

The namespace declaration is ignored by Ikaros but allows Ikaros code to be embedded in other XML code.

4 Processing Instructions

Processing instructions are currently ignored by Ikaros.

5 Comments

Standard XML comments are allowed and retained.

6 Elements

6.1 The <group> element

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.

6.2 The <module> element

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.

6.2.1 How the class attribute is resolved

Ikaros will search for a class implemention in the following way. If class = "ABC" is specified:

  1. Search for an ABC.ikc" in same directory. If found, include its main group. Files are not search recursively. That is, if the file C.ikc refers to class="C", it is not itself searched for the definition of the class.
  2. Seach for ikc in user class directory. If found, include its main group.
  3. Seach for ikc in system class directory. If found, include its main group.
  4. Seach internal classes (actual coded modules). If found, load the required code that implements the class.

See section 9 for a further discussion of these features as a means of defining classes.

6.3 The <connection> element

The connection element must have four attributes: sourcemodule, source, targetmodule, taget. The attribute description is used to add a textual description to the connection.

In addition, a connection element can include a delay attribute that specifies that the connections should be delayed. The default delay is "1". Delays can also bes specified as lists, e. g. "1, 3, 7, 10", or as ranges, e.g. "1:5" which correponds to the list "1, 2, 3, 4, 5". Ranges and list can be mixed, e. g. "1:3, 5:7" would correpond to "1, 2, 3, 5, 6, 7". When multiple delays are specified the effect is identical to making one connection for each delay in the list between the source and the target.

For example, the following

<connection
  source="OUTPUT"
  targetmodule="T"
  target="INPUT"
  delay="1,2"
/>

Is equivalent to the following two connections

<connection
  sourcemodule="S" 
  source="OUTPUT"
  targetmodule="T"
  target="INPUT"
  delay="1"
/>

<connection
  sourcemodule="S" 
  source="OUTPUT"
  targetmodule="T"
  target="INPUT"
  delay="2"
/>

6.4 The <input> element

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.

It is legal (and often useful) to have several input elements with the same name but different targets. In this case, a single connection that is made to this input will be connected to several target modules in the group.

An optional delay attribute can be used in an input. Unlike for connections, lists of delays or ranges cannot be used. Only a single delay value is recognized.

6.5 The <output> element

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.

Starting in version 1.2, outputs may contain a number of additional attrbutes to set the size of the output. These attributes are size, size_x, size_y, size_param, size_param_x, size_param_y, size_set.

The attrbute size is used to set a fixed output size of an array output. The attributes size_x and size_y are used in the same way to set the dimensions of a matrix output.

Using the size_param attributes, the output size is set using the value of an integer parameter to the module. The alternative with size_param_x and size_param_y are used for matrix outputs.

Finally, it is possible to set the size of an output based on the size of an input. This is done using the size_set attribute. The value of the attribute should be a name of an input and the output is automatically set to the same size. It is possible to list several input names separaed by a comma to eforce that the output should have the same size as each of the inputs in the list (that all have to be the same). To only get one dimension from inputs, use size_set_x and size_set_y.

The different size parameters are used in the following order, that is, if more than one is supplied, the last one will be used: size_param, size_param_x, size_param_y, size, size_x, size_y, size_set, size_set_x, size_set_y.

6.6 The <parameter> element

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"  />

To rename the parameter from a particular module use the following

<parameter name="beta" target="alpha" targetmodule="M"  />

If the attribute name is not specified, its value defaults to the value of "*".

In addition, a parameter element may include a number of attributes that documents the allowed values of the parameter. These atributes are:

description
this attribute gives a textual description of the parameter
type
the type can be float, int, bool, or list.
min
the minimum value of the parameter
max
the default value of the parameter
default
the maximum value of the parameter
values
a list of allowed values if the parameter type is list, in the format "x/y/z".

Starting with version 1.2 parameters may be dynamically changed during execution, for example from the viewer. Modules that react to this should bind the parameters to an internatl variable using the Bind() function.

6.7 The <view> element

The view element is only used by the WebUI and is not documented here.

7 Attribute Inheritance

If an attribute is not found in an element, 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.2, <view> elements do not inherit attributes from the enclosing elements.

8 Examples

8.1 Simple attribute inheritance

<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>

8.2 Using parameter elements to set several module parameters to the same value

<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>

8.3 Using groups for encapsulation

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" />

8.4 Using groups as classes

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.

9. Module Documentation

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.

9.1 The <description> 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.

9.2 The <example> element

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>

9.3 The <limitation> element

The group element may contain one or several limitation elements. The limtation element contains a text description of a limitation of the module.

9.4 The <bug> element

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.

9.5 The <change> element

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>

9.6 The <files> element

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>

9.7 The <author> element

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>
  <name>Jane Doe</name>
  <email>jane.doe@ikaros-project.org</email>
  <affiliation>The Ikaros Project</affiliation>
  <homepage>http://www.ikaros-project.org</homepage>
</author>

References

Balkenius, C., Morén, J., Johansson, B and Johnsson, M. (2010). Ikaros: Building Cognitive Models for Robots. Advanced Engineering Informatics, 24, 1, 40-48. [doi: 10.1016/j.aei.2009.08.003]

Christian Balkenius, Jan Moren & Birger Johansson. (2007). System-level cognitive modeling with Ikaros. Lund University Cognitive Studies, 133..

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