phone (860)
679-1452Virtual Cell - Technology
National Resource for Cell Analysis and Modeling
VCML Specification
IntroductionThe Virtual Cell Markup Language (VCML) is an XML document format for describing biological and mathematical models and specifications for analysis (e.g. simulations) to be performed on those models.
Versions
Version 0.4 is the baseline version derived from the native format of Virtual Cell 4.4. Version 1.0 will be a significant refactoring and removal of several major SBML incompatibilities. Used by first Open Source version of VCell (VCell 5). This is a placeholder for a work-in-progress document. Final documents for each version of VCML will be deposited at
http://sourceforge.net/projects/vcell/
Overview
This document describes the various Virtual Cell concepts (such as Unit representations in the Virtual Cell, Expression handling in the Virtual Cell (VCML), VCML symbols and namespaces, reserved symbols allowed in the Virtual cell. This document also presents the VCML document format and the specifications for the various VCML elements.
Unit Representation and Built-in Unit System in the Virtual Cell
Units in the Virtual Cell are not explicitly specified in VCML. Units for quantities int he Virtual Cell are based on the SI unit system. Each quantity in the Virtual Cell (species concentration, structure size, reaction rate, etc.) has pre-defined units, and in VCML, it is understood that these units hold for those quantities. The following table lists some basic of the quantities and their default units in the Virtual Cell.
| Quantity | Units |
|---|---|
| Length | um |
| Area | um2 |
| Volume | um3 |
| Time | second |
| Voltage | mV |
| Current | pA |
| Capacitance | pF |
| Species Concentration in Feature (3-d compartment) | uM |
| Species Concentration on Membrane (2-d compartment) | molecules/um2 |
| Reaction rate in Feature (3-d compartment) | uM/sec |
| Reaction rate in Membrane(2-d compartment) | molecules/um2/sec |
| Flux rate on Membrane (2-d compartment) | uM.um/sec |
Unit support in the Virtual Cell is provided with the use of an extenal java library from The University Corporation for Atmospheric Research (UCAR). The ucar.units package provides support for parsing and formatting string unit specification, converting numerical values between compatible units, and performing arithmetic on units (such as dividing one unit by another).
VCML Expressions
Expressions in the Virtual Cell use the infix notation similar to the expression handling in C and Java languages. The only notation not handled by the Virtual Cell expression handler is the conditional operation { (boolean_condition) ? (value_1) : (value2) }.
Similar to the C language, the following operators can be used in the Virtual Cell - arithmetic operators : +, -, *, /, ^; and logical operators : &&, ||, !. Operations are performed on real numbers, not integers. Also, like the C language, Virtual Cell coerces booleans to real and real to booleans. For example, boolean false when converted to real gets a value of 0 and true is 1; and a non-zero real number when converted to boolean is true and zero is converted to false.
The following functions are allowed in Virtual Cell expressions: exp, sqrt, abs, pow, log, sin, cos, tan, asin, acos, atan, atan2, max, min, ceil, floor, csc, cot, sec, acsc, acot, asec, sinh, cosh, tanh, csch, coth, sech, asinh, acosh, atanh, acsch, acoth, asech, factorial, log10.
When expressions are written out to VCML from a Virtual Cell model, it is written out in MathML format.
VCML Identifier Symbols
When defining an identifier tokens (in expressions) in the Virtual Cell, the following syntax is used:
#ID: LETTER (LETTER | DIGIT)
where LETTER: ["a"-"z", "_", "A"-"Z"] {alphabet and underscore characters} and DIGIT : ["0"-"9"] {numbers}
An identifier can start with a letter or underscore character but not with a digit, followed by letters or digits.
Math namespace, Bio namespace and Scoping Rules
Each entity in the BioModel (and MathModel) are defined in separate namespace. If an entity is defined within another (parent) entity, some of the symbols defined in the child entity are not accessible in the parent entity or another peer entity; but symbols defined in the parent entity are available in the children entities. For example, a species initial condition defined in an application (also referred to as SimulationSpec or SimulationContext) is not accessible in the model or biomodel, but global parameters defined in the model is avialable in the application. Also, when the math is generated in the application or MathModel, it has its own namespace, hence the generated symbols are not accesible in the model or application. The diagram below depicts the namescope heirarchy in a BioModel (the math namescope is flat with no accessibility from other namescopes and hence is independent).
Click on Image for lager view.
Reserved Symbols
The Virtual Cell specifies a set of reserved symbols and constants that can be used in expressions and computations. The reserved symbols used in Virtual Cell are : x, y, z representing the x, y, z coordinates in with units of um and t representing time in seconds. The reserved constants used in Virtual Cell computations are listed in the table below.
| Name | Description | Value | Units |
| _T_ | Absolute temperature | - | Kelvin (K) |
| _F_ | Faraday constant | 9.648e4 | Coloumbs/mole (C/mol) |
| _F_nmol_ | Faraday constant | 9.648e-5 | Coloumb/nano-mole (C/nmol) |
| _N_pmol_ | Avogadro's number (scaled) | 6.02e11 | molecules/pico-mole (molecules/pmol) |
| _K_GHK_ | Goldman_Hodgkin-Katz unit scale | 1e-9 | 1e9 |
| _R_ | Gas Constant | 8314.0 | mV.C/K/mol |
| KMOLE | Flux unit conversion | 1.0/602.0 | uM_um3_per_molecules |
| K_millivolts_per_volt | voltage scale | 1000 | 1e-3 |
MIRIAM compliance
The Minimum Information Requested In the Annotation of biochemical Models (MIRIAM) is a set of standards that help researchers to reuse, modify and combine computer models of biochemical processes. MIRIAM has two parts: (1) a ‘reference correspondence’ that matches each model to its description, documenting the model’s provenance and a stable link to its full description (often a journal publication), and (2) a set of annotation schemes linking the components of the model to relevant bioinformatics resources.
Currently Virtual Cell is working towards making the model, structures, species, and reactions comply with the MIRIAM standard for annotations. An editor has been developed to allow Virtual Cell users to enter MIRIAM compliant annotations in their model components. In VCML, the MIRIAM annotations are stored (in the 'rdf' format) in the annotation element of the corresponding element.
Description of VCML
VCML Containter
VCML can have a 
BioModel
A Virtual Cell Biomodel, represented by the 
A <BioModel>
Version
The Version of a Biomodel or any Virtual Cell entity that has a Version represents the version information for the entity, such as the the key value in the biomodel database table, a description string, date and time of creation, owner, whether the entity is archived or not, etc. The version of a Biomodel is automatically created when a biomodel (and the other model entities) are created and saved. In the VCML, the
The <Version> element has the following attributes of type String:
Name : the name of the versionable entity
KeyValue : the database table key value of the entity
BranchId: this attibute is a marker for a group of related versioned models. All entities with the same branchId are versions of the same model.
Archived : represents the VersionFlag of the versionable entity. It can take one of 3 values: '0' represents Current which is the default/normal flag setting; '1' represents Archived which prevents users from deleting the entity; '3' represents Publish which indicates that the model/entity has been archived and published (in extenal publications) and is used internally to deter administrators from deleting the model from database. (Note: a value of '2' represents Unchanged which is not used any longer).
Date : Date of the last save of the entity in "dd-MM-yyyy HH"mm:ss" format.
FromVersionable : a boolean that represents if the entity comes from a versionable entity.
In addition, the <Version> element contains the following elements:
<Owner> : Represents the owner of the versionable element. This element has the following attibutes of type String: Name of the owner, and Identifier is an number that represents the key value of the owner in the Virtual Cell database.
<GroupAccess> : This element represents the accessibility/visibility of the entity for other users. It has a Type attribute which can have a value of '0' to indicate no group access (entity is 'private' and not shared); or a value of '1' which indicates group access to all (shared with all users of the Virtual Cell, or 'public' access), or a an arbitrary value representing a group id (access to the entity is allowed to some of the users). If the group access type is for some users, the <GroupAccess> element has an additional attibute Hash which contains a hash key. In this case, the <GroupAccess> element also has a list of <User> elements that represent the list of users that have access to the entity. Each <User> element contains the attributes of type String: Name of User; KeyValue of User in the Virtual Cell database; Hidden, which is a boolean value (true indicates that the User is hidden; false implies User is a normal user).
<Annotation> : This element contains the annotaion string of the versionable entity.
<ParentSimRef> : This element is present only if the versionable entity is a Simulation. This has an attribute KeyValue tthat represents the keyvalue of the parent simulation (when only the name and nothing else is chnaged in a simultion that has been run and has results, the simulation should not be run again. This key value allows the results to be obtained from the original (parent) simulation).
Model
A Model describes the physiology of the
biological model : the cellular structures or compartments (called
Feature for 3D and Membrane for
2D), species (called LocalizedCompound for a
species and Compound for a species type), and
reactions (called SimpleReaction for a biochemical
reaction and FluxStep for a transport). A example
VCML code for a model is as shown:
UML representation of a physiological model:
A <Model> element has a required Name attribute of type String - if one is not provided, it uses a default name of 'unnamed_model'. The <Model> element has an optional <Annotation> element that contains a description of the model. It contains one or more structure elements - <Feature> and <Membrane> elements - which represent the compartments of a cell; one or more <Compound> elements; one or more <LocalizedCompound> elements; zero or more <SimpleReaction> and <FluxStep> elements (which describe simple reactions or fluxes); one or more <Diagram> elements. A <Model> element also has a <ModelParameters> element and <Version> element (which contains necessary version information about the model).
The <Compound> element in VCML represents species in a model, and <LocalizedCompound> element represents species contexts (species with their associated compartments). LocalizedCompound is equivalent to Species in SBML, and Compound is roughly equivalent to SpeciesType in SBML. Unlike SBML, the number of LocalizedCompounds should equal the number of Compounds.
Features and Membranes
A physiological model is defined across specific cellular
features that are mutually exclusive compartments within the cells,
as well as the membranes that separate them. All features and
membranes can contain molecular species and a collection of
reactions that describe the biochemical behavior of those species
within or adjacent to that feature or membrane.
A <Feature> element represents a 3-dimensional volumetric compartment. A <Membrane> element represents a 2-dimensional surface (or Membrane) separating Features. The Name and KeyValue fields, both of type String, are common for <Feature> or <Membrane> elements. In the case of <Membrane> element, a few additional fields (all of type String) are defined : the InsideFeature - indicates the name of the feature which the membrane encloses; OutsideFeature - indicates the name of the feature that encloses a membrane; and the MemVoltName field that represents the name of the voltage across the membrane. Note that each feature (except the most outer) must have a membrane, and each membrane must separate two features.
Compound
A <Compound> element represents the molecular
species type - any distinct state necessary to describe the
biochemistry of the cell, for example, molecular conformation,
receptor bound versus receptor unbound. A species (compound) can be
separately defined in multiple compartments. The species are
described by concentration and diffusion constants when associated
with a compartment (volume species), and surface densities when
associated with a membrane (membrane species). Species can
participate in reactions, fluxes, and diffusion. Species diffusion
is defined separately for each cellular compartment or membrane, and
is specified by diffusion constants. Species may have directed
motion along filaments, there may be a flux of species through a
membrane separating two neighboring compartments and species may be
involved in binding reactions between compartments or membranes.
A <Compound> element has a required Name attribute and an optional <Annotation> element, both of type String. In addition, the <Compound> element contains a <DBSpecies> element which links the compound with an existing database species, molecule, enzyme or compound.
Localized Compounds
A <LocalizedCompound>
A
Diagram
A <Diagram> element represents the reaction
network in a structure (compartment) - it has shapes (icons) for
localized compounds, simple and flux reactions. The UML diagram for
<Diagram> element is shown below:
Model Parameters
Global parameters in the Virtual Cell are represented by the
<ModelParameters> element in the <Model>
element. The <ModelParameters> element contains a list of
<Parameter> elements; each containing the
expression for the parameter and having the following attributes of
type String : a Name representing the name of the
parameter, a Role attribute representing the parameter role
(reaction rate or inward current density or user-defined), and a
Unit representing the name of the units of the parameter. These
parameters can be global constants or functions of other global
parameters or of model species. Note: when using species in
global/model parameter expressions, the speciesContext name (the
LocalizedCompound name), should be used.
The biochemical reactions represent complete descriptions of reaction stoichiometry and kinetics. Reactions can be either a collection of related reaction steps occurring at or near a single structure (e.g. membrane receptor binding, cytosolic calcium buffering), or transmembrane fluxes (e.g. flux through an ion channel). Each reaction is associated with a single cellular structure. The stoichiometry of a reaction is defined in terms of reactants, products, and catalysts, which are related to species in a particular cellular structure. It should be pointed out that reaction in a compartment involve only those species within that compartment, whereas reaction on a membrane involve the species on that membrane as well as the species present in the compartments neighboring the membrane. Numerically, the reaction rates and fluxes are represented symbolically by arbitrary algebraic expressions in terms of parameters and species concentrations.
The element representing a Reaction in VCML is either a <SimpleReaction> element (representing a reaction in a 3-d compartment or membrane) or a <FluxStep> element representing a flux reaction on a membrane. Both these elements can contain an optional <Annotation> element.
Simple Reaction
A SimpleReaction contains the reaction
participants - zero or more reactants, zero or more products and
zero or more catalysts/modifiers of the reaction and the kinetics of
the reaction. Reactants/products/modifiers refer to species in a
given compartment - LocalizedCompound. It must be noted
that there must be at least one reactant or one product for a
reaction. The <SimpleReaction> element has the
following attributes of type String : Name that indicates
the name of the reaction; Structure that represents the
Feature or Membrane in which the reaction takes place;
FluxCarrierValence represents the value of the charge carrier
valence; the FluxOption field indicates if the flux option
is molecular only, molecular and electrical or electrical only (MLB:
explain ); KeyValue is the database key value of the simple
reaction object. The <SimpleReaction> element also contains
the <Kinetics> element which represents the
kinetics of the reaction. below is the UML diagram and a VCML
example to illiustrate a <SimpleReaction>:
Flux Step
A FluxStep is associated with a single membrane
and describes the flux of a single compound through that membrane.
The flux compound must be a compound that is present in both
neighboring compartments. A single inward flux is defined by
convention (uM*um*s-1) and enforces flux conservation across the
membrane. The flux is a function of flux carrier and catalyst
concentration in the membrane's neighboring compartments and of
membrane bound catalyst surface density. A <FluxStep>
element has the attributes Name, Structure, FluxCarrierValence,
FluxOption and KeyValue similar to the
<SimpleReaction> element. In addition, it contains another
attribute of type String - FluxCarrier, which represents
the name of the species that is the flux carrier for the flux
reaction. The <FluxStep> element also contains the
<Kinetics> element (representing the kinetics of the flux
reaction) and zero or more catalysts/modifiers for the flux
reaction. The following UML diagram and VCML code represents a
<FluxStep>:
Kinetics
The <Kinetics> element represents the reaction
kinetics. Virtual Cell supports any user-specified kinetics (as
General kinetics), and certain pre-defined kinetics (Mass-Action,
Henri-Michaelis-Menten reversible and irreversible) for volume
reactions. For flux reactions, the user can specify an arbitrary
flux or use pre-defined General Current Density,
Goldman-Hodgkin-Katz Permeability and Nernst Conductance kinetics
options. Shown below is a VCML sample for the <Kinetics> element:
The<Kinetics> element in VCML has a KineticsType attribute of type String that represents the name of one of the kinetic types supported by the Virtual Cell (mentioned above). It also has a list of <Parameter> elements; each containing the expression for the parameter and having the following attributes of type String : a Name representing the name of the parameter, a Role attribute representing the parameter role (reaction rate or inward current density or user-defined), and a Unit representing the name of the units of the parameter. The parameter role inward current density is not defined for a reaction in a Feature (3-d compartment), it is defined only for reaction on a Membrane (2-d compartment).
SimulationSpec
A SimulationSpec is the VCML representation of
an Application in the Virtual Cell, which establishes the
association between a biological model, a geometry properly mapped
to the biology, initial conditions, mathematical description,
simulations and analysis. The <SimulationSpec>
element has the following attibutes of type String : Name
representing the name of the SimulationSpec or application,
Stochastic which can take the value true or
false indicating if the SimulationSpec is stochastic
or not, an optional CharacteristicSize which indicates the
characteristic size of the geometry image. In addition, the element
contains an optional <Annotation> element of type
string that stores a description of the SimulationSpec; a
<Geometry> element that stores the geometry associated with the
SimulationSpec; a <GeometryContext> element to
represent the geometric mapping; a required
<ReactionContext> element to represent the
parameter/variable mapping; an optional <ElectricalContext>
element that contains the <ElectricalStimuli> and
the <GroundElectrode> elements for applications
with electrophysiology; an optional <MathDescription>
element; a list of <Simulation> elements, if
present; an optional list of <AnalysisTask>
elements (tasks set up for parameter estimation); a
<Version> element that contains the version information of
the SimulationSpec. The following figures show the UML
representation and a VCML example of the <SimulationSpec>
element:
Geometry
Each Virtual Cell model requires a detailed description of the
cellular geometry to represent the behavior of the cellular system.
A geometric model represents the morphometry of a particular cell,
or a portion of a cell. A typical cell contains various structures
that can span a few orders of magnitude in scale. The geometry may
be captured by various imaging modalities such as wide field,
confocal, or electron microscopy. The decision to include small
structures, i.e. intracellular mitochondria, depends on the ability
to experimentally resolve such anatomical structures and the spatial
scale of interest. Internal structures that are included in the
physiological model, but are not spatially resolved, may be mapped
continuously (distributed) as a volume fraction of the enclosing
compartment. In order to properly define a simulation domain, the
geometry must be specified as 2-D or 3-D segmented images (based on
pixel intensity) with the appropriate scaling information (pixel
size defined in microns). Segmentation is necessary to establish the
discrete regions that represent the anatomical features of interest.
Membranes are implicitly represented as the boundary between
dissimilar compartments. For very regular structures or symmetric
cells, analytic geometry may be used to define the cell geometry
instead of experimental images. It must be stressed that the
simulation domain must still be defined.
A <Geometry> element in VCML has a Name and Dimension attributes and contains an optional <Annotation> element, an <Extent> element and <Origin> co-ordinates, <Image> (if it is a spatial geometry), a <Subvolume> element, a <SurfaceDescription>, if present, and the <Version> element that contains the version information for the <Geometry> element. The <Geometry> element in the Virtual Cell is represented by the following UML diagram:
The VCML code for a spatial geometry is as shown:
Dimension attribute of type String represents the dimension of the geometry (0, 1, 2 or 3).
<Annotation> : optional, of type String, contains the description of the geometry if present.
<Extent> : contains 'X', 'Y', 'Z' string attributes indicating the extent of the geometry.
<Origin> : contains 'X', 'Y', 'Z' string attributes indicating the origin of the geometry.
<Image> : present if geometry is spatial. This element represents a segmented image of n colors where there are n classes of volumetric compartments. This element has a Name attribute of type String and an optional <Annotation> element of type String. It contains an <ImageData> element that has attributes X, Y, Z for the x, y, z extent of the image and the CompressedSize attribute that specifies the compressed size of the image; and contains the encoded compressed pixels of the image. The image element also has an optional <Version> element with the version details of the image; and a list of <PixelClass> elements depending on the number of regions in the image; each <PixelClass> element has String attibutes : Name - indicating the name of the pixelclass or image region, ImagePixelValue representing the integer pixel value, and an optional Key attribute containing the database keyvalue for the pixelclass.
<Subvolume> : The list of subvolumes elements in the geometry can be of one of the following types : AnalyticSubVolume, CompartmentSubVolume or ImageSubVolume. The three subvolume type elements each have the following attributes of type String : Name - indicating the name of the subvolume (region) in the geometry; Handle denoting the handle of the subVolume; Type which can be Analytic, Compartmental or Image; and KeyValue - representing the database keyvalue of the subvolume. In addition, if the subvolume type is AnalyticSubVolume, the <Subvolume> element contains an <AnalyticExpression> child element that contains the analytic expression for the subvolume; and if the subvolume type is ImageSubVolume, the <Subvolume> element contains the attribute ImagePixelValue representing the integer pixel value.
<SurfaceDescription> : refer to the section on SurfaceDescription below.
<Version> : represents the version of the geometry object (creation date and time, key value in the database, description of geometry, etc)
Surface Description and Regions
SurfaceDescription is a representation of the
surface of the geometry. It is a collection of all the surface
elements between the individual subvolume regions of the geometry.
The <SurfaceDescription> element has the following
attributes of type String : NumSamplesX, NumSamplesY,
NumSamplesZ which indicate the x, y, z parameters of the size
of the surface; CutoffFrequency which represents the filter
cutoff frequency of the surface. In addition, the
<SurfaceDescription> contains a list of geometric regions which
can be MembraneRegions or VolumeRegions.
<MembraneRegion> element represents a surface Geometric Region. It contains the following attributes of type String : Name of the membrane region; the VolumeRegion_1 and VolumeRegion_2 attributes indicating the adjacent volume regions for the membrane; Size attribute for the membrane region, if it is set; and the Unit attribute that represents the units of the size.
<VolumeRegion> element represents a volume Geometric Region. It contains the following String attributes : Name of the volume region; RegionID representing the integer region ID for the volume region; SubVolume representing the subVolume name; Size containing the size of the volume region, if it is set; and and the Unit attribute that represents the units of the size.
GeometryContext
The <GeometryContext> element maps features and
membranes to geometrical objects defined in Geometry. The
<GeometryContext> element contains a list of
<FeatureMapping> (for a volumetric compartment) and
<MembraneMapping> (for a membrane) elements. The following
figure is the UML representation of the <GeometryContext>
element:
A <FeatureMapping> element has the following attributes of type String : Feature represents the name of the feature (3-d compartment), Subvolume represents the name of the subvolume, Resolved indicates if the feature is resolved or not, Size contains the size of the feature if it is set. In addition, the <FeatureMapping> element contains a <BoundariesTypes> element, which contains the attributes (String) Xm, Xp, Ym, Yp, Zm, Zp - each of which can be set to Flux or Value - positive and negative values X, Y, Z boundary conditions.
A <MembraneMapping> element has the following attributes of type String : Membrane represents the name of the membrane; SurfaceToVolumeRatio, VolumeFraction, Size contain the expressions for the surface-to-volume ratio, volume fraction and size parameters, if they are set; CalculateVoltage attribute that has values of true or false indicating if voltage should be calculated or not; SpecificCapacitance and InitialVoltage that contain the expressions for specific capacitance and initial voltage, if present (default values of 1.0 and 0.0 respectively).
ReactionContext
A <ReactionContext> element represents the
reaction mappings in VCML. It contains a list of
<LocalizedCompoundSpec> elements and a list of
<ReactionSpec> elements. The UML representation of a
<ReactionContext> element is shown below:
A <LocalizedCompoundSpec> element has the following attibutes of type String : LocalizedCompoundRef which is the name of the corresponding LocalizedCompound, ForceConstant which indicates if a concentration of LocalizedCompound is constant or not, EnableDiffusion which indicates if the LocalizedCompound has diffusion enabled or not. The <LocalizedCompoundSpec> element also contains an <Initial> element that contains the initial expression for the LocalizedCompound. If the SimulationSpec (application) is spatial, the <LocalizedCompoundSpec> element also has a <Diffusion> element that contains the diffusion rate for the speciesContext; and a <Boundaries> element which has attributes (of type string) Xm, Xp, Ym, Yp, Zm, Zp values for the LocalizedCompound (+ve and -ve values X, Y, Z boundary conditions).
A <ReactionSpec> element has two attributes of type String : ReactionStepRef the represents the name of the ReactionStep (reaction), and ReactionMapping has one of the following options : included, excluded, fast, molecular only, current only (representing if the reaction is included, excluded, fast, etc.).
Reaction mapping is a way for the user to specify the subset of reactions that have fast kinetics and the fast system will automatically be generated and integrated into the mathematical description by selecting or deselecting the option. The Virtual Cell software has been designed based on the separation of fast and slow kinetics, because there is often a wide range of time scales in interrelated cellular processes that pose a problem when computing numerical solutions. Structure mapping is used to establish the relationship between the BioModel and Geometry documents. In the compartmental model, the structures defined in the model description are mapped to a single compartment. A compartmental application (SimulationSpec) represents a single point simulation that is based on the defined physiological model and the geometric assumptions, the Surface to Volume Ratios and Volume Fractions. In a spatial application, each mutually exclusive volumetric region in the geometry is mapped to a single compartment and an interface separating any two regions is mapped to the corresponding membrane. A compartment that is not spatially resolved in the geometry may be considered continuously distributed within the geometric region of its parent compartment. Even though a region is described as being continuous it does not have to be uniformly distributed within its parent compartment.
Math Description
The MathDescription describes the class of
mathematical systems that are encountered in the Virtual Cell. It is
represented by the Virtual Cell Math Description language (VCMDL),
which is a declaritive mathematics language. This language defines
parameters, independent variables, differential/algebraic systems
defined over a complex geometry including discontinuous solutions
and membrane boundaries and the description of the task to perform
on such a system. The following figure is the UML representation of
the <MathDescription> element:
The <MathDescription> element has Name attribute and <Annotation> element of type String. It also has a <Version> element wihch contains necessary version information about the math description. The <MathDescription> element also contains lists of constants, variables, functions and Subdomains (refer to the next sections for further details). An example VCML for a MathDescription is shown below:
Variables
Variables represent the variables used in the Virtual Cell Math
Description Language (VCMDL). A Variable can be one of the following
types :
Constant
A <Constant> element represents a constant in
the math description, for example, initial conditions for species,
built in Virtual Cell constants (e.g., Faraday's constant,
Temperature in Kelvin, Gas constant, etc.) or other user-defined
constants in reactions. The <Constant> element has a
Name attribute of type String and contains the constant value
in an expression.
Function
VolumeRegionVariable
MembraneVariable
MembraneRegionVariable
CompartmentSubDomain
A CompartmentSubDomain also contains a list of Equations ( <PdeEquation> and <OdeEquation>, representing the equations that are generated from the geometric mapping of the model), a fast system, if any; and if the model is stochastic, a list of <VariableInitialConditions> and <JumpProcesses>.
A MembraneSubDomain also has a list of equations ( <PdeEquation> and <OdeEquation>), a fast system, if any; and a list of <JumpConditions>.
OdeEquation
PDeEquation
JumpCondition
FastSystem
VolumeRegionEquation
MembraneRegionEquation
Electrical Context
An <ElectricalContext> element specifies the
Membrane Potential Options and Electrical Stimulus that can be
applied to flux reactions. The Membrane potential options table
lists the membranes in the biomodel and the user has the option of
specifying the initial voltage (V_initial) and the specific
capacitance of each membrane. The user can choose between three
options for the applied electrical stimulus: no clamp, voltage clamp
or current clamp. Electrical Mapping is available in both Spatial
and Compartmental models. In Compartmental models the user cannot
specify clamp or electrode position. The UML diagram for
<ElectricalContext> is as shown below:
ElectricalStimuli : This can be either a VoltageClampstimulus or a CurrentClamp stimulus. The ElectricalStimuliis represented by the <Clamp> element which has an attribute Type of type String that indicates if it is voltage or current clamp. It also contains an <Electrode> element and a list of <Parameters> (electrical stimulus Parameters). The <Electrode> element has a Feature attribute of type String that represents the name of the feature where the electrode is located, and contains the <Coordinate> element that has attributes X, Y, Z indicating the x, y, z coordinates of the electrode position. Each <Parameter> element has the attributes (of type String) Name for paramter name; Role indicating the parameter role (voltage, current or user_defined); and Unit representing the parameter units; and contains the parameter expression.
<GroundElectrode> : This element represents the ground electrode property of the electrical mapping. The <Electrode> element is the same as decscribed above, containing the Feature attribute with the name of the feature where the ground electrode is located and containing the <Coordinate> element representing the position coordinates of the ground electrode.
Simulations
Once the biomodel and application(s) or the mathmodel have been
set up, simulations can be created and run. The appropriate solvers
for non-spatial (ODE) and spatial models (PDE) will automatically be
implemented based on the mathematical description. The non-spatial
simulation executes a single point simulation based on the defined
physiological model and the geometric assumptions, surface-to-volume
rations and volume fractions. The ODEs for for single point
approximations, representing the reactions kinetics are generated
and passed to an interpreted ODE solver. This system of equations is
solved using one of a variety of integration schemes. For a spatial
model, the Math Description consists of PDEs that correspond to
diffusive species and ODEs for non-diffusive species.
The <Simulation> element has a Name attribute of type String and an optional <Annotation> element of type String that contains a description of the simulation. In addition, it contains the following elements : <SolverTaskDescription>, <MathOverrides>, <MeshSpecification>, <Version>. The <Version> element contains version information for the simulation, namely, database keyValue, creation date and time, description, etc. A UML diagram and an example VMCL code for <Simulation> is shown below:
SolverTaskDescription
The <SolverTaskDescription> element describes
the solver-related specifications such as the time bounds, time
step, error tolerance, solver type, etc. It has the following
attributes of type String : TaskType that can take the
values Steady or Unsteady and indicates if the
simulation represents the system in steady state or not;
UseSymbolicJacoboan that can take values of true or
false to notify that the solver uses Symbolic Jacobian; and
SolverName that contains the name of the solver. For a
non-spatial simulation, the possible solver type values are :
Forward Euler, Runge-Kutta (Second Order, Fixed Time Step),
Runge-Kutta (Fourth Order, Fixed Time Step), Runge-Kutta-Fehlberg
(Fifth Order, Variable Time Step), Adams-Moulton (Fifth Order, Fixed
Time Step), IDA (Variable Order, Variable Time Step, ODE/DAE), CVODE
(Variable Order, Variable Time Step). For a spatial simulation, the
possible solvers are : Finite Volume, Regular Grid, Finite Volume
Standalone, Regular Grid; and for a stochastic simulation, the
possible solvers are : Gibson, Hybrid (Gibson + Euler-Maruyama
Method), Hybrid (Gibson + Milstein Method), Hybrid (Adaptive Gibson
+ Milstein Method). In addition, the <SolverTaskDescription>
has the following elements :
<TimeBounds> : This element has the attributes StartTime and EndTime of type string, that specifies the start and end times for the simulation.
<TimeStep> : This element has the attributes MinTime, DefaultTime, and MaxTime which represent the minimum time step (default value 1e-8), default time step (0.1), and maximum time step (1.0).
<ErrorTolerance> : This element has the attributes Absolute and Relative that contain values for the absolute (default 1e-9) and relative (default 1e-9) error tolerances.
<OutputTimeSpec> : This element represents the times at which output is calculated. It can be of 3 types : default, explicit or uniform. If it is default, it has the followng attibutes : KeepEvery and KeepAtMost, which specify the points at which the output is retained and maximum number of output values to be retained in the result set. If the OutputTimeSpec is explicit, it has the arrtibute OutputTimes that contains a comma or space separated list of time points at which output values have to be computed. If the OutputTimeSpec is uniform, it has the attribute OutputTimeStep that contains the uniform time interval between the start and end times of the simulation at which the output values have to be computed - this option is useful for variable time step solvers when it is required to compute output values at fixed time steps.
<StochSimOpton> : This element is present if the simulation is stochastic. It has the following attributes of type String : UseCustomSeed which can be true or false indicating if the simulation uses a custom seed or not; if UseCustomSeed attribute is 'true', the <StochSimOption> has the attibute CustomSeed which contains the value of the custom seed; NumberOfTrial attribute that contains the number of trials for the stochastic simulation; and if the stochastic solver is hybrid, it has the following attributes : Epsilon, Lambda, MSRTolerance, SDETolerance.
<SensitivityParameter> : This element is present in the SolverTaskDescription only if sensitivity analysis has been enabled for the simulation. It is the same as a Constant element, and has a Name attribute representing the name of the sensitivity parameter and contains the parameter expression value.
MathOverrides
The <MathOverrides> element of Simulation
contains the parameters of the model that have been overridden for
this simulation. It contains a list of <Constant>
elements (as described previously, with a Nameattribute and
containing the constant expression/value), each item in the list
corresponding to an overridden parameter in the simulation. If the
overridden parameter is a scan (multiple override values for same
parameter), that <Constant> element has another attribute
in addition to Name, ConstantArraySpec, which can
have a value of 1000 if it is an explicit list of values (e.g., 0.0,
0.2, 0.5, 1.0) or 1001 if the scan values are in an interval (e.g.,
0.0 to 1.0, 5 values); and instead of containing a single
expression/value for the parameter, it will contain the list or the
interval of values.
MeshSpecification
The <MeshSpecification> element of Simulation is
available only for spatial simulations, It contains the size of the
mesh or the grid points in the spatial geometry where the solution
is to be computed. This element contains the element <Size>
which has attributes X, Y, Z that specify the mesh size in
the x, y, z directions (for a 2-d geometry, only x and y are
specified).
Analysis Task
An AnalysisTask represents the parameter
estimation task that can be run in a Virtual Cell application.
Currently, parameter estimation in the Virtual Cell is allowed only
for non-spatil applications (or SimulationSpecs). If
parameter estimation is present in a given Virtual Cell application,
the <SimulationSpec> element contains an
<AnalysisTaskList> element. The UML diagram for the
<AnalysisTaskList> element is as shown below:
MathModel
A MathModel (stands for Mathematical Model)
element allows a biological model to be specified as a class of
mathematical systems using the Virtual Cell Math Description
Language (VCMDL), a declarative mathematics language. This language
defines parameters, independent variables, differential/algebraic
systems defined over a complex geometry including discontinuous
solutions and membrane boundaries, and the description of tasks to
be performed on such a system. The figure below shows a UML diagram
for a mathematical model:
A <MathModel> element is similar to <BioModel> element in that it has a required attribute Name used to identify a model. It can have an optional <Annotation> child, used to store a description of the mathematical model. It also contains the following elements : a <Geometry> element that represents the geometry of the model; a <MathDescription> element that describes the mathematical system that represents the model; a list of <Simulation> elements, if present; and a <Version> element that contains the version information for the model. The attibutes and contents of these elements are the same as those defined for these elements in the Biomodel.
| Technology | Modeling Process | ||
| Software Architecture | Modeling Framework | ||
| Math Framework | User Interface | ||
| Testing Framework | VCML Specification |
