All elements

This page summarizes all the element types currently supported by the proof-of-concept LEMS interpreter. The explanations are somewhat cursory so it is probably better to look at the examples to work out what is going on.

There is one block for each element type. All element names are in fixed width bold. Attribute names are in normal fixed width. Each block shows the attributes supported by an element and then the types of children allowed.

Model structure

Models can be spread over multiple files. The root element in each file is Lems.

Lems

Root element for any lems content
Can contain:
Dimension
Constant
Unit
Assertion
ComponentType
Component
Target

Target

A lems file can contain many component definitions. A Target elements specifies that a components should be treated as the entry point for simulation or other processing
component (String)
Reference to the entry point component  
reportFile (String)
Optional attribute specifying file in which to save short report of simulation  
timesFile (String)
Optional attribute specifying file in which to save times used in simulation  

Constant

A constant quantity: like a parameter for which the value is supplied in the class definition itself rather than when a component is defined.
name (String)
A readable name for the constant.  
symbol (String)
The symbol used in expressions to refer to this constant.  
value (String)
The value of a constant must be a plain number (no units) giving the SI magnitude of the quantity or an expression involving only plain numbers or other constants.  
dimension (String)
 

Include

file   (string)
the name or relative path of a file to be included
Files are included where the Include declaration occurs. The enclosing Lems block is stripped off and the rest of the content included as is.

Units and dimensions

Dimension

A Dimenson element associated a name with a particular combination of the standards SI base dimensions, mass, lenght, time, current, temperature and amount if substance (moles). Fractional dimensions are not currently supported.
name (String)
The name to be used when referring to this dimension from variable declaration or units  
m (int)
Mass  
l (int)
Length  
t (int)
Time  
i (int)
Current  
k (int)
Temperature  
n (int)
Amount of substance  
j (int)
Luminous intensity  

Unit

A Unit asociates a symbol with a dimension and a power of ten. For non-metric units a scale can be provided, as in '1 inch = 0.0254 m'. In this case there is a degeneracy between the power and the scale which is best resolved by not using the two together. The offset parameter is available for units which are not zero-offset, such as farenheit.
name (String)
As with constants, units are only referred to within expressions using their symbols, so the name is just for readability.  
symbol (String)
The symbol is used to refer to this unit inside compound expressions coutaining a number and a unit symbol. Such expressions can only occur on the right hand side of assignments statements.  
dimension (String)
Reference to the dimension for this unit  
power (int)
Power of ten  
scale (double)
Scale, only to be used for scales which are not powers of ten  
offset (double)
Offset for non zero-offset units  

Assertion

Assertions are not strictly part of the model, but can be included in a file as a consistency check.
dimension (String)
The name of a dimension  
matches (String)
An expression involving dimensions. The dimensionality of the expression should match the dimensionality of the dimension reference.  

Defining ComponentTypes

Component

id (String)
 
name (String)
Name by which the component was declared - this shouldn't be accessible.  
declaredType (String)
Name by which the component was declared - this shouldn't be accessible.  
type (String)
 
eXtends (String)
 
Can contain:
Insertion
Component
About
Meta

ComponentType

Root element for defining LEMS Component Types.
name (String)
The name of the component type. This can be uses as an XML element name in the shorthand form whendefining components.  
eXtends (String)
The component type that this type inherits field definitions for, if any  
Can contain:
Parameter
IndexParameter
DerivedParameter
PathParameter
Requirement
ComponentRequirement
InstanceRequirement
Exposure
Child
Children
Link
ComponentReference
ComponentTypeReference
Location
Property
Dynamics
Structure
Simulation
Equilibrium
Procedure
Geometry
Fixed
Constant
Attachments
EventPort
Path
Text
Collection
PairCollection
About
Meta

Parameter

A quantity, defined by name and dimension, that must be supplied when a Component of the enclosing ComponentType is defined
name (String)
The name of the parameter. This is the name of the attribute to be used when the parameter is supplied in a component definition  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the parameter  

