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

-->

Miscellaneous Short Topics in MML

Prerequisites:

Contents:

Public, Private and Extern variables

To make models adequately general, JSim allows some variables to be specified as "extern", which means they are not calculated by the model, but are provided to the model externally by the JSim user environment. The run-time environment requires that explicit values be assigned to all externs before a model can be run. Extern variables are considered completely constrained, so no additional MML constraints are required. A sample voltage inverter follows:

// invert extern voltage
math voltage_inverter {
  realDomain t;       // time
  t.min=0; t.max=10; t.delta=0.1;
  extern real Vin(t); // externally provided input voltage
  real Vout(t);       // output voltage
  Vout = -Vin;        // constraint for Vout
}
(Java plugin required)

MML variables may be designated as "private", which means they are not visible to the run-time interface. This can be useful in reducing clutter if a variable is uninteresting at run-time. Extern variables may not be private. Variable neither private nor extern are considered public.:

// using a private variable
math white_rabbit {       
  real a = 5;
  private real b = a^2; // down the rabbit hole
  real c = a + b;
}
(Java plugin required)

Run-time output:

a=5
c=30

Public variables may be redeclared as extern or private. This is accomplished with the keywords extern or private followed immediately by the variable name and can be useful when sub-variables are created automatically as public, as with domains. The following example makes t.min private, making it unchangable at run-time (see following section).: 

// private variable enforces unchangable parameter
math startzero {
  realDomain t;
  t.min=0; t.max=10; t.delta=1;
  private t.min;
}
(Java plugin required)

Choice variables

Choice variables are integer variables whose value is set by the user via a menu of defined values. For example:

choice fruit("apple", "banana", "cherry") = 2;

Above, the label "apple" is associated with the value 1, "banana" with 2, and "cherry" with 3. "banana" will be the default value.

You may arbitrarily assign associated numeric values by using integers as arguments:

choice zork(0, "zero", "one", "two", 10, "ten", "eleven") = 10;

Here the numeric values correspond in the natural way to the text labels. Only the values 0, 1, 2, 10 and 11 will be allowed.

If a choice variable is calculated from other variables, it becomes an output variable. In this case, it behaves no differently than any other integer variable. Example: 

int n = 3;
choice fruit("apple", "banana", "cherry");
fruit = n;

At this time, choice variables are all scalars, and have no associated domains.

Symbolic Derivatives

JSim can solve some variables via symbolic differentiation of other fully constrained variables.:

// symbolic derivative
math deriv1 {
  realDomain t;
  t.min=0; t.max=10; t.delta=1;
  real u(t) = 3*sin(t)^2;
  real v(t) = u:t;      // v = 6*sin(t)*cos(t)
}
(Java plugin required)

JSim currently can only differentiate variables which are constrained by explicit algebraic constraints. It cannot take derivatives of extern variables, implicitly constrained variables, ODE variables, etc. Since the chain rule from calculus is used, the differentiated variable must depend only on other variables with explicit algebraic constraints. In the following example, the attempt to differentiate c would generate an error due to c's nested dependence upon the extern variable a:

math deriv2 {
  realDomain t;
  t.min=0; t.max=10; t.delta=1;
  extern a(t);
  real b(t) = a^2 + t;
  real c(t) = exp(b);
  real d(t) = c:t;      // solve d by differentiating c
}

The colon (derivative) operator may also be applied to expressions. It has high precedence, so this requires the use of paretheses:

// derivative operator applied to complex expression
math deriv3 {     // same result as deriv1 above
  realDomain t;
  t.min=0; t.max=10; t.delta=1;
  real v(t) = (3*sin(t)^2):t;        // v = 6*sin(t)*cos(t)
}
(Java plugin required)

Variable Interpolation

Consider:

// variable interpolation
math interp1 {
  realDomain t; 
  t.min=0; t.max=3; t.delta=0.5;
  extern real u(t);
  real v(t);
  v = u^2;
}
(Java plugin required)

The constraint "v=u^2" applies at corresponding values of t, e.g. v(0)=u(0)^2, v(0.5)=u(0.5)^2, v(1)=u(1)^2, etc.

In some cases, the model may require u and v correspond at different values of t. For instance, we might prefer a constraint in which the values of v are "t delayed" relative u, as in v(t)=u(t-1)^2. JSim variable interpolation is a syntax that allows model writers to describe this relationship. Variable interpolation is a new new JSim feature, and is only partially supported, due to a number of subtle problems that will be described. Nevertheless, it can be very useful in the restricted set of circumstances it does apply, and support for the feature will be enhanced in later releases.

Variable interpolation is quite useful for interpolating functions values from an external data source. In the following, f(x) is provided to the model from an external data source and g(t) is calculated from interpolated values of f():

// interpolating extern data source
math a05 {
  realDomain t, x;
  t.min=1; t.max=5; t.delta=1;
  x.min=0; x.max=1; x.delta=0.01;
  extern real f(x);
  real g(t) = f(1/t);
}
(Java plugin required)

JSim variable interpolation syntax to support the delay example above is the natural one: 

v = u(t-1)^2;

Note that v does not need to be specified as v(t), since the two are equivalent. As it stands, this constraint has a problem a t=0 because u(-1) is not defined. This will generate an error at run-time because -1 is out of bounds for t. This problem can be corrected by enclosing the variable interpolation an if statement:

v = if (t<1) 0 else u(t-1)^2;

This is an improvement, but is not quite bullet-proof because the user might change t.min to 1 at run-time, renewing the previous problem. Two reasonable solutions exists:

