The VCML Specification Version 0.4

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://projects.sourceforge.net/vcell/

Overview

-- IonMoraru - 24 Jul 2007

• Diagram1.dia: Diagram for VCML

• image for VCML diagram:
  

Preliminary Definitions and Principles

VCell Database Metadata

Unit Representation and Built-in Unit System

Units in the Virtual Cell are not explicitly specified in VCML. 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
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 (infix vs. MathML^?)

VCML Symbols and Scoping Rules (Namespace, Name, Expression, Units)

Math namespace, Bio namespace

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.

VCML Components

VCML Container

BioModel^? Element

The Biomodel element consists of all the necessary information needed to define the biological model,.i.e., compartments, species, reactions, fluxes and Applications and Geometry. Below is an XML data object representing a full model :

• UML diagram for Biomodel:
  

A BioModel element has a required Name attribute of type String which identifies the biomodel. A biomodel can have an optional Annotation child which is of type String - it is used to store useful information about a model such as any notes that the creator of the model wishes to add to indicate what the model represents. A biomodel is the container for a physiological model (which is described in the VCell code base by Model) and one or more experimental set-ups referred to by users as Applications and internally in the VCell code base as SimulationContext and in VCML as SimulationSpec. The required Version child of the biomodel stores version information for the biomodel, such as the the key value in the biomodel database table, a description string, date and time of creation, etc. (the Version element is automatically created when a biomodel is created and saved). For models that have MIRIAM annotation, there is an additional annotation element which stores the MIRIAM annotation in the rdf format.

MathModel^? Element

A MathModel^? element allows a biologocal model to be specified as a class of mathematical systems using the Virtual Cell Math Description Language (VCMDL), which is 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 MathModel^?:

* UML diagram for Mathmodel:

A MathModel element has a required attribute Name of type String which is used to identify the mathmodel. It can have an optional Annotation child (of type String), used to store a description of the mathmodel. The mathmodel also contains the following elements : a Geometry element that represents the geometry of the mathmodel; 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 mathmodel.

Physiology (Model)

A Model element describes the physiology of the biological model - the compartments, species, and reactions. A example VCML code for a model is as showb:

* UML representation of a physiological model:

A Model 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 child that contains a description of the model. It contains one or more Structure elements which represent the compartments of a cell; one or more Species elements; one or more SpeciesContext elements (as many SpeciesContexts^? as there are Species); zero or more ReactionStep elements (which describe simple reactions or fluxes); one or more Diagram elements. A Model element also has a Version element which contains necessary version information about the model.

Structures (Compartments)

A physiological model is defined as a collection of biochemical reactions acting on a set of molecular species localized in specific cellular structures. The cellular structures are defined as mutually exclusive compartments within the cells, as well as the membranes that separate them. The compartments represent three-dimensional volumetric regions called Features while the membranes represent two-dimensional surfaces separating the compartments. All structures can contain molecular species and a collection of reactions that describe the biochemical behavior of those species within that structure.

A Structure can be a 3-dimensional compartment or Feature element or a 2-dimensional Membrane element. The Name and KeyValue fields, both of type String, are common for Feature or Membrane structure elements. In the case of Membrane structure 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.

Reactions

The biochemical reactions are objects that 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 step is associated with a single cellular structure. The stoichiometry of a step 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 steps in a compartment involve only those species within that compartment, whereas reaction steps 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 Reaction element in VCML is either a SimpleReaction element (representing a reaction in a 3-d compartment or membrane) or a FluxReaction element representing a flux reaction on a membrane. Both these elements can contain an optional 'Annotation'.

Simple Reaction

A SimpleReaction^? element has the following attributes of type String : Name that indicates the name of the reaction; Structure that represents the structure 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; KeyValue is the key value of the simplereaction object. The SimpleReaction^? element 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. It must be noted that there must be at least one reactant or one product for a reaction. The following VCML example illiustrates a SimpleReaction^?:

Flux Reaction