PathParameter

A parameter of which the value is a path expression. When a ComponentType declares a PathParameter, a corresponding Component definition should have an attibute with that name whose value is a path expression that evaluates within the instance tree of the built model. This is used, for example, in the definition of a group component class, where the coresponding component specifies a path over the instance tree which selectesthe items that should go in the group.
name (String)
Name of the parameter  

Property

An property on an instance of a component. Unlike a Parameter, a Property can very from instance to instance. It should be set with an Assign element within the build specification.
name (String)
 
dimension (String)
 
defaultValue (String)
The defaultValue for the property must be a plain number (no units) giving the SI magnitude of the quantity.  

DerivedParameter

A parameter that is a function of the Component's Parameters, which does not change with time. Its value can be supplied either with the 'value' attribute that evaluates within the scope of the definition, or with the 'select' attribute which gives a path to 'primary' version of the parameter. For example, setting select='//MembranePotential[species=channel/species]/reversal' within the appropriate context allows a channel's reversal potential to taken from a single global setting according to its permeant ion, rather than explicitly supplied locally.
name (String)
The name of the derived parameter  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the derived parameter  
select (String)
Path to the parameter that supplies the value. Exactly one of 'select' and 'value' is required.  
value (String)
A string defining the value of the element  

Fixed

Fixes the value of a parameter in the parent class, so that it does not have to be supplied separately in component definitions.
parameter (String)
 
value (String)
 

Requirement

A Requirement gives the name and dimension of a quantity (parameter or variable) that should be accessible within the scope of a model component. This is only applicable for elements that can be included as children of other elements, where the scope comprises its own parameters and those in the scope of its enclosing element. Once a requirement has been declared, then the quantity can be used within the Dynamics definition of the component. It is the responsibility of an implementation to check that the component is only used in a context in which the requirement is met. A typical example is in defining membrand bound components which require access to the membrane potential but where the variable that holds the potential itself is defined in the top level component.
name (String)
name  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the requirement  

ComponentRequirement

The name of a component or component reference that must exist in the component hierarchy
name (String)
name  

InstanceRequirement

An instance that must be supplied at build time. Expressions can contain references to quantities in the instance
name (String)
name  

Exposure

A quantity that is made available to other components in the simulation. Note that all variables in a Dynamics definition are private. If other components need access to them, then the definition should explicitly link them to an exposure defined in the component class
name (String)
Name of the exposure element  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the element  

Child

Specifies that a component can have a child of a particular type. The name supplied here can be used in path expressions to access the component. This is useful, for example, where a component can have multiple children of the same type but with different roles, such as the forward and reverse transition rates in a channel.
name (String)
Name of the child  
type (String)
Reference to a component class, the value should be the name of the target class.  
description (String)
An optional description of the child  

Children

Specifies that a component can have children of a particular class. The class may refer to an extendedtype, in which case components of any class that extends the specified target class should be valid as child components
name (String)
Name of the children  
type (String)
The class of component allowed as children.  

Link

Like a ComponentRef, but resolved relative to the enclosing object so the target must already be in the model. One or the other should be deprecated. The Link element has the same properties as ComponentRef. The Link element just establishes a connection with the target component, but leaves it in its existing place in the hierarchy. Variables in the target component can be accessed via the name of the link element.
name (String)
A name for the ComponentReference  
type (String)
The type of the target Component  
description (String)
An optional description of the ComponentReference  

ComponentReference

A reference to another component. The target component can be accessed with path expressions in the same way as a child component, but can be defined independently
name (String)
A name for the ComponentReference  
type (String)
The type of the target Component  
description (String)
An optional description of the ComponentReference  

ComponentTypeReference

This is used in conjunction with PathParameter elements to specify the target class of selections defined within components operating over the instance tree.
name (String)
 

Collection

Specifies that instances of components based on this class can containe a named collection of other instances. This provides for containers for oprating on groups of instances with path and filter expressions defined in components to operate over the instance tree.
name (String)
 

PairCollection

