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.

Cardiac Physiome Society workshop: November 6-9, 2017 , Toronto

MFAX BCL Reference

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

This is a reference manual for the MFAX Biological Component Library (BCL). MFAX stands for a Metabolite Flow and Exchange, and contains a set of components appropriate for chemical network models in multiple compartments with convective flow and membrane transport between those compartments. This manual provides concise and exact syntax and semantics for each component.

Prerequisites:

Overview

Each BCL component is declared in the following manner in a BCL model:

      component_type name(arguments) unit;

where the unit declaration is present only when unit conversion is on and the component type requires it.

Details provided here for each component type include

The component types described in this manual are

Chem

Name
Chem
Description
Chemical Species
Declaration arguments
NONE
Compatible unit
mole/sec

Example:

      Chem A mM;

Sub-variables
NONE
Notes
The name of a chemical species. Concentrations and production and consuption rates for species in system is reflected in sub-variables in many other components, but the Chem component itself has no sub-variables. In order to avoid name conflicts in concentration sub-variables, Chem names must start with a capital letter.

Compartment

Name
Compartment
Desc
Uniformly mixed volume
Declaration Arguments
NONE
Compatible unit
liter

Example:

      Compartment region1 ml;

Sub-variables:

      real vol ml; // volume of compartment
      real X(t) molar;  // concentration of species X in compartment

Notes
A volume over which all chemical species have uniform concentration. The BCL author must set the volume subvariable "vol". The concentration variables X may be set (forced) explicitly, or vary based on the dynamics of the model. If the latter, the initial concentrations default to zero, but may be set otherwise via the MML when construct. If a compartment has any attached flow components (FlowSource, Flow, FlowSink), it must have exactly one inflow and exactly one outflow.

Consumption

Name
Consumption
Desc
Consumption of a chemical species in a compartment
Declaration Arguments
Compartment, Chem
Compatible unit
NONE

Example:

      Consumption Q1(C1, A);

Sub-variables:

      real flux(t) mole/sec; // consumption rate

Notes
Consumption of a Chem within a Compartment as determined the sub-variable flux, which has no default and must be constrained by the BCL author. JSim attempts to protect concentrations from going negative by forcing zero consumption at zero concentration. However, numeric instabilities in the ODE solvers may sometimes result in negative concentrations. To avoid this, it is recommended that "flux" values ramp smoothly to zero at zero concentration. Negative "flux" values will result in production the species within the compartment. Exact units of the rate variable depend on the units for the related Chem, Compartment and Time variables.

FastReaction

Name
FastReaction
Desc
Fast Chemical Reaction
Declaration Arguments
Compartment, Equation
Compatible unit
NONE

Example:

      FastReaction R1(C1, "X+Y=2Z");

Sub-variables:

      real k(t); // equilibrium constant

Notes
A reaction that equilibrates instantaneously compared to any MassBalReactions, FluxReactions and intercompartmental exchanges in the system. The sub-variable k may be thought of as equivalent to kf/kb in a MassBalReaction. k has no default value, and must be constrained by the BCL author. Multiple FastReactions may be specified, however, the instant equilibration constraint makes it possible to overspecify a system in this way, so the BCL author must be careful. JSim will reject overspecified models. JSim can run into numeric trouble in cases where there are multiple molecules on both sides of a FastReaction and one or more of the concentrations become zero, however this problem is probably more theoretical than practical. Nevertheless, work on this issue continues.

Flow

Name
Flow
Desc
Flow between two Compartments or FlowJunctions
Declaration Arguments
two Compartments and/or FlowJunctions
Compatible unit
NONE

Example:

      Flow F2(C1, C2);

Sub-variables:

      real flow(t) liter/sec;   // rate of flow
      real X(t) mole/liter;     // conc. of Chem X in this flow

Notes
Flow from 1st argument into 2nd argument. The flow and concentration sub-varibles are informational only, and should not be constrained by the BCL author.

FlowJunc

Name
FlowJunc
Desc
Flow Junction
Declaration Arguments
none
Compatible unit
NONE

Example:

      FlowJunc J1 liter;

Sub-variables:

      real Xwgt(t);     // output flow fraction in flow X
      real Y(t) molar; // outflow concentraion of Chem Y

Notes
A volumeless junction of 2 or more flows, useful for splitting or combining flows. At least one input flow and at least one output flow must be attached. The Xwgt variables (where X is the name of an output Flow, FlowSource or FlowSink), collectively determine the fraction of flow to each output. All Xwgts default to 1, so unless the BCL author constrains them, flow will be distributed equally to all outputs.

FlowSink

Name
FlowSink
Desc
Flow Sink
Declaration Arguments
one Compartment or FlowJunction
Compatible unit
NONE

Example:

      FlowSink F3(C2);

Sub-variables:

      real flow(t) liter/sec;   // rate of flow
      real X(t) molar;  // conc. of Chem X in this flow