Fluxes are associated with a single membrane and describe the flux of a single species through that membrane. The flux species must be a species 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 an arbitrary function of flux carrier and catalyst concentration in the membrane's neighboring compartments and of membrane bound catalyst surface density. A FluxReaction^? 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 FluxReaction^? also contains the kinetics of the reaction and zero or more catalysts/modifiers for the flux reaction. The following VCML code represents a FluxReaction^?:

Kinetics

Kinetics represents the reaction kinetics. Virtual Cell supports General, MassAction^?, Henri-Michaelis-Menten (reversible) and Henri-Michaelis-Menten (irreversible) for volume reactions and General Mass Flux, General Current Density, Goldman-Hodgkin-Katz Permeability and Nernst Conductance for membrane reactions.

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

Species

A Species element represents the molecular species - any distinct state necessary to describe the biochemistry of the cell, for example, molecular conformation, receptor bound versus receptor unbound. The species 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 Species element has a required Name attribute and an optional Annotation attribute, both of type String. In addition, the Species element contains a DBSpecies element which links the species with an existing database species, molecule, enzyme or compound.

SpeciesContexts^?

A SpeciesContext^? represents the instance of a species in a particular compartment. It references the species and the structure in which the species is located. When used in an expression, a speciesContext that is in a volume will take the value of the volumetric concentration (expressed in uM) and if the speciesContext is on a membrane, it takes the value of surface density (expressed in molecules/um2).

A SpeciesContext element has the following required fields : Name of type String which specifies the name of the SpeciesContext^?; SpeciesRef of type String which indicates the Species with which this SpeciesContext^? element is associated; Structure of type String which indicates the name of the compartment in which the SpeciesContext^? is located; a boolean HasOverride field which, if true, indicates that the speciesContext name has been overridden, and if false, indicates that the speciesContext name cannot be overridden; a KeyValue field of type String which contains the key value of the SpeciesContext^?.

Geometry

Each model that is developed 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.

The Virtual Cell geometry has a GeometrySpec and a SurfaceDescription. A GeometrySpec^? is a container for the geometry dimension, extent and origin co-ordinates, image (if it is a spatial geometry), and subvolumes. The VCML code for a spatial geometry is as shown:

A Geometry element in VCML has a Name attribute of type String which denotes the name of the Geometry. Dimension attribute of type String represents the dimension of the geometry (0, 1, 2 or 3). The geometry element contains the following elements : an optional Annotation element, the Extent and Origin elements, an Image element, if the geometry is spatial, a list of SubVolume elements, a SurfaceDescriptionElement, if present, and the Version element.

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 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, the AnalyticSubVolume^? also contains an AnalyticExpression child element that contains the analytic expression for the subvolume; and the ImageSubVolume^? 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

Surface description 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 SurfaceDescription^?; CutoffFrequency which represents the filter cutoff frequency of the SurfaceDescription^?. In addition, the SurfaceDescription^? contains a list of geometric regions which can be SurfaceGeometricRegions^? or VolumeGeometricRegions^?.

MembraneRegion : is the element that represents a surfaceGeometricRegion. 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 : is the element that represents a volumeGeometricRegion. 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.

Segmented Images

SimulationContext^?

A SimulationSpec^? (SimulationContext^? in the code base) is the VCML representation of an Application in the Virtual Cell, which establishes the association between a biological model and a geometry such that the geometry is properly mapped to the biology. The application consists of Structure Mapping, Initial Conditions, Reaction Mapping, Electrical Mapping, Math, Simulations, and Analysis (for parameter estimation). The following figures are the VCML and UML representations of the SimulationSpec^? object:

* UML diagram for SimulationSpec^?:

A SimulationContext^?, represented by the SimulationSpec element, has the following attibutes of type String : Name representing the name of the SimulationContext^?, StochAttr which can take the value true or false indicating if the SimulationContext^? 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 SimulationContext^?; a Geometry element that stores the geometry associated with the simulationContext; 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; 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 simulationContext element.

Initial Conditions

Initial Conditions allows user to define species concentrations, set concentrations to be fixed, and confine the concentration of a variable or variables to a certain region or regions within the model. Species concentration in the Virtual Cell are expressed in uM in volumetric compartments and in molecules/um2 on membranes.

Reaction Mappings

