The following is a brief template of what should go into a proposal for this SBML L3 extension. It is written as an outline of the sections we envision being important to put into the document.

Goals and scope

The original objectives for the proposed SBML Composition extension were the following:

• Facilitate the reuse of existing models (as components)
• Manage complexity when building large models

As various different approaches were analysed in considerable amount of detail during the September 2007 workshop on model composition, the goals, scope, and design of the extension evolved considerably:

1. There is a fundamental need for a simple algorithm for defining, referring to, and including, separate model components - e.g. chunks of SBML documents (or fragments thereof). This should be a "core" enhancement to SBML in Level 3. A separate proposal for such an enhancement (based on xlink) was drafted and is described here.
2. To define a model that can be arbitrarily complex, but purely hierarchical (when referring to its parts), is both required and sufficient for achieving all of the goals of the proposal. To reflect this, the proposed L3 extension has been renamed the Hierarchical Modeling extension. The syntactical elements needed are surprisingly few - as long as there is an unequivocal mechanism for separating "sub-model" namespaces and replacing ("overloading") model elements.
3. The proposed solution is simple, but has a number of quite powerful additional features (that were somewhat unforeseen):
   • The ability to create related collections of model variants - e.g. storing "multiple runs" of a model (with different kinetic parameters or initial conditions) - in a single SBML document
   • The ability of almost complete backwards compatibility if libSBML will be enhanced to support this extension - e.g. L2 software tools that use libSBML for document handling may be able to read in any such model as a "flattened" L2v3 model
   • The ability to create "smart" visualization tools/algorithms - e.g. "balck-box" display of components, selective zoom/editing of components, etc.
   • The facilitation of tool interoperability with CellML language-encoded models and components

Design/architecture

Use cases

Syntax

HierarchicalModel Type

The HierachicalModel is the type of the model element, which is the top element of an SBML file containing a model which is composed from multiple submodels. The HierarchicalModel is derived from the Model type of the SBML core. The attributes of the model stay unchanged however the sequence of child elements is expanded. The added child elements are listOfSubmodels, listOfReplacements, and listOfPorts.

ListOfSubmodels Type

The ListOfSubmodels is the type of the listOfSubmodels element. This element contains the a list of submodels . The model sources which are instantiated may be defined by a model element, or locally and remotely (in another XML documnet) through the SBMLInclude type. The two alternate attribute lists of the source element present restrictions of the SBMLInclude type (derived from xi:include) applicable for the local or remote model definitions. The scope of the SBML id of the hierarchical model does exclude the child of the submodel element. This means that an instantiated model has its own namespace. It is possible to instantiate several copies of a submodel from the same source.

The resulting section in an SBML document would look like:

         <listOfSubModels>
           <submodel id="Submodel_1">
             <substanceConversionFactor 
               id="SCF_1"
               name="Substant Conversion Factor 1"
               value="1000" 
               units="submodelSubstsanceUnitPerParentModelSubstanceUnit"
               constant="true" />
             <volumeConversionFactor 
               id="VCF_1"
               name="Volume Conversion Factor 1"
               value="1000" 
               units="submodelVolumeUnitPerParentModelVolumeUnit"
               constant="true" />
             <areaConversionFactor 
               id="ACF_1"
               name="Area Conversion Factor 1"
               value="100" 
               units="submodelAreaUnitPerParentModelAreaUnit"
               constant="true" />
             <lengthConversionFactor 
               id="LCF_1"
               name="Length Conversion Factor 1"
               value="10" 
               units="submodelLengthUnitPerParentModelLengthUnit"
               constant="true" />
             <timeConversionFactor 
               id="TCF_1"
               name="Time Conversion Factor 1"
               value="60" 
               units="submodelTimeUnitPerParentModelTimeUnit"
               constant="true" />
             <model id = "HierarichicalModel_1">
               ...
             </model>
           </submodel>
             ...
           <submodel id="Submodel_X">
             <model xref="..." xpointer="..." />
           </submodel >
         </listOfSubmodels>

ListOfReplacements Type

ListOfPorts Type

ConversionFactor Type

The ConversionFactor type is used to specify the conversions required between the parent and sub models as well as the conversion required for replacements. The type is derived from the Parameter type of the SBML core with the restriction that the constant attribute is fixed to the value true.

The conversion is such that following two MathML fragments are equivalent in value and in units.

         <ci> target </ci>

         <apply>
           <times/>
           <ci> conversionFactor </ci>
           <ci> source </ci>
         </apply>

This means that when we flatten a hierarchical model to a SBML core model every occurrence of the first fragment will be replaced by the second. For this mechanism to work properly in the units space it is required that proper units for the conversion factors must be defined as part of the parent model.

ObjectReference Type

Description of extension

Expected impact on other extensions

Some possible other L3 extensions that might be impacted by this one are: modularity/inclusion, rule-based models, arrays, spatial geometry. Are there others?

Previous relevant proposals and other documents

-- StefanHoops - 11 Sep 2007