Canonical form

The present proposal is not a canonical form for a model. Rather, it is a concise human accessible format that is intended to have a 1-1 mapping to some canonical form. The reason for defining the human accessible one first is that it is easier to work with. As long as the mapping is easily applied and lossless, then there is little reason ever to look at models expressed in the canonical form. Indeed, provided it is genuineley lossless, then it doesn't much matter which form of a model is treated as the primary version, although it seems more likely that other tools will support the canonical form than the human readable one.

Turning a model specification into its canonical form involves:

Parsing expressions and writing out MathML
Converting quantities to their SI values and putting the original units in metadata elements (the canonical form has dimensions but no units)
Using the "Component type='xyz'" format for model elements

The interpreter should be able to do this at some stage, but it doesn't yet. Ideally, the conversion should be implemented in XSL too since that is probably the simplest dependency for other systems to swallow. An XSL mapping to a canonical form would also provide a working reference as to what that form actually is until, and possibly even after, the documentation caught up.

Other XML formats

As well as the canonical form for a minimally redundant model specification, there are two other XML formats that could usefully be generated:

The expanded version of a model where component references are dereferenced. This is the version over which specification level paths operate.
The instantiated version of a model, where every state variable appears in the XML. This is the tree over which run-time paths operate.

In general, of course, the second of these will never be generated, but it is useful to be able to construct it for particular models when writing paths for their behaviors. These two trees can be generated with ... (not yet).

Partial example - model from example1 in XML canonical form

The following is by no means complete (only some of the sub-element types for type definitions and components are included) but it gives an indication of what the canonical format could look like.

ex1canonical.xml (xml)

