This page will look better in a graphical browser that supports web standards, but is accessible to any browser or internet device.

Served by Samwise.

Cardiac Physiome Society workshop: November 6-9, 2017 , Toronto

Using Templates in MML

This page is for the current JSim version 2.0. Click here for the earlier JSim 1.6 version.

This document discusses the current state of templates in MML. MML templates allow an MML author to create reusable modules which become valuable in large-scale modeling. JSim template implementation is still in an experimental stage, and the information provided here may well change for future releases of JSim.



Understanding components and flattening

MML models are constructed via nested components. Each component may contains one or more sub-components and/or constraints. The most common form for constraints are equations, but constraints also include events and procedures . Consider the following model:

(Java plugin required)

The top level component (of type math) is called main. main contains 2 sub-components: t (of type realDomain), and u (of type real) and 5 equation constraints. The t component contains 4 sub-components: min, max and delta (of type real) and ct (of type int).

Most JSim modelers use only the predefined JSim types (math, real, realDomain, realState, int, intState, choice). However, JSim allows users to define their own types via the "template" declaration. When the JSim compiler encounters a component declaration for a user-defined template, the component goes through a "flattening" process wherein the component is reduced to predefined JSim types. Once the entire model is "flat", the compiler proceeds to generate run-time code, dealing only within pre-defined types. This approach spares the component writer the arduous task of understanding the internals of the JSim compiler, thus making template writing a fairly straight-forward process.

Understanding the MFAX and XSIM template packages

NSR currently distributes two optional template packages with JSim:

In each case, the model writer imports the set of template definitions via the MML "import" directive, and creates of model by declaring components using some combination of the these templates and JSim's default templates. Consider the following MFAX model, which describes a the dimerization of a chemical species A in a single compartment:

(Java plugin required)

The top level component here is named "main", and is of type MFAX. example1 has 5 sub-components: t (of type Time); A and B (of type Chem); C (of type Compartment); and R (of type MassBalReaction). example1 also contains 6 equation constraints (e.g. "R.kb = 0.5"). The new types were defined via template commands in the imported MFAX.mod file, a portion of which is show below:

class template MFAX { class="JSim.bcl.mfax.MFSys"; }
class template Time { class="JSim.bcl.mfax.Time"; }
class template Chem { class="JSim.bcl.mfax.Chem"; }
class template Membrane { class="JSim.bcl.mfax.Membrane"; }

The details of these template declarations is explored in the following sections.

Template Declarations

There are currently two types of template declarations supported by MML - class templates and MML templates. Class templates are described by pre-compiled java classes that are loaded as needed. MML templates are templates described in MML. Each has its own strengths and weaknesses, as described in the following sections. Overall, class templates are more general and powerful while MML templates are more transparent and easier to create and maintain. Both the MFAX and XSIM template packages are implemented using class templates. It is expected that MML templates will eventually play an important role in creating large modular physiological models.

A template declaration doesn't "do anything" by itself, that only happens when one or more components are declared using the template. Each component inherits properties of its template and the model writer may extend them in various template-specific ways. The component declaration syntax is independent of the template declaration methodology, facilitating easy reuse and/or substitution of templates.

Class Templates

Class templates have form:

class template NAME { class="CLASSNAME"; }

where words in lower case are reserved by MML, and capitals are defined by the model writer. See the MFAX/XSIM section above for a specific example. CLASSNAME refers to a Java class accessible to JSim via JSIMPATH that follows appropriate conventions for interacting with the planner. Unfortunately, those conventions are not yet finalized and documented, which means that, at present, class templates are only an option for model writers to get the JSim source code .

MML Templates

MML templates allow you to extend existing templates via MML. The simplest usage would be to extend the built-in math template, which represents a collection of variables and/or constraints. For example:

(Java plugin required)

Here the template ABC defines 3 real variables (a, b and c) and one constraint (a+b=c). The top-level model component "main" defines two sub-components X and Y, each of type ABC, meaning that each contains the sub-variables a, b, and c and the a+b=c constraint on those variables. Since the internal ABC constraints leave 2 of it's 3 variables unconstrained, additional constraints must be placed in the top-level component for the model to compile sucessfully. In this case, by constraining X.a and X.b, X.c can be calculated. Y.b is set to 5, and "Y.c=X.c" ends up calculating Y.c, since X.c had already been constrained. The Y version of the a+b=c constraint end up calculating Y.a, since Y.b and Y.c have already been constrained. Note that template constraints do not necessarily determine order of calculation within the component, but that the order may be determined by contextual usage. This is an important feature for writing widely reusable components.

An existing template can be extended following this example, in which the ABC template is extended to include another variable and another constraint:

(Java plugin required)

Note that substitution of the ABCD template for ABC in the main component resulted in only minor changes within main itself. In this way, it is hoped templates can introduce a degree of modular construction necessary for large-scale modeling.

Limitations of MML Templates

While MML templates do have some existing functionality within JSim, they are not yet fully supported and/or documented because the following unresolved problem which are judged to be serious enough to hamper real-world professional usage. It is quite possible that resolution of these problems will require changes to template syntax, which would be problematic for on-going support if this feature was prematurely released:

Comments or Questions?

[This page was last modified 06Jul12, 3:11 pm.]

Model development and archiving support at provided by the following grants: NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.