This document describes the XML model description format currently implemented by the XML parser for describing models. This format is incomplete and likely to change - but suffices for building models and testing the concepts.
The Big Idea behind the XML model description format is that anyone anywhere can take the XML model file, any replicate a given simulation run without having to manually reinstall software. This should work at any level, from parameter searches, network models, single cell models and channel models. Currently the Neosim parser deals with network models, where projection schemes, individual entities can be given by neosim Modules.
Although the XML files should be readable by humans, it is intended that they would be used primarily as an interchange format - modellers should not have to type XML tags by hand. Currently they do, until front ends are developed.
<header>
The values have to be put between the tags, for
example :
<author> My Name </author>
The links on the tags explain their use.
This section gives the name of the network to be built
by Neosim.
There can be as many network tags as you want, but each network
named here has to be defined by the define-network tag of the
prototypes section.
See the tags' links for more explanations.
<define-entity name=" " modulename=" " xmlfile=" "/>
Where :
The description of the entity's characteristics (neuron cell's and
behaviour description) is not actually included in the
XML file, but loaded from a linked module file. That module file
is a library (.jar or .lib) of Java or C++ code, whose location
is to be given in the <module> tag
of the <experiment> section.
See the <module> tag explanation for more
details.
Example :
<prototypes>
<define-entity
name="neuron" modulename="libNeuron"
xmlfile="neuron.xml"/>
</prototypes>
The definition of populations and projections of a network are made
inside the <define-network> tag :
<define-network name=" " >
{define one or many populations here}
{define one or many projections here}
</define-network>
Where :
<population name=""
entityname=" " type=" " num="
" xdim=" " ydim=" "
zdim=" " xorig=" " yorig=" "
zorig=" " xdelta=" " ydelta=" "
zdelta=" "/>
Where :
The population defined can be of two types (future development will
allow custom populations) which are "standard" and
"Grid3D".
The populations are connected by projections of different kinds,
depending on the choice of the type of population.
Examples :
// set a standard population of 10 neurons
// set a Grid3D population of 3by3by2 neurons, origin's coordinates 0 0
0, with a distance(delta) of 1 between the neurons. That type of population can
be used for 1D and 2D populations as well.
<projection name="" srcPop=""
dstPop="" type="" { + custom
parameters... } >
{defines connections here}
</projection>
Where :
<connection src=" "
scrPort="out1" dst=" " dstPort="in1"
delay="" { +entity specific parameters...} />
Where :
There will be as many <connection> tags as there are
connections in a standard projection.
Example of use inside a
<projection> tag:
<projection name="toOthers" srcPop="neuronpop" dstPop="neuronpop" type="standard" >
An example is available : a projection between two 3D grids,
each cell of the source grid connected to the cells belonging to a spherical area of
the destination grid.
The corresponding XML tag will be :
<projection name=" " srcPop=" " dstPop=" "
type="jar" jarfile="
" radius=" " autoconnect=" " boundmethod=" "> Where :
In order to use a custom projection module, the location of its code module should be defined in the
<experiment> section using the
<module> tag.
Example of use inside a
<projection> tag:
<projection name="Sphere" srcPop="pop3D1" dstPop="pop3D2"
type="jar" jarfile="ProjSphere" radius="1" autoconnect="true" boundmethod="mirror">
<connection scrPort="out1" dstPort="in1" delay="2" xrange="1" yrange="1" zrange="1" />
</projection>
With the module defined in the <experiment> section as :
<module
name="ProjSphere" location="file:/home/examples/projections/Proj3DSphere.jar" version="1.0"
/>
Here is an example of an entire network specification
Where name refers to the identifier of a network as defined
by the <define-network> tag of the
<prototypes> section.
<module name=" " location=" "
version="" />
Where :
In order to extend the possibilities of the XML description, some
XML tags allow the definition of a linked library of code (Java or
C++). These libraries (.jar or .lib) can be user-defined (see "How to
write a new Neosim module" ) and can provide custom
descriptions of entities, projections or simulation controls.
Example :
<experiment>
<control> ... </control>
<time value="" />
Where
value : is the value of the simulation time in seconds.
The custom control module allows to define specific behaviour and
monitoring in a code library (see "How to
write a new Neosim module"). The corresponding module
has to be defined in the <experiment> section using the <module>
tag. In the <control> section the
tag which links to that module is :
<controlmodule name="" {+ custom parameters}/>
Where
name : refers to a name defined by a <module> tag.
Examples of a standard simulation control :
With :
<module
name="controlMod" location="file:/home/examples/controls/control.jar" version="1.0"
/>
The structure of the XML File
The XML model description format is made of four sections :
The order of the sections must be respected.
The XML file looks like :
...
</header>
<prototypes>
...
</prototypes>
<model>
...
</model>
<experiment>
...
</experiment>
Header section
The Header section refers to information about the file, the
simulations, as author name, file version, ...
Its tags are :
<header>
<author> value </author>
<email> value </email>
<date> value </date>
<version> value </version>
<documentation> value </documentation>
<references> value </references>
<units> value </units>
</header>
Prototypes section
The Prototypes section describes the different components of a model :
entities, projections and networks.
Its tags are :
<prototypes>
<define-entity name="" modulename="" xmlfile=""/>
...
<define-network name ="">>
<population name="" entityname="" num="" />
...
<projection name="" srcPop="" dstPop="" type="" {+additional parameters...} >
<connection src="" scrPort="" dst="" dstPort="" delay="" {+additional parameters...} />
...
/<projection>
...
</define-network>
</prototypes>
Model section
The Model section specifies which networks described in the prototypes
section are used in the simulation.
Its tags are :
<model>
<network name ="" />
...
</model>
Experiment section
The Experiment section gives the parameters of the simulation run, like
the run time of the simulation, and the precise location of the module files.
Its tags are :
<experiment>
<module name="" location="" />
...
<control>
<time value="" />
{or }<controlmodule name="controlMod" />
</control>
</experiment>
How to describe a Neosim model using XML tags
A model can be seen as a set of networks of populations of entities. Those elements of a model are defined as prototypes used in the model. Building model is first describing the prototypes, in the following order :
Define the entities
In the <prototypes> section, with the XML tag :
An entity is the basic element of the simulation, which sends and/or
receives events from the other entities. It could be a model of a neuron
for example, or a visualisation or statistics gathering user interface tool.
The <define-entity> tag defines prototypes entities
which can then be used in the specification of a population.
Define the network
A network is composed of populations and of projections.
The populations are sets of entities, and the projections are sets of
connections between the entities of two populations.
Define the Population
In the <prototypes> section, inside the <define-network>
tag using the XML tag :
Define the Projection
In the <prototypes> section, inside the <define-network>
tag using the XML tag :
Define a Standard Projection
The standard projection (type = "standard") is a set of connections , in which each connection
between two entities of the populations has to be described
explicitly, using the <connection> tag :
<connection src="0" scrPort="out1" dst="1" dstPort="in1"
delay="2" weight="2" />
<connection src="1" scrPort="out1" dst="2" dstPort="in1"
delay="3" weight="2" />
<connection src="2" scrPort="out1" dst="3" dstPort="in1"
delay="5" weight="2" />
</projection>
Define a Custom Projection
A custom projection defined in a code module(see
"How to write a new Neosim
module").
Instead of explicitly listing all the connections, such custom
projections provide methods to build the connections.
The <connection> tag is still
needed, but only once, to specify the parameters of the "generic"
connection used as a model for all the built connections.
<connection scrPort="out1" dstPort="in1" delay=" " xrange=" " yrange=" " zrange=" " />
</projection>
If "true", allows to connect an entity of the source population to
the entity of same index in the destination population.
If "false", it is not allowed. In that way autoconnections can be avoided
when the destination population is also the source population
nobound means that connections attempted to a cell out of the
dimension limit of the destination grid are ignored
continuous means that the dimensions are pretended circulars, any
connections out of a border comes to inside the opposite border.
mirror means that
Example of an XML network specification
Make instance of the Model
After the descriptions of all the prototypes needed comes the time
to use them. The tag to use is:
<model>
<network name ="" />
...
</model>
There could be as many networks named here as there are networks
defined in the <prototypes> section.
Define the Experiment parameters
This section lets you
Define a module
In the <experiment> section, defines the module with the XML tag :
<module
name="libNeuron" location="file:/home/examples/simpleneuron/simpleneuron.jar" version="1.0"
/>
</experiment>
Define the simulation Control parameters
The simulation can be run with several specific parameters and
also monitored in several ways.
Those parameters are defined inside the control tag :
<control>
<time value="10" />
</control>
Examples of a custom simulation control :
<control>
<controlmodule name="controlMod" />
</control>
Example of an XML Description
<Here is an example of an entire XML Description of a Neosim simulation>