Ikaros Control File Specification

Tentative Specification May 23, 2006

Current version:
http://www.ikaros-project.org/2010/IKC12-20100615/
This version:
http://www.ikaros-project.org/2006/DRAFT-IKC10-20060523/
Author:
Christian Balkenius <christian.balkenius@lucs.lu.se>

Abstract

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.

Status of this document

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.

1 Introduction

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.

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>

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.

3 Fundamentals

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

4 Processing Instructions

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.

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.

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.

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.

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

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.

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.

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

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
list
a list of allowed values if the parameter type is list, in the format "x/y/z".

Conceptually, parameters are similar to inputs except that they are used at start-up and not during execution.

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

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. Classes, Modules and Groups

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.

References

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