Using Functions and Procedures in MML | Interagency Modeling and Analysis Group

Introduction

Functions and procedures are mechanisms for incorporating code from procedural languages such as Java, C, C++, Fortran and Matlab into MML models. Some general principles are explained in this document, and pointers to implementation of specific languages are provided.

Prerequisites:

Introductory Survey of MML (required)
Introduction to the JSim GUI (recommended)
Familiarity with Java or C programming (recommended)

MML functions and procedures (F&P) provide mechanisms for incorporating procedural code into MML models. Functions treat all arguments as inputs and return a real value. Procedures have no return value, but have both input and output arguments. To use a function or procedure in an MML model, it must be defined and then called in an appropriate context.

There are three mechanisms for defining F&P. Source F&P are defined by source code embedded within an MML model, which is compiled at model build time or run time. Native F&P are defined by object code that has been previously created by C, C++, Fortran or other native code compilers. Class F&P are defined by pre-compiled Java classes which are linked into the model at run-time.

Procedural code blocks within these F&P definitions must conform to the relevant JSim Application Programmer's Interface (API) so that values computed will properly communicate with the rest of the MML model and the JSim application.

However a function or procedure is defined, it doesn't do any useful work until it is called one or more times in an appropriate context. A function may be used in any algebraic expression within an MML equation or relation constraint. A procedure may be used, standing by itself or modified by a "when" clause, as an MML constraint. The MML @ construct is provided to ensure dimensional compatibility between F&P definition and usage. These concepts are illustrated by the examples that follow:

Multiprocessing F&P

JSim requires F&P used under multiprocessing (MP) to be reentrant, meaning that they can be called simultaneously in different contexts without crosstalk between the computational threads. Writing reentrant code is technical and should be done only be expert programmers. A complete description of reentrancy implementation techniques is beyond the scope of this document.

The JSim compiler (like virtually all other compilers) can't tell whether a function or procedure is reentrant by automated analysis. The model author must tell it. JSim assumes F&P are not reentant unless told otherwise. However, telling JSim that a function or procedure is reentrant will not make it so. In fact, tagging a function or procedure reentant, when the code is not, in fact, reentrant, will typically crash not only the model but java and JSim itself in a truly spectacular way. So never tag a function or procedure as reentrant unless you are very sure the underlying code is reentrant. Standard warnings apply to you and your children to the seventh generation.

Assuming you have a reentrant function or procedure you wish to use under JSim MP, you may tag it reentrant by adding the following clause to the F&P declaration:

      reentrant="true";

The following is a reentrant example using Java source F&P:

// F&P reentrant tag for multi-processing support
source real function square(a) {
  language="java";
  reentrant="true";
  maincode={{
    double aval = a.realVal();
    return aval*aval;
  }};
}

math reentrant {
  realDomain t;
  t.min=0; t.max=5; t.delta=1;
  real v(t) = square(t);
}

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.