Skip to Search
Skip to Navigation
Skip to Content

University of Connecticut Health Center - Know Better Care VCell - The Virtual Cell

VCell Software Architecture

VCML Specification

Introduction

The 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 below for larger view.)

VCML

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> element (that represents a Virtual Cell biomodel) or <MathModel>  element (that represents a Virtual Cell mathmodel) as a top level element. The schema of VCML relationships is shown below:

VCML

BioModel

A Virtual Cell Biomodel, represented by the <BioModel> element, consists of a Model (represented by a <Model>  element; containing all the necessary information needed to define the biological model, i.e., compartments, species, reactions, fluxes and geometry), one or more optional experimental set-ups or Applications (containing all the necessary information on how the model is simulated, such as parameters and solver settings; represented by the <SimulationSpec> element in VCML), and auxiliary information such as <Version> and different types of annotations. Below is an XML data object representing a full model:

VCML

 

<BioModel> element has a required Name attribute of type String which identifies the biomodel. A biomodel can have an optional <Annotation> child used to store useful information about a model such as any comments that the creator of the model wishes to add to indicate what the model represents. The <Model> and <SimulationSpec> elements will be discussed in more detail in separate sections below. The required  <Version> child of the biomodel stores version information for the biomodel. For models that have MIRIAM annotation, there is an additional <annotation> element which stores the MIRIAM annotation in the rdf format. The <Biomodel> element is illustrated in the UML diagram below:

final_VCML_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 <Version> element represents the Version of the Virtual Cell model entities. The following entities have a Version : Biomodel, MathModel, Model, SimulationSpec, Geometry, MathDescription, Simulation (and hence their corresponding VCML elements will contain a <Version>  element). The <Version>  element is represented by the UML diagram below:

final_version

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:

VCML

UML representation of a physiological model:

final_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> element represents the instance of a species in a particular compartment. It references the compound and the structure in which the species is located. When used in an expression, a localized cocmpound that is in a volume will take the value of the volumetric concentration (expressed in uM) and if the localized compound is on a membrane, it takes the value of surface density (expressed in molecules/um2).

A <LocalizedCompound> element has the following required fields : Name of type String which specifies the name of the localized compound; CompoundRef of type String which indicates the compound with which this localized compound element is associated; Structure of type String which indicates the name of the compartment in which the localized compound is located; a boolean HasOverride field which, if true, indicates that the localized compound name has been overridden (changed by the user), and if false, indicates that the localized compound name has not been changed by user; a KeyValue field of type String which contains the database key value of the localized compound.

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:

final_diagram

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.

Biochemical reactions and transport
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>:

final_simple_rxn

VCML

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>:

final_flux_step

VCML

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:

VCML

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:

final_appln

XMLSimSpec

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:

final_geometry

The VCML code for a spatial geometry is as shown:

XML Geometry

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:

final_geom_context

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:

final_reaction_context

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:

final_math_desc

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:

XML_MathDesc

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
A <Function> element represents user-defined functions or functions generated for volume variables or membrane variables following the mass conservation rules during the math generation process. A <Function> element has a Name attribute of type String and contains an expression for the function.
VolumeVariable
A <VolumeVariable> element represents a state variable (species in the model) compartment in the math description. A volume variable in a spatial context has different values at different points in the volume. A <VolumeVariable> element has a Name attribute of type String.
VolumeRegionVariable
A <VolumeRegionVariable> in the math description is an element that represents a volumetric variable in a region in a spatial model. A VolumeRegionVariable has the same value within the region. A <VolumeRegionVariable> element has a Name attribute of type String.
MembraneVariable
A <MembraneVariable> element represents a state variable on a membrane in the math description. A <MembraneVariable> is used only in a spatial model and the element has a Name attribute of type String.
MembraneRegionVariable
A <MembraneRegionVariable> in the math description is an element that represents a membrane variable (species) in a spatial model. A <MebraneRegionVariable> element has a Name attribute of type String. It has a single value for a contiguous patch of membrane of the same type (membrane region), for e.g., a contiguous patch of plasma membrane. Example of MembraneRegionVariable is the membrane electric potential for the cell that is well-clamped spatially (where the mem potential is equipotential).
StochVolVariable
A <StochVolVariable> in the math description is an element that represents a stochastic variable (or species) in the model. . A <StochVolVariable> element has a Name attribute of type String. It represents a discrete valued random var that is currently integer-valued. Stochastic equations are going to be integer-valued and associated with a Poisson process.

