Understanding XML files format

Document's Structure

The document is composed by two kinds of tags: reserved tags and property tags. The reserved tags includes the root node <nnfw>, the <neuralnet> node and tags for creating a neural network. These tags, contained by <neuralnet> node, can be divided into three groups as follow:
Architecture tags <cluster> & <linker>
they declare the basic element of neuralnetwork and how they are interconnected
Neural Newtork tags <inputs>, <outputs> & <order>
they declare which Cluster are inputs and outputs of the neural network and how act the udpating step method
Configure tags <configure> <randomize>
The first one allows to configure the object created above. The configuration can also be done directly inside the Architecture tags, but with <configure> you can separate the configuration from the declaration of architecture. The second simply randomize the object's parameters.
A Property tag represents an object's property, where the tag name is the property name and the tag content is the value which the object's property will be setted.

A document where the property tags are not showed will appear as follow: 

<nnfw version="1.1">
  <neuralnet>
    <cluster name="aName" type="aType" numNeurons="dim"> ... </cluster>
    <cluster name="aName" type="aType" numNeurons="dim"> ... </cluster>
    ...
    <cluster name="aName" type="aType" numNeurons="dim"> ... </cluster>

    <linker name="aName" type="atype" from="aClusterName" to="aClusterName"> ... </linker>
    <linker name="aName" type="atype" from="aClusterName" to="aClusterName"> ... </linker>
    ...
    <linker name="aName" type="atype" from="aClusterName" to="aClusterName"> ... </linker>

    <inputs> aClusterName1 aClusterName2 ... </inputs>
    <outputs> aClusterName3 aClusterName4 ... </outputs>
    <order> aClusterName1 aClusterName2 ... </order>

    <configure name="someName"> ... </configure>
    <configure name="someName"> ... </configure>
    ...
    <configure name="someName"> ... </configure>
  </neuralnet>
</nnfw>

Important Warning
Spaces are not allowed in all attribute values. For instance, "a funny name" is not allowed for the attribute name. But instead, substitute white spaces with other characters, e.g. "a_funny_name" or even better use only alphanumeric chars, "aFunnyName".

Setting a Property

Inside the tags <cluster>, <linker> and <configure> a lot of property tags can be annidated for configuring all aspect of Clusters and Linkers.

The common structure of all property tags is: 

<propertyName type="aTypeName"> ... </propertyName>
where propertyName is the name of object's property and the attribute type is optional but it plays an important role explained below.

Property tags can exists only annidated in <cluster>, <linker> and <configure> tags, because they need an object which refers to. A property tag outside tags listed above arises an unrecognized tag error.

Let's start with an example, suppose to have a cluster and we want to set the accumulate property to 'true', we will write: 

  <configure name="clusterName">
     <accumulate> true </accumulate>
  </configure>
With the tag <configure> we specify which object we want to configure, and the tag <accumulate> tell to the xml parser to set the accumulate property of the cluster to 'true'.

Now, suppose that the cluster is configured with a SigmoidFunction with lambda 1.0 as output function, and we want to change lambda to 0.5, we will write: 

  <configure name="clusterName">
     <outfunction>
       <lambda> 0.5 </lambda>
     </outfunction>
  </configure>
In this situation, lambda is a property of the outfunction cluster's property, and it's possible to set it by simply annidating <lambda> property tag into <outfunction>. There's no limit to property tags annidation.

But now, suppose we want to change the SigmoidFunction with a new different function (e.g. LinearFunction) and configure the new one. In this situation the attribute type is important; in fact, with this attribute you specify the new type to create and substitute to the old one. That's the code: 

  <configure name="clusterName">
     <outfunction type="LinearFunction">
        <minX> -20.0 </minX>
        <maxX> +20.0 </maxX>
        <minY> -1.0 </minY>
        <maxY> +1.0 </maxY>
     </outfunction>
  </configure>
In this way, the outfunction cluster's property is configured to be a LinearFunction. As soon after creation, the LinearFunction is setted accordlying to annidated property tags: minX, maxX, minY and maxY.

Special Case: Vector properties

Vector properties are handled via special attribute 'i' for configuring the value stored. At the moment there is only one class that have a Vector property: the PoolFunction. Suppose to have a Cluster with a PoolFunction and want to configure the 3rd function of a PoolFunction, that's the code: 
  <configure name="clusterName">
     <outfunction>
       <functions i="2">
          <lambda> 0.5 </lambda>
       </functions>
     </outfunction>
  </configure>
The tag <outfunction> access to the PoolFunction of cluster, and the functions property is a Vector and it's possibile to change the 3rd element with the attribute i. Note, that i is egual to TWO. Because the indexing of Vector properties starts from zero (like C-array), so 0 means the first element, 1 the 2nd and 2 the 3rd.

If you want to substitute the 4th function with a new one, then you need the attribute type too. That's the code: 

  <configure name="clusterName">
     <outfunction>
       <functions i="3" type="ScaledSigmoidFunction">
          <lambda> 0.5 </lambda>
          <min> -1.0 </min>
          <max> +1.0 </max>
       </functions>
     </outfunction>
  </configure>
[Up]

Setting the Architecture

The topology of neural network is specified by <cluster> and <linker> tags. The latter defines how the cluster are interconnected among them and how the information is transferred through the interconnections; i.e. Linkers. The former specifies which kind of neuron's layers are present into the neural network that is being constructed.

Declaring a Cluster
The tag <cluster> has three mandatory attribute: All property of the Cluster's type can be setted by annidated tags. (Setting a Property) 
  <cluster name="hidden" type="BiasedCluster" numNeurons="6">
    <accumulate> True </accumulate>
    <outfunction type="ScaledSigmoidFunction">
      <lambda> 0.5 </lambda>
    </outfunction>
    <biases> -1.2 2.4 0.5 -0.6 1.1 0.9 </biases>
  </cluster>
Declaring a Linker
The tag <linker> has four mandatory attribute: All property of the Linker's type can be setted by annidated tags. (Setting a Property) 
  <linker name="matrix1" type="MatrixLinker" from="input" to="output">
    <randomize min="-1.0" max="+1.0" />
  </linker>
See Configure tags for randomize explanation.

Neural Network Parameters

Neural network parameters

Configure tags

<configure> has only one mandatory attribute, name, that indicates the identification name of the Cluster or Linker to be configurated by <configure> tag. Once opened this tag, all object's properties can be configurated putting all needed property tags inside <configure>. See Setting a Property for examples.

Annidated to <configure>, <cluster> and <linker> tags can be placed a special reserved tag: <randomize>. It take two mandatory attribute 'min' and 'max' that specifies the range of random number generator. The randomize tag will sets all object's parameters that is being configurated to random values within range [min,max].

Tip-off
Compiling NNFW with GSL enabled allow to get more truly random number generation.
[Up]
BerliOS Developer Logo Valid XHTML 1.0 Transitional Valid CSS!