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.
Prerequisites:
- Introductory Survey of MML (required)
- Introduction to the JSim GUI (recommended)
Contents:
- Understanding components and flattening
- Understanding the MFAX and XSIM template packages
- Template Declarations
- Class Templates
- MML Templates
- Limitations on MML Templates
- Comments or Questions?
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:
// exponential decay via ODE
math main {
realDomain t;
t.min=0; t.max=10; t.delta=1;
real u(t);
when (t=t.min) u=1;
u:t = -u;
}
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:
- MFAX : a set of templates appropriate for chemical network models in multiple compartments with convective flow and membrane transport between those compartments. MFAX is an example of a "Biological Component Library" (BCL) because each template is intended to represent an abstract biochemical entity (e.g. compartment, chemical species, chemical reaction, ...).
- XSIM : a set of templates appopriate for running XSIM-style models under JSim. These templates do not constitute a BCL is the classic sense, since none of them represent biological components, but the underlying implementation methodology is identical to that of the MFAX BCL.
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:
// simple MFAX reaction, without units
import MFAX;
MFAX example1 {
Time t;
t.min=0; t.max=10; t.delta=0.5;
Chem A, B; // this is just a comment
Compartment C;
C.vol = 10;
MassBalReaction R(C, "2A=B");
R.kf = 1;
R.kb = 0.5;
}
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:
// nested template example
math template ABC {
real a, b, c;
a+b=c;
}
ABC template ABCD {
real d;
d=2*c;
}
math main {
ABCD X, Y;
X.a = 1;
X.b = 2;
Y.b = 5;
X.c = Y.c;
}
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:
// extended template example
math template ABC {
real a, b, c;
a+b=c;
}
ABC template ABCD {
real d;
d=2*c;
}
math main {
ABCD X, Y;
X.a = 1;
X.b = 2;
Y.b = 5;
X.c = Y.c;
}
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:
- Mechanisms for sharing common variables between components are not yet well defined, yet they are critical to real-world usage. In particular, template-defined variables must be aware of realDomains (e.g. time) which, to be meaningful, must be shared. The preliminary sharing mechanisms currently in place are currently judged to be insufficient for real-world usage and so are not documented here, lest we become too attached to them.
- Effective large-scale use of MML templates requires importing declarations from multiple source files. The JSim GUI does not yet support editing or project-based control of multiple sources for a single model. Thus, imported files must be stored separately either a user's directory or the JSim installation, which is currently awkward, especially for new users. Better mechanisms for sharing importable templates (perhaps network based) must be developed.
- MML extension of variable templates (e.g. real, realDomain, ...) is sub-optimal because there is no syntax supporting constaint of its own value (i.e. "this").
- MML extension of class templates is not yet supported, and vice-versa.
- Template declaration syntax currently implies single-inheritance, which may or may not be a critical problem. There is yet no general consensus as to whether multiple-inheritance is an essential feature for object-oriented programming (C++ has it, Java does not).
Comments or Questions?
Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, 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.