CompartmentSubDomain
A <CompartmentSubDomain> element represents a volumetric subdomain. The <CompartmentSubDomain> element has a Name and a Priority attribute of type String. The value represented by the Priority attribute string should be such that if two CompartmentSubDomains are separated by a MembraneSubDomain, the priority of the inside CompartmentSubDomain must be greater than that of the outside CompartmentSubDomain. It also contains <BoundayType> elements for negative and positive X, Y, Z directions (Xm, Xp, Ym, Yp, Zm, Zp). Each <BoundayType> element has two attributes of type String : Boundary (which takes values of Xm, Xp, Ym, Yp, Zm, Zp depending on which boundary type element it is); and a Type which can be Dirichlet or Neumann.

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>.

MembraneSubDomain
A <MembraneSubDomain> element represents a surface (membrane) subdomain. The <MembraneSubDomain> element has an InsideCompartment and an OutsideCompartment attribute of type String, representing the names of the volumetric compartments that are inside and outside the membrane respectively. It also contains <BoundayType> elements for negative and positive X, Y, Z directions, similar to the ones defined for CompartmentSubDomain above.

A MembraneSubDomain also has a list of equations ( <PdeEquation> and <OdeEquation>), a fast system, if any; and a list of <JumpConditions>.

OdeEquation
An <OdeEquation> element represents an ODE equation for a variable. It has a Name attribute of type String which indicates the name of the variable of the Ode equation. It contains a <Rate> element and an <Initial> element. The <Rate> element contains the ODE rate expression (default value of 0.0) for the variable. The <Initial> element contains the initial value of the variable.

PDeEquation
<PdeEquation> element represents a Partial Differential Equation for a variable. PDEs are present only in spatial models. A <PdeEquation> element has a Name attribute of type String indicating the name of the PDE equation variable; an optional <Boundaries> element which has attributes Xm, Xp, Ym, Yp, Zm, Zp (of type string) that represent the positive and negative values of X, Y, Z boundary conditions for the variable; a <Rate> element containing the PDE variable rate expression (default value of 0.0); a <Diffusion> element that contains the variable diffusion rate (default value of 0.0); an <Initial> element for the initial value of the PDE variable; and an optional <Velocity> element that contains the attributes x, Y, Z that represent the velocities in the x, y, z directions.

JumpCondition
A <JumpCondition> element represents an internal flux boundary conditions for reaction diffusion equations defined over volumes at membrane boundaries. The <JumpCondition> element has a Name attribute of type String; an <Influx> element containing an expression that represents the flux moving from the membrane to the inside compartment (the compartment enclosed by the membrane); and an <Outflux> element containing an expression that represents the flux moving from the membrane to the outside compartment (the compartment enclosing the membrane).

FastSystem
A <FastSystem> element is defined in each domain that has fast reactions and represents a fast system or the set of reactions that have fast kinetics in a domain in the model. A <FastSystem> element has one or more (depending on the number of reactions that are fast) <FastInvariant> elements each of which contains the expression of the fast invariant for the reaction; and one or more <FastRate> elements each of which contains the expression of the fast rate (reaction rate) of the reaction.

VolumeRegionEquation
A VolumeRegionEquation is an equation describing the dynamics of a VolumeRegionVariable. The <VolumeRegionEquation> element representing the VolumeRegionEquation has a Name attribute for the VolumeRegionVariable. This element contains rates (<UniformRate>, <VolumeRate> and <MembraneRate> elements with default values of 0.0) that are evaluated on the region and integrated over adjacent surfaces and integrated over the volume (to look at net effects of heterogenous contributions). This is useful for infinite diffusion approximation within a volume domain. In addition, the <VolumeRegionEquation> contains the <Initial> element for the initial value expression of the VolumeRegionVariable and a <SolutionType> element which contains a Type attribute of type String (which can take a value of '0' for Unknown Solution and a value of '1' for Exact Solution). If the solution type is Exact, the <SolutionType> element contains the expression for the exact solution.

MembraneRegionEquation
A MembraneRegionEquation is an equation describing the dynamics of a MembraneRegionVariable. The <MembraneRegionEquation> element has a Name attribute (name of the MembraneRegionVariable the equation represents). element contains rate elements (<UniformRate> and <MembraneRate> elements with default values of 0.0) for rates that are evaluated on the region and integrated over adjacent surfaces and integrated over the volume. For example, all electric currents (which may not be uniformly distriubuted across the membrane) passing through the membrane are summed to determine the total current which is used to update the membrane potential. In addition, similar to the <VolumeRegionEquation>, the <MembraneRegionEquation> has an <Initial> element a <SolutionType> element.

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:

Final_Electrical_Context

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:

final_simulation

XML_Simulation

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:

final_analysis_task

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:

final_mathmodel

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.

 

The Virtual Cell, a project of NRCAM, is developed by the Center for Cell Analysis & Modeling (CCAM)