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.

Miscellaneous Short Topics in MML

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

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;
  real V(t) = sqrt(t); // must ensure t>=0
}

(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 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.

Comments or Questions?

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

Model development and archiving support at physiome.org 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.