Prerequisites:
- Introductory Survey of MML (required)
- Introduction to the JSim GUI (recommended)
Contents:
- Public, Private and Extern variables
- Choice Variables
- Symbolic Derivatives
- Variable Properties
- Comments or Questions?
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
}
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;
}
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
}
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)
}
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)
}
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";
}
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";
}
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?
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.