In this text, a term an “insilico model” or simply a “model” is used to specify a single model described by an entire insilicoML document, which include meta-information, definition of units, morphological data and timeseries data. A single model may be divided into several sub-models or components. Each of those components is referred to as a “module”. The user can import an insilico model from the model database into their own model building process. Once an insilico model is imported, it is treated as a module.

Many IDs will be used within an insilico model. Some of them are given by 16 byte universally unique identifier (UUID) which are unique across all insilico models. Others are given as sequential number starting from 1 which are unique within an insilico model. ID=0 sometimes has a particular meaning.

In a text, use of characters ‘<‘, ‘>’, ‘&’, and ‘“’ (double quotation) as a value of tags are not allowed. In the case that users want to use them, these characters are need to be escaped as ‘&lt;’, ‘&gt;’, ‘&amp;’ and ‘&quot;’, respectively. Otherwise they cause XML syntax error. Multi-byte characters like Japanese and Chinese characters must be written in UTF-8 code (English is preferable in any case).

insilico-model is a top-tag of the insilicoML, that specifies version and namespaces as its attributes. insilico-model has the following children; header, unit-set, edge-set, module-set, controller-set, template-set, instance-set and timeseries-set.

<is:insilico-model version="1.0">
  <is:header>
    ... 
  </is:header>
  <is:unit-set>
    ... 
  </is:unit-set>
  <is:module-set>
    ... 
  </is:module-set>
  <is:controller-set>
    ... 
  </is:controller-set>
  <is:template-set>
    ... 
  </is:template-set>
  <is:instance-set>
    ... 
  </is:instance-set>
  <is:timeseries-set>
    ... 
  </is:timeseries-set>
  <is:edge-set>
    ... 
  </is:edge-set>
</is:insilico-model>

The miscellaneous properties, not directly related to modeled physiological phenomena of the model are described in header section. This includes children tags; generator, model-name, meta-information, editor, and date.

<is:header>
    ... children tags of header ...
</is:header>

The name of the application that generated the insilicoML document.

<is:generator>ISIDE 1.0</is:generator>

This describes model name which is defined by a creator who builds this model. The format of the contents can be free-text. If there exists well-known name of the model, it is recommended to use that.

<is:model-name>Physiological model</is:model-name>

This includes name and information of the model creator in isml-creator-set, information of articles in which the model is presented or the modeled physiological phenomenon is presented in article-set among others. Specifications of isml-creator-set and article-set are described in Section III.

This describes model editor (such as insilicoIDE or ISIDE) related information. Location of modules displayed on the GUI of the model editor is described in position-set. Application type used to edit the model is specified by name attribute. If the application does not support editor tag, it may skip here.

<is:editor type="iside">

This is a set of positions of modules that have been displayed on the GUI of the model editor. A position has a module-id attribute. Each position takes freetext, such as “x=10, y=20, layer=1”. The format is defined depending on application.

<is:position-set>
  <is:position module-id="0F0E3D94-3177-C6C68E5D76B7">x=43.0 y=1243.0 layer=1</is:position>
  <is:position module-id="9A0A1EAB-5B88-E299E5CD66F3">x=43.0 y=1243.0 layer=1</is:position>
</is:position-set>

