Introduction

This document describes the XSim template library for JSim, which is used to create the MML wrapper for an XSim-style model under JSim. It assumes you understand the Introduction to XSim-style models under JSim and are familiar with writing simple MML models under JSim.

Basics

More variable types

Spatial variables

Using units

Basics

The XSim template library allows XSim-style declarations of parameter P array locations so that JSim can properly communicate with the free-standing model computation code. We'll start with a simple example (that should already look familiar):

        import XSim;
        XSim main {
          library lib("demo");
          ivar time;    
          time.min=0; time.max=30; time.delta=0.1; time.loc = 130;
          realInput period = 6; period.loc = 1;
          realInput amplitude = 1; amplitude.loc = 2;
          realOutput Sine(time); Sine.loc = 201;
          realOutput Cosine(time); Cosine.loc = 202;
       }

The import statement loads the template library, and the line "XSim main {" declares the model mainline will be done using the "XSim".

The library statement tells JSim that the free-standing model code will be found in the file libjsxdemo.so under Linux, jsxdemo.dll under Windows or libjsxdemo.jnilib under MacOS. There must be exactly one library declaration in an XSim model.

The ivar statement declares the XSim independent variable, of which there must be exactly one. An ivar is like a standard MML realDomain, except that it has an associated P array location (time.loc).

The realInput statements here declare parameters that are set by the user. The realOutput statements declare parameters to be calculated by the XSim model. Both are like standard the MML real, except they have associated P array locations (e.g. period.loc). amplitude and period are scalars since they were declared without any domains. Therefore they will be passed to the P array only during model initialization. Sine and Cosine are time-dependent, since they were declared with domain "time". Therefore they will be returned from the P array for each model time-step.

P array location declarations are required for all ivar, realInput and realOutput variables. Omitting an location will result in a compilation error. Note that locations follow the Fortran convention of counting from 1 (not 0 as in C, Java, etc.).

More variable types

Here's a simple stirred-tank model:

        import XSim;
        XSim main {
          library lib("tank");
          ivar t;       
          t.min=0; t.max=30; t.delta=0.1; t.loc = 130;
          realInput V=1; V.loc = 1;
          realInput Fp=1; Fp.loc = 2;
          extern realInput Cin(t); Cin.loc = 200;
          realOutput Cout(t); Cout.loc = 201;
          realOutput transitTime; transitTime.loc = 205;
       }

Here Cin is declared with domain t, so it will be sent to the model at each time-step. It is declared extern so the user may assign a function generator to it. This declaration corresponds to the XSim feed and dynamic input constructs.

Note that output transitTime is declared without any domains, so it will be retrieved from the P array in the model completion phase. This declaration corresponds to the XSim static output construct.

Spatial domains

Here's a model using a spatial domain:

        import XSim;
        XSim main {
          library lib("btex");
          ivar t;       
          t.min=0; t.max=30; t.delta=0.1; t.loc = 130;
          intInput Nseg = 7; Nseg.loc = 3;
          realDomain x;
          x.min=0; x.max=1; x.ct=Nseg;
          realInput V=1; V.loc = 1;
          realInput Fp=1; Fp.loc = 2;
          choiceInput recirc(0, "No", "Yes")=0; recirc.loc=5;
          extern realInput Cin(t); Cin.loc = 200;
          realOutput Cout(t); Cout.loc = 201;
          realOutput C(t,x); C.loc=300; C.dim=65; 
       }

Here the Nseg variable is declared as an integer, with P array location 3. The recirc variable is a choice integer (as in standard MML) with values "No"=0 and "Yes"=1. There is no corresponding intOutput or choiceOutputs declarations.

The spatial domain x is declared as a simple realDomain, without any location since XSim style models only recognize a single independent variable. However the size of the x grid is determined by Nseg, which is passed to the model (P array location 3).

The output C is a function of both x and t, and so takes up multiple P array locations. The number actually retrieved from the model is determined by x.ct. However, since most model programs have fixed size requirements, you must declare the maximum number of locations C will use, via C.dim. Not specifying C.dim will result in a compilation error.

If the locations used by C were not contiguous, e.g. 300, 303, 306, ... you could specify this with "C.locincr = 3". However, locincr defaults to 1 if not specified.

All variables, input and output, static and dynamic, may have a spatial dimension. Space prohibits a separate example here for each. However, XSim variables (ivar, realInput, intInput, realOutput) may have at most one spatial dimension.

Using units

Units may be included in XSim-style models in the standard JSim way:

        import nsrunit;
        unit conversion off;
        import XSim;
        XSim main {
          library lib("tank");
          ivar t sec;   
          t.min=0; t.max=30; t.delta=0.1; t.loc = 130;
          realInput V=1 liter; V.loc = 1;
          realInput Fp=1 liter/sec; Fp.loc = 2;
          extern realInput Cin(t) molar; Cin.loc = 200;
          realOutput Cout(t) molar; Cout.loc = 201;
          realOutput transitTime sec; transitTime.loc = 205;
       }

Note that unit conversion is off, since native code models have no mechanism to handle automated unit conversion.

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.