Defines a named collection of paris of instances, similar to the Collection element.
name (String)
 

EventPort

A port on a component that can send or receive events, depending on the direction specified
name (String)
Name of the EventPort  
direction (String)
'IN' or 'OUT'  
description (String)
An optional description of the EventPort  

Text

Holds textual information that does not change the model but is needed for other purposes such as labelling graphs.
name (String)
The textual content  
description (String)
An optional description of the element  

Path

Duplicates some functionality of PathParameter - the two should be merged.
name (String)
 

Attachments

Specifies that a component can accept attached components of a particular class. Attached components can be added at build time dependent on other events. For scoping and access purposes they are like child components. The cannonical use of attachments is in adding synapses to a cell when a network connection is made.
name (String)
A name for the Attachments  
type (String)
The type of the Attachments  

Insertion

IntegerParameter

name (String)
The name of the parameter. This is the name of the attribute to be used when the parameter is supplied in a component definition  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the parameter  

IndexParameter

name (String)
The name of the parameter. This is the name of the attribute to be used when the parameter is supplied in a component definition  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the parameter  

About

Meta

Meta element to provide arbitrary metadata to LEMS simulations. Note that this is not processed by the LEMS interpreter.

Dynamics

Dynamics

Specifies the dynamical behavior of components build from this ComponentType. Note that all variables in a Dynamics definition are private. If other components need access to them, then the definition should explicitly link them to an Exposure defined in the component class
Can contain:
Super
DerivedVariable
ConditionalDerivedVariable
StateVariable
TimeDerivative
KineticScheme
OnStart
OnEvent
OnCondition
StateScalarField
DerivedScalarField
DerivedPunctateField
Regime

StateVariable

Specifies a state variable that stores values that define the state of the system at a point in time. The dynamics of state variables may be defined as Ordinary Differential Equations (ODEs) using the TimeDerivative entity. They can also be discontinuously modified using elements in Dynamics such as OnStarts, OnEvents, and OnConditions. StateVariables may be linked to exposures.
name (String)
Name of the state variable  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
exposure (String)
If this variable is to be accessed from outside, it should be linked to an Exposure that is defined in the ComponentType.  
description (String)
An optional description of the state variable  

StateAssignment

Has 'variable' and 'value' fields
variable (String)
The name of the variable  
value (String)
A string defining the value of the element  

TimeDerivative

First order differential equations, functions of StateVariables and Parameters, for how StateVariables change with time. Has a variable and a value. The value is the rate of change of the variable.
variable (String)
The name of the variable  
value (String)
A string defining the value of the element  

DerivedVariable

A quantity that depends algebraically on other quantities in the model. The 'value' field can be set to a mathematical expression, or the 'select' field to a path expression. If the path expression produces multiple matches, then the 'reduce' field says how these are reduced to a single value by taking the sum or product.
name (String)
Name of the derived variable  
select (String)
A path to the variable that supplies the value. Note that to select a variable from another component, the variable must be marked as an Exposure. Exactly one of 'select' and 'value' is required  
dimension (String)
The dimension, or 'none'. This should be the name of an already defined dimension element  
description (String)
An optional description of the derived variable  
reduce (String)
Either 'add' or 'multiply'. This applies if ther are multiple matches to the path or if 'required' is false. In the latter case, for multiply mode, multiplicative expressions in this variable behave as if the term was absent. Additive expressions generate an error. Conversely, if set to 'add' then additive expressions behave as if it was not there and multiplicative ones generateand error.  
exposure (String)
 
required (boolean)
Set to true if it OK for this variable to be absent. See 'reduce' for what happens in this case  
value (String)
A string defining the value of the element  

OnStart

Can contain:
StateAssignment
EventOut
Transition

OnCondition

Can contain:
StateAssignment
EventOut
Transition

OnEvent

Event handler block
port (String)
the port to listen on  
Can contain:
StateAssignment
EventOut
Transition

EventOut

KineticScheme