<Lems>
   <Dimension>
      <name>voltage
      </name>
      <mass>1
      </mass>
      <length>2
      </length>
      <time>-3
      </time>
      <current>-1
      </current>
   </Dimension>
   <Dimension>
      <name>time
      </name>
      <time>1
      </time>
   </Dimension>
   <Dimension>
      <name>per_time
      </name>
      <time>-1
      </time>
   </Dimension>
   <Dimension>
      <name>conductance
      </name>
      <mass>-1
      </mass>
      <length>-2
      </length>
      <time>3
      </time>
      <current>2
      </current>
   </Dimension>
   <Dimension>
      <name>capacitance
      </name>
      <mass>-1
      </mass>
      <length>-2
      </length>
      <time>4
      </time>
      <current>2
      </current>
   </Dimension>
   <Dimension>
      <name>current
      </name>
      <current>1
      </current>
   </Dimension>
   <Dimension>
      <name>none
      </name>
   </Dimension>

   <Type>
      <name>iaf1
      </name>
      <Parameter>
         <name>threshold
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <Parameter>
         <name>refractoryPeriod
         </name>
         <dimension>time
         </dimension>
      </Parameter>
      <Parameter>
         <name>capacitance
         </name>
         <dimension>capacitance
         </dimension>
      </Parameter>
   </Type>

   <Type>
      <name>iaf2
      </name>
      <extends>iaf1
      </extends>
   </Type>

   <Type>
      <name>iaf3
      </name>
      <extends>iaf1
      </extends>
      <Parameter>
         <name>leakConductance
         </name>
         <dimension>conductance
         </dimension>
      </Parameter>
      <Parameter>
         <name>leakReversal
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <Parameter>
         <name>deltaV
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <EventPort>
         <name>spikes-in
         </name>
         <direction>in
         </direction>
      </EventPort>
   </Type>

   <Type>
      <name>spikeGenerator
      </name>
      <Parameter>
         <name>period
         </name>
         <dimension>time
         </dimension>
      </Parameter>
      <EventPort>
         <name>a
         </name>
         <direction>out
         </direction>
      </EventPort>
   </Type>

   <Type>
      <name>spikeGenerator2
      </name>
      <extends>spikeGenerator
      </extends>
      <EventPort>
         <name>a
         </name>
         <direction>out
         </direction>
      </EventPort>
   </Type>

   <Type>
      <name>HHRate
      </name>
      <Parameter>
         <name>rate
         </name>
         <dimension>per_time
         </dimension>
      </Parameter>
      <Parameter>
         <name>midpoint
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <Parameter>
         <name>scale
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
   </Type>

   <Type>
      <name>HHExpRate
      </name>
      <extends>HHRate
      </extends>
   </Type>

   <Type>
      <name>HHSigmoidRate
      </name>
      <extends>HHRate
      </extends>
   </Type>

   <Type>
      <name>HHExpLinearRate
      </name>
      <extends>HHRate
      </extends>
   </Type>

   <Type>
      <name>HHGate0
      </name>
      <Parameter>
         <name>power
         </name>
         <dimension>none
         </dimension>
      </Parameter>
      <Child>
         <name>Forward
         </name>
         <type>HHRate
         </type>
      </Child>
      <Child>
         <name>Reverse
         </name>
         <type>HHRate
         </type>
      </Child>
   </Type>

   <Type>
      <name>HHGate
      </name>
      <Parameter>
         <name>power
         </name>
         <dimension>none
         </dimension>
      </Parameter>
      <Child>
         <name>Forward
         </name>
         <type>HHRate
         </type>
      </Child>
      <Child>
         <name>Reverse
         </name>
         <type>HHRate
         </type>
      </Child>
   </Type>

   <Type>
      <name>HHChannel
      </name>
      <Parameter>
         <name>conductance
         </name>
         <dimension>conductance
         </dimension>
      </Parameter>
      <Children>
         <name>gates
         </name>
         <type>HHGate
         </type>
      </Children>
   </Type>

   <Type>
      <name>ChannelPopulation
      </name>
      <Parameter>
         <name>number
         </name>
         <dimension>none
         </dimension>
      </Parameter>
      <Parameter>
         <name>erev
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <ComponentRef>
         <name>channel
         </name>
         <type>HHChannel
         </type>
      </ComponentRef>
   </Type>

   <Type>
      <name>HHCell
      </name>
      <Parameter>
         <name>capacitance
         </name>
         <dimension>capacitance
         </dimension>
      </Parameter>
      <Parameter>
         <name>injection
         </name>
         <dimension>current
         </dimension>
      </Parameter>
      <Parameter>
         <name>v0
         </name>
         <dimension>voltage
         </dimension>
      </Parameter>
      <Children>
         <name>populations
         </name>
         <type>ChannelPopulation
         </type>
      </Children>
   </Type>

   <Component>
      <id>celltype_a
      </id>
      <type>iaf1
      </type>
      <value parameter="threshold">-0.03
      </value>
      <value parameter="refractoryPeriod">0.0020
      </value>
      <value parameter="capacitance">3.0E-6
      </value>
   </Component>

   <Component>
      <id>ctb
      </id>
      <type>iaf1
      </type>
      <value parameter="threshold">-0.03
      </value>
      <value parameter="refractoryPeriod">0.0020
      </value>
      <value parameter="capacitance">1.0E-6
      </value>
   </Component>

   <Component>
      <id>na
      </id>
      <type>HHChannel
      </type>
      <value parameter="conductance">2.0E-11
      </value>

      <Component>
         <id>m
         </id>
         <type>HHGate
         </type>
         <value parameter="power">3.0
         </value>

         <Component>
            <id>null
            </id>
            <type>HHExpLinearRate
            </type>
            <value parameter="rate">1000.0
            </value>
            <value parameter="midpoint">-0.04
            </value>
            <value parameter="scale">0.01
            </value>
         </Component>

         <Component>
            <id>null
            </id>
            <type>HHExpRate
            </type>
            <value parameter="rate">4000.0
            </value>
            <value parameter="midpoint">-0.065
            </value>
            <value parameter="scale">-0.018000000000000002
            </value>
         </Component>
      </Component>

      <Component>
         <id>h
         </id>
         <type>HHGate
         </type>
         <value parameter="power">1.0
         </value>

         <Component>
            <id>null
            </id>
            <type>HHExpRate
            </type>
            <value parameter="rate">70.0
            </value>
            <value parameter="midpoint">-0.065
            </value>
            <value parameter="scale">-0.02
            </value>
         </Component>

         <Component>
            <id>null
            </id>
            <type>HHSigmoidRate
            </type>
            <value parameter="rate">1000.0
            </value>
            <value parameter="midpoint">-0.035
            </value>
            <value parameter="scale">0.01
            </value>
         </Component>
      </Component>
   </Component>

   <Component>
      <id>k
      </id>
      <type>HHChannel
      </type>
      <value parameter="conductance">2.0E-11
      </value>

      <Component>
         <id>n
         </id>
         <type>HHGate
         </type>
         <value parameter="power">4.0
         </value>

         <Component>
            <id>null
            </id>
            <type>HHExpLinearRate
            </type>
            <value parameter="rate">100.0
            </value>
            <value parameter="midpoint">-0.055
            </value>
            <value parameter="scale">0.01
            </value>
         </Component>

         <Component>
            <id>null
            </id>
            <type>HHExpRate
            </type>
            <value parameter="rate">125.0
            </value>
            <value parameter="midpoint">-0.065
            </value>
            <value parameter="scale">-0.08
            </value>
         </Component>
      </Component>
   </Component>

   <Component>
      <id>hhcell_1
      </id>
      <type>HHCell
      </type>
      <value parameter="capacitance">1.0E-12
      </value>
      <value parameter="injection">4.0E-12
      </value>
      <value parameter="v0">-0.06
      </value>

      <Component>
         <id>null
         </id>
         <type>ChannelPopulation
         </type>
         <value parameter="number">6000.0
         </value>
         <value parameter="erev">0.05
         </value>
      </Component>

      <Component>
         <id>null
         </id>
         <type>ChannelPopulation
         </type>
         <value parameter="number">1800.0
         </value>
         <value parameter="erev">-0.077
         </value>
      </Component>
   </Component>

   <Component>
      <id>celltype_c
      </id>
      <type>iaf3
      </type>
      <value parameter="leakConductance">3.0E-12
      </value>
      <value parameter="leakReversal">-0.05
      </value>
      <value parameter="deltaV">0.0050
      </value>
      <value parameter="threshold">0.045
      </value>
      <value parameter="refractoryPeriod">0.0030
      </value>
      <value parameter="capacitance">1.0E-6
      </value>
   </Component>

   <Component>
      <id>celltype_d
      </id>
      <extends>celltype_c
      </extends>
      <value parameter="leakConductance">5.0E-12
      </value>
      <value parameter="leakReversal">-0.05
      </value>
      <value parameter="deltaV">0.0050
      </value>
      <value parameter="threshold">0.045
      </value>
      <value parameter="refractoryPeriod">0.0030
      </value>
      <value parameter="capacitance">1.0E-6
      </value>
   </Component>

   <Component>
      <id>gen1
      </id>
      <type>spikeGenerator
      </type>
      <value parameter="period">0.03
      </value>
   </Component>

   <Component>
      <id>gen2
      </id>
      <type>spikeGenerator2
      </type>
      <value parameter="period">0.032
      </value>
   </Component>

   <Component>
      <id>iaf3cpt
      </id>
      <type>iaf3
      </type>
      <value parameter="leakConductance">5.0E-11
      </value>
      <value parameter="leakReversal">-0.05
      </value>
      <value parameter="deltaV">0.05
      </value>
      <value parameter="threshold">-0.03
      </value>
      <value parameter="refractoryPeriod">0.0040
      </value>
      <value parameter="capacitance">1.0E-12
      </value>
   </Component>
</Lems>