libSBML C API  libSBML 5.8.0 C API
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
KineticLaw_t Class Reference

Detailed Description

Implementation of SBML's KineticLaw construct.

An object of class KineticLaw is used to describe the rate at which the process defined by a given Reaction takes place. KineticLaw has subelements called "math" (for MathML content) and "listOfParameters" (of class ListOfParameters), in addition to the attributes and subelements it inherits from SBase.

KineticLaw's "math" subelement for holding a MathML formula defines the rate of the reaction. The formula may refer to other entities in a model as well as local parameter definitions within the scope of the Reaction (see below). It is important to keep in mind, however, that the only Species identifiers that can be used in this formula are those declared in the lists of reactants, products and modifiers in the Reaction structure. (In other words, before a species can be referenced in the KineticLaw, it must be declared in one of those lists.)

KineticLaw provides a way to define local parameters whose identifiers can be used in the "math" formula of that KineticLaw instance. Prior to SBML Level 3, these parameter definitions are stored inside a "listOfParameters" subelement containing Parameter objects; in SBML Level 3, this is achieved using a specialized object class called LocalParameter and the containing subelement is called "listOfLocalParameters". In both cases, the parameters so defined are only visible within the KineticLaw; they cannot be accessed outside. A local parameter within one reaction is not visible from within another reaction, nor is it visible to any other construct outside of the KineticLaw in which it is defined. In addition, another important feature is that if such a Parameter (or in Level 3, LocalParameter) object has the same identifier as another object in the scope of the enclosing Model, the definition inside the KineticLaw takes precedence. In other words, within the KineticLaw's "math" formula, references to local parameter identifiers shadow any identical global identifiers.

The values of local parameters defined within KineticLaw objects cannot change. In SBML Level 3, this quality is built into the LocalParameter construct. In Level 2, where the same kind of Parameter object class is used as for global parameters, the Parameter objects' "constant" attribute must always have a value of true (either explicitly or left to its default value).

A warning about identifier shadowing

A common misconception is that different classes of objects (e.g., species, compartments, parameters) in SBML have different identifier scopes. They do not. The implication is that if a KineticLaw's local parameter definition uses an identifier identical to any other identifier defined in the model outside the KineticLaw, even if the other identifier does not belong to a parameter type of object, the local parameter's identifier takes precedence within that KineticLaw's "math" formula. It is not an error in SBML for identifiers to shadow each other this way, but can lead to confusing and subtle errors.

Version differences

In SBML Level 2 Version 1, the SBML specification included two additional attributes on KineticLaw called "substanceUnits" and "timeUnits". They were removed beginning with SBML Level 2 Version 2 because further research determined they introduced many problems. The most significant problem was that their use could easily lead to the creation of valid models whose reactions nevertheless could not be integrated into a system of equations without outside knowledge for converting the quantities used. Examination of real-life models revealed that a common reason for using "substanceUnits" on KineticLaw was to set the units of all reactions to the same set of substance units, something that is better achieved by using UnitDefinition to redefine "substance" for the whole Model.

As mentioned above, in SBML Level 2 Versions 2–4, local parameters are of class Parameter. In SBML Level 3, the class of object is LocalParameter.