Allows the specification of systems that can be in one of a small number of states at any time with probabilistic transitions between states. This includes continuous time Markov processes as are used for stochastic models of ion channels. A kinetic scheme does not itself introduce any new elements or state variables. It is rather a way of connecting quantities in existing components by saying that quantities in the edge elements should be interpreted as transition rates among quantities in the node elements.
name (String)
Name of kinetic scheme  
nodes (String)
Source of notes for scheme  
edges (String)
The element that provides the transitions for the scheme  
stateVariable (String)
Name of state variable in state elements  
edgeSource (String)
The name of the attribute in the rate element that defines the source of the transition  
edgeTarget (String)
Attribute tha defines the target  
forwardRate (String)
Name of forward rate exposure  
reverseRate (String)
Name of reverse rate exposure  

Regime

Allows the dynamics of a ComponentType to be expressed via a finite state machine. Each regime has its internal dynamics, and conditions on which transitions between regimes occur are specified using the OnCondition element
name (String)
The name of the regime  
initial (String)
'True' if this is the initial regime of the system  
Can contain:
DerivedVariable
StateVariable
TimeDerivative
OnStart
OnEntry
OnEvent
OnCondition
RequiredVar

OnEntry

Can contain:
StateAssignment
EventOut
Transition

Transition

Super

ConditionalDerivedVariable

name (String)
 
dimension (String)
 
exposure (String)
 
Can contain:
Case

Case

value (String)
A string defining the value of the element  

Equilibrium

Can contain:
DerivedVariable

StateScalarField

DerivedScalarField

DerivedPunctateField

Structure

Structure

By default, each Component in a model gives rise to a single instance of its state variables when the model is executed. The state variables are then governed by the dynamics definition in the associated ComponentType. Elements in the Structure declaration can be used to change this behavior, for example to make multiple instances of the state variables, or to instantiate a different component. A typical application for the latter would be a Component that defines a population of cells. The population Component might define the number of cells it contains but would refer to a Component defined elsewhere for the actual cell model to use.
Can contain:
BuildElement

MultiInstantiate

Can contain:
Assign
BuildElement

CoInstantiate

Can contain:
Assign
BuildElement

Assign

Choose

Can contain:
BuildElement

ChildInstance

Can contain:
Assign
BuildElement

ForEach

Can contain:
BuildElement

EventConnection

Can contain:
Assign
BuildElement

Tunnel

Can contain:
Assign
BuildElement

PairsEventConnection

Can contain:
BuildElement

PairFilter

Can contain:
BuildElement

IncludePair

Can contain:
BuildElement

With

Can contain:
BuildElement

If

Can contain:
BuildElement

Apply

Can contain:
BuildElement

Gather

Can contain:
BuildElement

GatherPairs

Can contain:
BuildElement

Simulation

Simulation

Can contain:
Record
EventRecord
Run
DataDisplay
DataWriter
EventWriter
Meta

Record

quantity (String)
path to the parameter that will contain the path to the quantity to be recorded  
scale (String)
path to the element that defines the scale for rendering the quantity dimensionless  
color (String)
hex format color suggestion for how the data should be displayed  

EventRecord

quantity (String)
path for the component which will emit spikes to be recorded  
eventPort (String)
event port for the component which will emit spikes  

DataDisplay

DataWriter

EventWriter

Run

The run element provides a way to make a model runnable. It should point to the parameters that set the step size etc. The target parameters have to be dimensionally consistent.
component (String)
name of the component reference that will set the component to be run  
variable (String)
 
increment (String)
path to the parameter that sets the step size  
total (String)
path to the parameter that sets the total span of the independent variable to be run  

Procedure

Procedure

Can contain:
Statement

Equilibrate

ForEachComponent

Can contain:
Statement

Print

Defining Components

Component

id (String)
 
name (String)
Name by which the component was declared - this shouldn't be accessible.  
declaredType (String)
Name by which the component was declared - this shouldn't be accessible.  
type (String)
 
eXtends (String)
 
Can contain:
Insertion
Component
About
Meta