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

Detailed Description

Implementation of SBML's Parameter construct.

A Parameter is used in SBML to define a symbol associated with a value; this symbol can then be used in mathematical formulas in a model. By default, parameters have constant value for the duration of a simulation, and for this reason are called parameters instead of variables in SBML, although it is crucial to understand that SBML parameters represent both concepts. Whether a given SBML parameter is intended to be constant or variable is indicated by the value of its "constant" attribute.

SBML's Parameter has a required attribute, "id", that gives the parameter a unique identifier by which other parts of an SBML model definition can refer to it. A parameter can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specifications.

The optional attribute "value" determines the value (of type double) assigned to the parameter. A missing value for "value" implies that the value either is unknown, or to be obtained from an external source, or determined by an initial assignment. The unit of measurement associated with the value of the parameter can be specified using the optional attribute "units". Here we only mention briefly some notable points about the possible unit choices, but readers are urged to consult the SBML specification documents for more information:

  • In SBML Level 3, there are no constraints on the units that can be assigned to parameters in a model; there are also no units to inherit from the enclosing Model object (unlike the case for, e.g., Species and Compartment).

  • In SBML Level 2, the value assigned to the parameter's "units" attribute must be chosen from one of the following possibilities: one of the base unit identifiers defined in SBML; one of the built-in unit identifiers "substance", "time", "volume", "area" or "length"; or the identifier of a new unit defined in the list of unit definitions in the enclosing Model structure. There are no constraints on the units that can be chosen from these sets. There are no default units for parameters.

The Parameter structure has another boolean attribute named "constant" that is used to indicate whether the parameter's value can vary during a simulation. (In SBML Level 3, the attribute is mandatory and must be given a value; in SBML Levels below Level 3, the attribute is optional.) A value of true indicates the parameter's value cannot be changed by any construct except InitialAssignment. Conversely, if the value of "constant" is false, other constructs in SBML, such as rules and events, can change the value of the parameter.

SBML Level 3 uses a separate object class, LocalParameter, for parameters that are local to a Reaction's KineticLaw. In Levels prior to SBML Level 3, the Parameter class is used both for definitions of global parameters, as well as reaction-local parameters stored in a list within KineticLaw objects. Parameter objects that are local to a reaction (that is, those defined within the KineticLaw structure of a Reaction) cannot be changed by rules and therefore are implicitly always constant; consequently, in SBML Level 2, parameter definitions within Reaction structures should not have their "constant" attribute set to false.

What if a global parameter has its "constant" attribute set to false, but the model does not contain any rules, events or other constructs that ever change its value over time? Although the model may be suspect, this situation is not strictly an error. A value of false for "constant" only indicates that a parameter can change value, not that it must.

As with all other major SBML components, Parameter is derived from SBase, and the methods defined on SBase are available on Parameter.

Note
The use of the term parameter in SBML sometimes leads to confusion among readers who have a particular notion of what something called "parameter" should be. It has been the source of heated debate, but despite this, no one has yet found an adequate replacement term that does not have different connotations to different people and hence leads to confusion among some subset of users. Perhaps it would have been better to have two constructs, one called constants and the other called variables. The current approach in SBML is simply more parsimonious, using a single Parameter construct with the boolean flag "constant" indicating which flavor it is. In any case, readers are implored to look past their particular definition of a parameter and simply view SBML's Parameter as a single mechanism for defining both constants and (additional) variables in a model. (We write additional because the species in a model are usually considered to be the central variables.) After all, software tools are not required to expose to users the actual names of particular SBML constructs, and thus tools can present to their users whatever terms their designers feel best matches their target audience.
See Also
ListOfParameters