There is often a wide range of time scales in interrelated cellular processes that pose a problem when computing numerical solutions. The Virtual Cell software has been designed based on the separation of fast and slow kinetics. 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.

A ReactionContext^? element represents the reaction mappings in VCML. It contains a list of SpeciesContextSpecs and a list of ReactionSpecs elements.

A SpeciesContextSpec element has the following attibutes of type String : LocalizedCompoundRef which is the name of the corresponding speciesContext, ForceConstant which indicates if a speciesContext (concentration) is constant or not, EnableDiffusion which indicates if the species has diffusion enabled or not. The element also contains an Initial element that contains the initial expression for the speciesContext. If the simulationContext is spatial, the SpeciesContextSpec^? 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 speciesContext (+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.).

Structure Mappings

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 (simulationContext) 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.

The structure mappings are represented in VCML using the GeometryContext element, which is contained in the simulationContext element. The GeometryContext^? element contains a list of FeatureMapping (for a volumetric compartment) and MembraneMapping (for a membrane) elements.

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 tag that has values of true or false indicating if voltage should be calculated or not; SpecificCapacitance and InitialVoltage that contain the expressions for SpecificCapacitance^? and InitialVoltage^?, if present (default values of 1.0 and 0.0 respectively).

Boundary Conditions

For resolved Structures (compartments), there are two choices for boundary conditions Neumann (for flux) and Dirichlet (value) conditions.

Math Description

The Math Description 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 MathDescription element has Name and Annotation attributes of type String. It also has a Version element wihch contains necessary version information about the math description. The mathDescription element also contains a list of Variables and a list of Subdomains (refer to the section on Variables and Subdomains below 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

This 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 in the math description 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.

VolVariable^?

A VolVariable^? is an element that 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 volVariable 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.

MemVariable^?

A MemVariable^? is an element that represents a state variable in a membrane in the math description. A memVariable is used only in a spatial model and has a Name attribute of type String.

MembraneRegionVariable^?

A MembraneRegionVariable^? in the math description is an element that represents a membrane variable in a spatial model. A mebraneRegionVariable element has a Name attribute of type String.

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.

SubDomains^?

A subdomain is a mathematical concept that corresponds to a ... A subdomain can be a 'CompartmentSubDomain' or a 'MembraneSubDomain'.

CompartmentSubDomain^?

This 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 2 compartmentSubDomains are separated by a membraneSubDomain, the priority of the inside compartmentSubDomain must be greater than that of the outside compartmentSubDomain. It also contains bounday type elements for negative and positive X, Y, Z directions (Xm, Xp, Ym, Yp, Zm, Zp). Each boundary type element has 2 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, a fast system, if any; and if the model is stochastic, a list of VariableInitialConditions^? and JumpProcesses^?.

MembraneSubDomain^?

This 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 bounday type 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, a fast system, if any; and a list of JumpConditions^?.

Equations

The Equations element in VCML represent the equations that are generated from the geometric mapping of the model. An equation can be of the following types:

OdeEquation^?

This is a representation for 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^?

This element represents a PDE equation for a variable. Pde equations are present only in spatial models. It has a Name attribute of type String indicating the name of the Pde equation variable; a Boundaries element which has attributes (of type string) for Xm, Xp, Ym, Yp, Zm, Zp values for the variable (+ve and -ve values X, Y, Z boundary conditions); 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 velocities in the x, y, z directions.

JumpCondition^?

A JumpCondition^? is 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).

VolumeRegionEquation^?

MembraneRegionEquation^?

Electrical Mappings

Electrical Mapping 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 (Vinitial) 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 electrical mapping in an application (or simulationContext) is represented in VCML by the ElectricalContext element in the SimulationContext^? element. It contains one ElectricalStimuli element and a GroundElectrode element.

ElectricalStimuli : This can be either a VoltageClamp^? stimulus or a CurrentClamp^? stimulus. The ElectricalStimuli^? element 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 (electricalStimulusParameters). 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. 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 elemebt 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 Name attribute 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 elements 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).

Application Analysis

Field Data

Examples

XML Schema for VCML

Biomodel_VCML_Schema.xsd: XML Schema for a Virtual Cell Biomodel.

Mathematical Expression grammar