This indicates the dates when the model was created, registered, downloaded and last-modified. The format of date is defined according to W3C-DTF (http://www.w3.org/TR/NOTE-datetime) as in the following example.

<is:date>
  <is:created>2007-12-26T14:55:11+09:00</is:created>
  <is:registered>2007-12-26T14:55:11+09:00</is:registered>
  <is:downloaded>2008-2-26T14:15:11+09:00</is:downloaded>
  <is:last-modified>2008-3-11T10:15:11+09:00</is:last-modified>
</is:date>

Numerical configuration describes the information used during numerical simulation.

The random-generator has type attribute taking either built-in or external, and name attribute taking either c-rand, mersenne-twister, gfsr, xor-shift for type=”built-in”, and any function name which is developed by the model creator for type=”external”. The integration tag specify the algorithm used for numerical integration by a name attribute taking either euler or 4th-rungekutta.

The time-discretization defines the interval of time to use for discretization of time during numerical integration. The attribute unit-id specifies the unit of the time step. The attribue evolution specifies simulation time evolves or not. Children tags step gives the default time step, step-min and step-max give the maximum and minimum value of time step, respectively, for the case of variable time step algorithm for numerical integration.

The simulation-time-span defines the time span for running simulation. The time unit must be given as an attribute unit-id.

<is:numerical-configuration>
  <is:algorithm>
    <is:random-generator type="built-in" name="mersenne-twister"/>
    <is:integration name="4th-rungekutta"/>
  </is:algorithm>
  <is:time-discretization unit-id="3" evolution="true">
    <is:step>0.01</is:step>
    <is:step-min>0.001</is:step-min>
    <is:step-max>0.1</is:step-max>
  </is:time-discretization>
  <is:simulation-time-span unit-id="3">10</is:simulation-time-span>
</is:numerical-configuration>

Free text description.

All units used in the model definition must be defined in this section. The user can define any unit as combinations of the following seven base units defined in the international system of units, i.e.,

together with prefixes in the following table;

Each unit definition must have ID number which is given by sequential number to be unique in a insilico model. In the definition of units, the user can use the user-defined units by their ID as well as the above seven base units by their default (given) unit-id. Prefixes must be referred to by their symbol listed in above table. Principally a unit can be described by multiplication and segment of some of the seven base units. For this purpose the exponent of units can be specified in the definition. Besides, multiplier and offset can also be specified. For convenience, more several units are defined as default:

In ISML, unit-set is a set of units which has children name and definition. A definition must list all necessary elements as children, which specify unit-id of base seven units and user-defined units with exponent, offset, multiplier and prefix if necessary.

The unit-id must be positive integer for user defined units. unit-id=”0” is reserved as “dimensionless”. The exponent, multiplier, offset are real numbers. The prefix must be take one of name of prefixes in above table, such as ‘mega’, ‘kilo’ and ‘nano’. The unit-ids are referred in the description of insilico model, such as physical quantities.

<is:unit unit-id="12">
  <is:name>newton</is:name>
  <is:element unit-id="2"/> 
  <is:element unit-id="1"/>
  <is:element unit-id="3" exponent="-2"/>
</is:unit>
<is:unit unit-id="13">
  <is:name>micro-newton-meter</is:name>
  <is:element unit-id="12" prefix="micro"/> 
  <is:element unit-id="1"/>
</is:unit>
<is:unit unit-id="14">
  <is:name>fahrenheit</is:name>
  <is:element unit-id="5" multiplier="0.56" offset="-459.67"/>
</is:unit>

This is a set of edges. An edge describes the structural and functional relationships among modules which are main actors representing functional components making up the insilico model. A type of the edge is specified by an attribute type which takes one value among functional, structural, logical, capsular, and forwarding. An edge spans a link between two ports, which are defined in children tags, head and tail specified by module-id and port-id. Since port-id is unique within a module, and module-id is unique across insilico models, when both of them are specified, a port is uniquely identifiable. An operation specifies what effect or relationship exists between the two modules linked by the edge. The module - edge linkages can be thought to form a basis of the ontology of physiological phenomena. The information described in the operation is important to build a ontology with rich vocabulary. The detailed explanation of the edge is written in the description. Each type of the edge is explained below.

functional

A functional edge connects between an output and input ports to indicate the source and destination ports of the information flow of physical quantities. The operation must be described by the user with a word or a short phrase representing a verb or a verb phrase. For example, a functional edge linking between an output port of an ionic current module and an input port of a membrane module, the functional edge may be phrased by “depolarize” or “hyperpolarize” depending on the functional roles of the current. The tail of the edge must be an output port of a module, and the head must be an input port of a module.

structural

A structural edge represents structural relationships between modules. The operation must be specified as one of constituent, include or attachment. In the cases of structure edges, the port ID of head and tail must be 0 which means that it is a special port that is not associated to any information of physical quantities. The tail of the edge must be a child, and the head must be a parental module. Thus the edge directs from the child to the parent.

logical

A logical edge represents logical relationships between modules. This is similar to the structure but modules linked by logical edges do not have physical structure but only conceptual structure. The operation must be specified as one of constituent, include or attachment. In the cases of logical edges, the port ID of head and tail must be 0 which means that it is a special port that is not associated to any information of physical quantities. The tail of the edge must be a child, and the head must be a parental module. Thus the edge directs from the child to the parent.

capsular

A capsular edge links between a capsule module and top modules of all modules encapsulated by the capsule module. A capsular edge links two modules (the capsule module and its child module) with ports of port-id 0. The tail of the edge is the module encapsulated by the capsule module and the head must be the capsule module. Since a capsule module can encapsulate several modules simultaneously, one capsule module can have several capsular edges linking to children modules.

forwarding

A forwarding edge is used to link an input (output) port of a capsule module to an input (output) port of a module encapsulated by the capsule module. This is a kind of port forwarding which prevents direct connections to the modules under the capsule module from modules outside of the scope of the capsule module. When the edge links between input ports, the tail must be the port on the capsule module, and the head is the input port on the module under the capsule. In the case of linking output ports, the tail must be the port on the module under the capsule, and the head must be the port on the capsule module.

<is:edge-set>
<is:edge type="functional" edge-id="2AB51F54-E542-4A25-AD67-424241527691">
  <is:head module-id="D45BFBF3-39CB-4C9E-987C-01E7BD2BAE9C" port-id="2"/>
  <is:tail module-id="FA14B54B-674F-49FD-BB85-2FCDD032FA4D" port-id="4"/>
  <is:operation>stimulus</is:operation>
  <is:description>can be long sentences</is:description>
</is:edge>
<is:edge type="structural" edge-id="734F8C39-34FF-4D34-8FC8-76BB0A98AE23">
  <is:head module-id="D45BFBF3-39CB-4C9E-987C-01E7BD2BAE9C" port-id="0"/>
  <is:tail module-id="FA14B54B-674F-49FD-BB85-2FCDD032FA4D" port-id="0"/>
  <is:operation>constituent</is:operation>
  <is:description>can be long sentences</is:description>
</is:edge>
<is:edge type="forwarding" edge-id="176C9DD9-49E1-46A8-B82F-4476173CA963">
  <is:head module-id="FA14B54B-674F-49FD-BB85-2FCDD032FA4D" port-id="2"/>
  <is:tail module-id="8ADFDC1A-F580-4617-A519-FA00BEC5CAEE" port-id="1"/>
  <is:operation>input</is:operation>
  <is:description>can be long sentences</is:description>
</is:edge>
</is:edge-set>

Fig.5 Modules (dark gray circles) linked by edges. Structural or logical edges (solid lines) build a hierarchical architecture of the model. Functional edges (dashed lines) indicate the flow of the information. Ports (light gray smaller circles) of capsule module are linked to ports of modules by forwarding edges.

See the following links for details.

• module-set
  • property
  • port-set
  • physical-quantity-set
  • event-set
  • morphology
  • import

During numerical simulations, especially agent-based simulations, objects such as modules are sometimes needed to be constructed and destroyed dynamically. The controller manages dynamic construction and destruction of objects (edges and modules) according to rules defined in operation-set. Rules of construction and destruction are defined separately in each operation specified by its type. Edges accompanying the modules are are also managed. One controller manages one template module which is specified in a template tag. A controller has a controller-id which is sequential number more than 0.

<is:controller-set>
  <is:controller controller-id="1">
    ... children tags of controller ...
  </is:controller>
</is:controller-set>

A template specifies the target that this controller manages construction and destruction. The target is specified by template-id. The target module must be a capsule type module with state = - “true” in the template tag in the preference.

<is:template template-id="1"/>

This is a set of several operations. One operation defines one action of the controller. Operation has operation-id and type as its attributes. The operation-id is the sequential number starting from 1. The type can take either constructor or destructor.

<is:operation-set>
  <is:operation operation-id="1" type="constructor">
    <is:timing>called</is:timing>
    <is:count>4</is:count>
    <is:initialization>
      <is:target module-id="4BFFE4D0-6C3A-4F4D-913D-7541A0664D9B" physical-quantity="1">
        <is:definition type="ae" format="mathml">
          <m:math> ... </m:math>
        </is:definition>
      </is:target>
    </is:initialization>
  </is:operation>
</is:operation-set>

This takes initial or called. If it is “initial”, this operation is evaluated as initialization when the simulation starts. If it is “called” then the operation is carried out when a condition is satisfied in a module and the module calls this operation.

<is:timing>initial</is:timing>

This specifies count of instances of a template module to be constructed or destructed when the situation is satisfied. To generate random number, “random” must be specified.

<is:count>2</is:count>

Values of physical-quantity(s) must be initialized when module instances are constructed. The physical-quantity to be initialized is specified by the module-id and physical-quantity-id in the target tag. The initial value are defined by mathematical expression by mathML, morphological or time-seriese data. The location where the instance objects are generated during a simulation are given as the initial value of the frame-origin and frame-angle of the module.

<is:initialization>
  <is:target module-id="111dE4D0-6C3A-4F4D-913D-7541A0664KLJ" physical-quantity="1">
    <is:definition type="op">
      <is:call controller-id="2" operation-id="2"/>
    </is:definition>
  </is:target>
</is:initialization>

When the target is one of template included in the template specified in the template tag, instead of defining value directory, call an operator defined in another controller by specifying controller-id and operator-id in a tag call. In this case the type of the definition must be “op”.

<is:description>can be long sentences</is:description>

Each template section in the template-set indicates the module ID of the top module of a template modules which form a tree structure. Each template takes two attribute, one is template-id which is sequential number and unique in a model and the second is ref-module-id pointing a top module of the partial tree of modules representing a template.

<is:template-set>
  <is:template template-id="c1db88ee-e2fc-40fc-a6f1-91e5a23d0c3b" ref-module-id="4BFFE4D0-6C3A-4F4D-913D-7541A0664D9B"/>
  <is:template template-id="6ebfdd24-450c-4bd3-825e-d49ad3a91e4e" ref-module-id="4b0a64bc-7233-4be6-bc1c-0e83baba7388"/>
</is:template-set>

Template modules are declared in as modules in module-set. Initial conditions of state type physical-quantities and implementations of static-variable type physical-quantities can be set in each instance. If these values can be set by instances, the their definition type is set as “instance-dependent” in the description of the template modules. The instance of those templates need to give the concrete values for the initial conditions or the implementation of static-variables, which are defined in target-physical-quantity-set.

Each instance has its own module-id as an attribute, which is used in definitions of edges. In this sense an instance can act as like a usual module. The instance-of tag specifies a template-id of one template among templates listed in the template-set. A template does not necessarily need to be composed of single module, but generally be composed of several modules forming a tree structure. Thus one instance need to define concrete implementations of physical-quantities in several modules. Hence there is target-module-set section, in which each target-module corresponds to each module in the template. A target-module specifies a module by its module-id. Since a module has several physical-quantities to be defined concretely by the instance, there is target-physical-quantity-set and target-physical-quantity.

<is:instance-set>
  <is:instance module-id="86982f9e-dccd-4f41-8cdd-7fa06d8a9d89">
    <is:instance-of template-id="c1db88ee-e2fc-40fc-a6f1-91e5a23d0c3b"/>
    <is:target-module-set>
      <is:target-module module-id="58f9b31b-3775-462b-898b-1ec924c3d834">
        <is:target-physical-quantity-set>
          <is:target-physical-quantity physical-quantity-id="2">
            <is:initial-value>
              <is:definition type="ae" format="mathml">
                <m:math>
                  <m:apply>
                    <m:eq/>
                    <m:ci>x</m:ci>
                    <m:cn>-0.5</m:cn>
                  </m:apply>
                </m:math>
              </is:definition>
            </is:initial-value>
          </is:target-physical-quantity>
 
          <is:target-physical-quantity physical-quantity-id="3">
            <is:implementation>
              <is:definition format="mathml" type="ae">
                <m:math>
                  <m:apply>
                    <m:eq/>
                    <m:ci>c</m:ci>
                    <m:cn>1.75</m:cn>
                  </m:apply>
                </m:math>
              </is:definition>
            </is:implementation>
          </is:target-physical-quantity>
        </is:target-physical-quantity-set>
      </is:target-module>

A set of time series data written in Timeseries ML format is inserted here to be used in this model. timeseries-id which is an attribute of timeseries-data which is UUID. timeseries-set has an attribtue type taking either internal or external. Contents is written either in this insilico model file (internal) or other independent TSML files (external). In the case of internal, contents of timeseries data written in its own format (See details of the section for the insilico-timeseries.) is expanded here. Otherwise only a pointer to a file (URL or relative file path) is specified in uri attribute.

<is:timeseries-set type="internal">
  <ts:insilico-timeseries xmlns:ts="http://physiome.jp/ns/timeseriesml">
    ... children tags of insilico-timeseries ...
  </ts:insilico-timeseries>
</is:timeseries-set>

<is:timeseries-set type="external" iref="../../timeseries.tsml"/>