MFAX BCL Reference | Interagency Modeling and Analysis Group

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

Name
Description
Declaration arguments
Compatible unit
Sub-variables
Notes

The component types described in this manual are

Chem
Compartment
Consumption
FastReaction
Flow
FlowJunc
FlowSink
FlowSource
FluxReaction
Inject
MassBalReaction
Membrane
Production
Time
TransportFlux
TransportPS
Comments or Questions?
Give feedback

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?

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.