Notes
Drainage of flow from component, flow disappears from system. The flow and concentration sub-varibles are informational only, and should not be constrained by the BCL author.

FlowSource

Name
FlowSource
Desc
Flow Source and/or regulator
Declaration Arguments
one or two Compartments or FlowJunctions
Compatible unit
liter/sec

Examples:

      FlowSource F1(C1) liter/sec;
      FlowSource F2(C2,C1) liter/sec;

Sub-variables:

      real flow(t) liter/sec;   // rate of flow
      real X(t) mole/liter;     // conc. of Chem X in this flow

Notes
With one argument, provides system flow source. With two arguments, provides system flow regulator. The "flow" sub-variable must be constrained by the BCL author. The concentration variables are informational only, and should not be constrained. Introducing a concentration in a FlowSource is usually done by attaching one or more Inject components to it.

FluxReaction

Name
FluxReaction
Desc
Flux-based Chemical Reaction
Declaration Arguments
Compartment, Equation
Compatible unit
NONE

Example:

      FluxReaction R1(C1, "X+Y=2Z");

Sub-variables:

      real flux(t) mole/sec; // reaction flux

Notes
A chemical reaction whose actions are determined by a flux variable which may be positive or negative. The flux variable has no default and must be constrained by the BCL author. Care should be taken so that the flux variable is not positive if the reactant concentrations are zero, and not negative if the product concentrations are zero.

Inject

Name
Inject
Desc
Injection
Declaration Arguments
FlowSource, Flow or FlowSink plus a Chem
Compatible unit
NONE

Example:

      Inject I1(F1, A);

Sub-variables:

      real flux(t) mole/sec;    // injection rate of the Chem

Notes
An injection of a Chem into a flow (FlowSource, Flow or FlowSink) as determined by the sub-variable "flux" which has no default and so must be constrained by the BCL author. "flux" units are calculated from those of Time and the specified Chem (e.g. if Time has unit "hour" and Chem has unit "mM", "flux" will have unit "mmol/sec"). Neat, huh?

MassBalReaction

Name
MassBalReaction
Desc
Mass Balance Chemical Reaction
Declaration Arguments
Compartment, Equation
Compatible unit
NONE

Example:

       MassBalReaction R1(C1, "X+Y=2Z");

Sub-variables:

      real kf(t);  // forward equilibrium constant
      real kb(t);  // backward equilibrium constant

Notes
A chemical reaction whose actions are determined by forward and backward rate constants (kf and kb). Units for kf and kb will vary depending upon the form the chemical equation, which must be in quotes. Spacing does not affect the chemical equation. Both kf and kb must be constrained by the BCL author, since neither has a default value.

Membrane

Name
Membrane
Desc
Membrane between two compartments
Declaration Arguments
Compartment1, Compartment2
Compatible unit
NONE

Example:

      Membrane M(C1, C2);

Sub-variables
NONE
Notes
A Membrane defines the topologic relationship between two compartments. A membrane implies no calculations in itself, but serves as an attahchment point for Transport components.

Production

Name
Production
Desc
Production of a chemical species in a compartment
Declaration Arguments
Compartment, Chem
Compatible unit
NONE

Example:

      Production Q2(C2, A);

Sub-variables:

      real fluw(t) mole/sec; // production rate

Notes
Production of a Chem within a Compartment. This is the same as the Consumption component, except with the sign of the rate subvariable reversed. See Consumption .

Time

Name
Time
Desc
Time, that eternal, ever-unfolding stream of existence.
Declaration Arguments
NONE
Compatible unit
second

Example:

      Time t second;

Sub-variables:

      real min second;    // minimum value for time
      real max second;    // maximum value for time
      real delta second; // time grid spacing
      int ct;            // # points in time grid

Notes
Defines the name for system time, which is represented as an evenly spaced grid. There must be exactly one Time declaration in a MFAX model, and it must be the first declared component. Units for min, max and delta sub-variables are same as for Time component itself. The model must constrain min, max and either delta or ct. For those familiar with MML, Time is a realDomain component with additional semantics.

TransportFlux

Name
TransportFlux
Desc
Flux mediated Transport across a Membrane
Declaration Arguments
Membrane, Chem
Compatible unit
NONE

Example:

      TransportFlux T1(M, A);

Sub-variables:

      real flux(t); // flux in moles/time

Notes
Cross-membrane transport as determined by sub-variable flux.

TransportPS

Name
TransportPS
Desc
PS mediated Transport across a Membrane
Declaration Arguments
Membrane, Chem
Compatible unit
NONE

Example:

      TransportPS T1(M, A);

Sub-variables:

      real PS(t) liter/sec;  // permiability*surface area

Notes
Cross-membrane transport as determined by sub-variable PS, which has units compatible with liter/sec that are determined by those of Time and the first Compartment attached to the Membrane.
Comments or Questions?

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

Model development and archiving support at physiome.org provided by the following grants: 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.