Tutorial (under construction)

Opening Comments

Re-usable Modular Code for Physiological Modeling with JSim's MML

Every attempt to make modular reusable code will have some shortcomings. It is a truism that a generic modeling environment that will do everything for everybody will prove to be too complex for almost anyone to utilize. In advance, we must recognize that there will be shortcomings and compromises in whatever is proposed. Hence we propose a simplified approach to writing and reusing modular code that will be useful in producing correct models, but will not be able to solve all types of problems.

We define a model as consisting of a name space and rules governing the elements of the name space. The elements of the name space include the model name and all the named parameters and variables in the model. The rules governing the elements of the name space are all of the declarations and equations. The reusable name space consists of those elements which we will want to use to define in a new model. Similarly, the reusable rules consists only of those declarations and equations which we will want to include also. We delineate the reusable name space and reusable rules with three directives. The three directives appear as comments in the model and are given by

//%NAMESPACE,
//%START, and
//%END.

An illustration is given to make this less abstract. Here is a model of a single compartment with flow.

comp1Flow.mod:

//%NAMESPACE comp1Flow(A,Ain,Aout,A0,F,V);
import nsrunit;
unit conversion on;
math comp1Flow{
realDomain t s; t.min=0; t.max=30; t.delta=0.1;
//%START
real A(t) mM;
real Aout(t) mM;
real A0 = 1 mM;
extern real Ain(t) mM;
real F = 1 ml/(g*min);
real V = 0.05 ml/g;
when(t=t.min) {A=A0;}
A:t=F/V*(Ain-A);
Aout=A;
//%END
real Q(t) umol/g;
real Qint(t) umol/g;
when(t=t.min) {Qint=V*A0;}
Q=V*A;
Qint:t=F*(Ain-Aout);
}

In the example above, element "A" in the reusable name space refers to all instances of A in the reusable rules. Single instances of A are contained in the following lines.

real A(t) mM;
when(t=t.min) {A=A0;}
Aout=A;
Q=V*A;

Two instances of A are contained in this line.

A:t=F/V*(Ain-A);

Element names such as "A" can be located by finding all instances of the name which are surrounded by valid separators and/or the name starts a line of code or ends a line of code. Valid separators include the spacing symbols (blank space and tabs); the mathematical symbols, "=",">",">", "^", "*", "/", "+", and "-"; the grouping symbols, "{", "}", "(", and ")"; and punctuation symbols (comma, semicolon, full colon, and period).(Please note: The description of the processes used will be replaced by the standard lexical analyses and parsing software which has been available for decades.)

In the comp1Flow.mod model, the elements Q and Qint calculating the amount of material still in the compartment using two different methods have not been included in the reusable name space and rules. They are in the model to validate the calculations in comp1Flow.mod, but we have no further use for them.

To complete our example, a simple model of consumption (removal of a chemical species in a compartment) is given.

consumption.mod:

//%NAMESPACE consumption(A,A0,V,G)
import nsrunit; unit conversion on;
math consumption { //
realDomain t sec; t.min=0; t.max=30.; t.delta=0.1;
//%START
real A(t) mM;
real A0 = 1 mM;
real V = 0.05 ml/g;
real G = 1 ml/(g*min);
when(t=t.min) {A=A0;}
A:t=-G/V*A;
//%END
real Analytic(t) mM;
Analytic=A0*exp(-(G/V)*t);
} 

A set of directives that produces a working model from the two or more existing models is needed. We call such a file a "new rules file". It contains the directives,

//%EXTERNAL,
//%RENAME,
//%PROCESS, 

and optionally the directives

//%START and
//%END, 

as well as model code. Model code inside a

//%START and //%END

directive is treated differently than model code outside of those directives.

The EXTERNAL directive provides a name and a file name so that the code being reused can be located. The RENAME provides a matching set of new names that will be used to generate new equations and declarations from the reusable rules governing the elements of the name space. The PROCESS directive signifies that all the necessary components present including the START and END directives used in the "new rules file" to surround additional code which must be processed with the renamed reusable code.

An example of such a "new rules file" is makeComp1FlowG, a file for making a one compartment flow model with consumption.

makeComp1FlowG:

import nsrunit;
unit conversion on;
math Comp1FlowG {
realDomain t sec; t.min=0; t.max=30.0; t.delta=0.1;
//%EXTERNAL comp1Flow comp1Flow.mod
//%EXTERNAL consumption consumption.mod
//%RENAME comp1Flow(A1,A1in,A1out,A10,Fp,V1)
//%RENAME consumption(A1,A10,V1,G1)
//%PROCESS
 }

This file is processed in the following way:

• (Step 0) Create file for the new program.
• (Step 1) Read a line. If at end of file, quit.
• (Step 2) If this line does not begin with one of the directives, copy it directly to the new program file. Go to step (1).
• (Step 3) If this line is a directive, determine what kind of directive it is.
  • (A) If it is the EXTERNAL directive, then following EXTERNAL there are two names. The first string is the name of the model. The second string is the location of the model. This information is saved. Go to step (1).
  • (B) If it is the RENAME directive, separate the names following RENAME into the model name and all the elements of the new name space. Using the model name, open the associated model file. Locate the NAMESPACE directive. Pair each name in the NAMESPACE directive with the names in the RENAME directive and make a copy of the reusable rules replacing all of the NAMESPACE names with the RENAME names. Write this new code to a temporary area. Go to step (1).
  • (C) If there is a START directive, read and copy all subsequent lines to the temporary area until the END directive is read. Go to step (1).
  • (D) If it is a PROCESS directive, process all of the code in the temporary area following these rules:
    • Remove duplicate copies of any declarations;
    • Write all of the real, int, extern real, realState, and int declarations to the new program file;
    • Look for code lines that begin with a "Name:t = something;".Scan the rest of the temporary area and locate all instances of "Name:t = something else;". Combine the something and the something else's into a single statement, Name:t = something + (something else) + ... + (last something else); and write the statement to the new program file. Do this for all the time derivatives.
    • Finally write all remaining statements in the temporary area to the new program file.
    Goto step (1).

This process produces the following model code:

Comp1FlowG.mod

import nsrunit; unit conversion on;
math Comp1FlowG {
realDomain t sec; t.min = 0; t.max = 30.0; t.delta = 0.1;
real A1(t) mM;
real A1out(t) mM;
real A10 = 1 mM;
extern real A1in(t) mM;
real Fp = 1 ml/(g*min);
real V1 = 0.05 ml/g;
real G1 = 1 ml/(g*min);
when(t=t.min) {A1=A10;}
A1:t=Fp/V1*(A1in-A1)+(-G1/V1*A1);
A1out=A1;

 }

This model illustrates merging together two one-compartment models with flow, two two-compartment models for passive exchange, and one model for enzyme conversion. The "new rules file" is shown below. The RUN MODEL button contains the final model and the three different models from which it was constructed.

makeComp2FlowEnzyme

import nsrunit; unit conversion on;
math comp2FlowEnz {
realDomain t sec; t.min = 0; t.max = 30.0; t.delta = 0.1;
//%EXTERNAL comp1Flow comp1Flow.mod
//%EXTERNAL exchange  exchange.mod
//%EXTERNAL enzyme    enzyme.mod
//%RENAME comp1Flow(A1,A1in,A1out,A10,F,V1)
//%RENAME comp1Flow(B1,B1in,B1out,B10,F,V1)
//%RENAME exchange(A1,A10,V1,A2,A20,V2,PSA)
//%RENAME exchange(B1,B10,V1,B2,B20,V2,PSB)
//%RENAME enzyme(A2,A20,B2,B20,E2,AE2,kf12,kb12,kf22,kb22,Etot2,JA22AE,JAE22B)
//%PROCESS

 }

Using models for

• Facilitated transport with competition for two species and two compartments (TranspFac2.mod,
• Direct conversion (convert.mod),
• Michaelis-Menten conversion (GmaxKm.mod), abd
• Enzyme conversion (enzyme.mod),

the following models are constructed:

• TF2G.mod--Facilitated Transport for two species and direct conversion of the first species into the second species in the 2nd compartment.

• TF2GmaxKm.mod--Facilitated Transport for two species and Michaelis-Menten conversion of the first species into the second species in the second compartment.

• TF2Enz.mod--Facilitated Transport for two species and enzyme conversion in the 2nd compartment.