v = if (t-t.min<1) 0 else u(t-1)^2;

or:

private t.min;
v = if (t<1) 0 else u(t-1)^2;

The first method is somewhat awkward to read, but is good for any t.min. The second is easier to read, but fixes t.min=0. The complete working example, using the first method follows:

// bullet-proof interpolation
math interp2 {
  realDomain t;
  t.min=0; t.max=3; t.delta=0.5;
  private t.min;
  extern real u(t);
  real v(t);
  v = if (t<1) 0 else u(t-1)^2;
}
(Java plugin required)

Unfortunately, the current JSim Planner cannot handle a number of related cases that might potentially be useful. Consider a interp2-like model with the converse relationship between the time-courses of u and v: 

math interp3 {
  realDomain t;
  t.min=0; t.max=3; t.delta=0.5;
  private t.max;
  real u(t) = t+1;
  real v(t);
  v = if (t>2) 0 else u(t+1)^2;
}

The problem is that JSim currently calculates any domain t starting from t.min and proceeding through t.max. To properly calculate interp3, the reverse order of t calculation would be desirable. What the user will see at run-time is that some values for v will be returned as NaNs (Not A Number, see IEEE standard 754) because they were calculated from u values that were not yet defined.

JSim also cannot currently handle the following recursive relation, which should (ideally) produce a sawtooth waveform for v:

math interp5 {
  realDomain t;
  t.min=0; t.max=3; t.delta=0.5;
  private t.min;
  real v(t) = if (t<1) t else v(t-1);
}

Note that the constraints "when (t=t.min) u=1" and "u(t.min)=1" are mathematically equivalent, but that only the former can be used to specify ODE and PDE initial and boundary conditions.

Numerical accuracy can also be a problem with variable interpolation, since values at non-grid points are linearly interpolated from nearby grid points. In the following v and w, should (ideally) be identical, but are not due to the linear interpolation:

// examines linear interpolation accuraccy 
math interp6 {
  realDomain t;
  t.min=0; t.max=1; t.delta=0.25;
  private t.min, t.max;
  real u(t) = t^2;
  real v(t) = u(t^2);
  real w(t) = t^4;
}
(Java plugin required)

This problem is particularly acute in some ODE calculations. Increasing the fineness of the domain grid will help to reduce the interpolation error, although at the expense of longer calculation times and larger output files.

Although there are some problems with JSim variable interpolation, it is hoped that the feature is still useful in the restricted circumstances it applies, particularly for delay lines. Work continues to improve this feature for later releases.

Variable Properties

JSim version 1.6.66 introduces customizable variable properties. Properties allow tagged values to be associated with a variable. Currently, only string values are supported. The "desc" and "help" properties are defined by default. The "desc" property is a concise one-line description of the variable. The "help" property is free-form text that may extend to multiple lines. Additional properties may be specified on a model-by-model basis with the MML "property" command. Additional properties, if defined, may be used to label variables for various automated analyses currently under development. For example, the additional property "fma" might be defined that connects a variable the Foundational Model of Anatomy ontology. Properties are assigned by optional assignments that should be clear from the following example: 

// fma, opd properties
property fma=string, opb=string; // ontology references
math main {
  realDomain t;
  t.min=0; t.max=5; t.delta=1;
  extern real Cin(t);
  real u(t) = Cin^2;
  u.desc = "input concentration";
  real Vp = 1;
  Vp.desc = "plasma volume";
  Vp.help = "typically 0.3-2.5\nsee Atkins & Bee JAP 1997";
  Vp.fma = "fluid.blood.plasma"; 
  Vp.opb = "volume";
}
(Java plugin required)

If defined, the "desc" and "help" property values will appear in the help popup for a variable in the GUI. The "desc" and "help" properties are normally defined as double-quoted strings, with "\n" being interpreted as a line separator for v.help::

If a property value text is extensive, it may be simpler to use the alternative double-brace specification for multi-line text:

// using double braces for extensive property text
math prop2 {
  real Vp = 1;
  Vp.desc = "plasma volume";
  Vp.help = {{Four score and seven years ago our fathers brought forth on this 
continent a new nation, conceived in liberty and dedicated to the 
proposition that all men are created equal. Now we are engaged in 
a great civil war, testing whether that nation or any nation so 
conceived and so dedicated can long endure. We are met on a great 
battlefield of that war. We have come to dedicate a portion of 
that field as a final resting-place for those who here gave their 
lives that that nation might live. It is altogether fitting and 
proper that we should do this. But in a larger sense, we cannot 
dedicate, we cannot consecrate, we cannot hallow this ground. 
The brave men, living and dead who struggled here have consecrated 
it far above our poor power to add or detract. The world will 
little note nor long remember what we say here, but it can never 
forget what they did here. It is for us the living rather to be 
dedicated here to the unfinished work which they who fought here 
have thus far so nobly advanced. It is rather for us to be here 
dedicated to the great task remaining before us--that from these 
honored dead we take increased devotion to that cause for which 
they gave the last full measure of devotion--that we here highly 
resolve that these dead shall not have died in vain, that this 
nation under God shall have a new birth of freedom, and that 
government of the people, by the people, for the people shall 
not perish from the earth.}};
  real Fp=1;
  Fp.desc="flow rate";
}
(Java plugin required)

When adding customizable help to a model, remember that model help automatically includes the default value and unit (if any) for input variables and the relevant equations and unit (if any) for output variables. Including such information in the customizable help is strongly discouraged.

[This page was last modified 03Mar08, 3:11 pm.]

Model development and archiving support at physiome.org provided by the following grants: 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.