Detailed Description

The rate expression for an SBML reaction.

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

KineticLaw_t's "math" subelement for holding a MathML formula (required through SBML Level 3 Version 1, but optional as of SBML Level 3 Version 2) 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_t (see below). It is important to keep in mind, however, that the only Species_t identifiers that can be used in this formula are those declared in the lists of reactants, products and modifiers in the Reaction_t structure. (In other words, before a species can be referenced in the KineticLaw_t, it must be declared in one of those lists.)

KineticLaw_t provides a way to define local parameters whose identifiers can be used in the "math" formula of that KineticLaw_t instance. Prior to SBML Level 3, these parameter definitions are stored inside a "listOfParameters" subelement containing Parameter_t objects; in SBML Level 3, this is achieved using a specialized object class called LocalParameter_t and the containing subelement is called "listOfLocalParameters". In both cases, the parameters so defined are only visible within the KineticLaw_t (or, as of SBML Level 3 Version 2, only visible within the parent Reaction_t); 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_t in which it is defined. In addition, another important feature is that if such a Parameter_t (or in Level 3, LocalParameter_t) object has the same identifier as another object in the scope of the enclosing Model_t, the definition inside the KineticLaw_t takes precedence. In other words, within the KineticLaw_t's "math" formula, references to local parameter identifiers shadow any identical global identifiers.

The values of local parameters defined within KineticLaw_t objects cannot change. In SBML Level 3, this quality is built into the LocalParameter_t construct. In Level 2, where the same kind of Parameter_t object class is used as for global parameters, the Parameter_t 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_t's local parameter definition uses an identifier identical to any other identifier defined in the model outside the KineticLaw_t, even if the other identifier does not belong to a parameter type of object, the local parameter's identifier takes precedence within that KineticLaw_t'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.

SBML Level/Version differences

In SBML Level 2 Version 1, the SBML specification included two additional attributes on KineticLaw_t 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_t was to set the units of all reactions to the same set of substance units, something that is better achieved by using UnitDefinition_t to redefine "substance" for the whole Model_t.

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

In SBML Level 3 Version 2, the scope of the LocalParameter_t was expanded to the entire Reaction_t, instead of just the KineticLaw_t. This introduced a single new restriction: an L3v2 LocalParameter_t may not now shadow the id of any Species_t referenced by a SpeciesReference_t in the same Reaction_t. Other than that, there is no difference in any core construct. However, packages may take advantage of this new scope by adding elements to the Reaction_t that may now reference a LocalParameter_t defined in the same Reaction_t.

Examples:: createExampleSBML.c, printAnnotation.c, printMath.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
int	KineticLaw_addLocalParameter (KineticLaw_t kl, const LocalParameter_t p)
	Adds a copy of the given LocalParameter_t structure to the list of local parameters in the given KineticLaw_t structure. More...

int	KineticLaw_addParameter (KineticLaw_t kl, const Parameter_t p)
	Adds a copy of the given Parameter_t structure to the list of local parameters in the given KineticLaw_t structure. More...

KineticLaw_t *	KineticLaw_clone (const KineticLaw_t *kl)
	Returns a deep copy of the given KineticLaw_t structure. More...

int	KineticLaw_containsUndeclaredUnits (KineticLaw_t *kl)
	Predicate returning `true` or `false` depending on whether the math expression of this KineticLaw_t contains parameters/numbers with undeclared units. More...

KineticLaw_t *	KineticLaw_create (unsigned int level, unsigned int version)
	Creates a new KineticLaw_t structure using the given SBML `level` and `version` values. More...

LocalParameter_t *	KineticLaw_createLocalParameter (KineticLaw_t *kl)
	Creates a new LocalParameter_t structure, adds it to the given KineticLaw_t structures's list of local parameters, and returns a pointer to the LocalParameter_t created. More...

Parameter_t *	KineticLaw_createParameter (KineticLaw_t *kl)
	Creates a new Parameter_t structure, adds it to the given KineticLaw_t structures's list of parameters, and returns a pointer to the Parameter_t created. More...

KineticLaw_t *	KineticLaw_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new KineticLaw_t structure using the given SBMLNamespaces_t structure. More...

void	KineticLaw_free (KineticLaw_t *kl)
	Frees the given KineticLaw_t structure. More...

UnitDefinition_t *	KineticLaw_getDerivedUnitDefinition (KineticLaw_t *kl)
	Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this KineticLaw_t. More...

const char *	KineticLaw_getFormula (const KineticLaw_t *kl)
	Gets the mathematical expression of this KineticLaw_t structure as a formula in text-string form. More...

ListOf_t *	KineticLaw_getListOfLocalParameters (KineticLaw_t *kl)
	Get the list of local parameters defined for the given KineticLaw_t structure. More...

ListOf_t *	KineticLaw_getListOfParameters (KineticLaw_t *kl)
	Get the list of parameters defined for the given KineticLaw_t structure. More...

LocalParameter_t *	KineticLaw_getLocalParameter (KineticLaw_t *kl, unsigned int n)
	Get the nth parameter in the list of local parameters in the given KineticLaw_t structure. More...

LocalParameter_t *	KineticLaw_getLocalParameterById (KineticLaw_t kl, const char sid)
	Get a parameter with identifier "id" out of the list of local parameters defined for the given KineticLaw_t structure. More...

const ASTNode_t *	KineticLaw_getMath (const KineticLaw_t *kl)
	Gets the mathematical expression of this KineticLaw_t structure as an ASTNode_t structure. More...

const XMLNamespaces_t *	KineticLaw_getNamespaces (KineticLaw_t *kl)
	Returns a list of XMLNamespaces_t associated with this KineticLaw_t structure. More...

unsigned int	KineticLaw_getNumLocalParameters (const KineticLaw_t *kl)
	Get the number of local parameters defined in the given KineticLaw_t structure. More...

unsigned int	KineticLaw_getNumParameters (const KineticLaw_t *kl)
	Get the number of parameters defined in the given KineticLaw_t structure. More...

Parameter_t *	KineticLaw_getParameter (KineticLaw_t *kl, unsigned int n)
	Get the nth parameter in the list of parameters in the given KineticLaw_t structure. More...

Parameter_t *	KineticLaw_getParameterById (KineticLaw_t kl, const char sid)
	Get a parameter with identifier "id" out of the list of local parameters defined for the given KineticLaw_t structure. More...

const char *	KineticLaw_getSubstanceUnits (const KineticLaw_t *kl)
	Gets the value of the "substanceUnits" attribute of the given KineticLaw_t structure. More...

const char *	KineticLaw_getTimeUnits (const KineticLaw_t *kl)
	Gets the value of the "timeUnits" attribute of the given KineticLaw_t structure. More...

int	KineticLaw_isSetFormula (const KineticLaw_t *kl)
	Predicate returning `1` (true) or `0` (false) depending on whether the "formula" attribute of the given KineticLaw_t structure is set. More...

int	KineticLaw_isSetMath (const KineticLaw_t *kl)
	Predicate returning `1` (true) or `0` (false) depending on whether the "math" subelement of the given KineticLaw_t structure is set. More...

int	KineticLaw_isSetSubstanceUnits (const KineticLaw_t *kl)
	Predicate returning `1` (true) or `0` (false) depending on whether the "timeUnits" attribute of the given KineticLaw_t structure is set. More...

int	KineticLaw_isSetTimeUnits (const KineticLaw_t *kl)
	Predicate returning `1` (true) or `0` (false) depending on whether the "timeUnits" attribute of the given KineticLaw_t structure is set. More...

LocalParameter_t *	KineticLaw_removeLocalParameter (KineticLaw_t *kl, unsigned int n)
	Removes the nth LocalParameter_t structure from the list of local parameters in this KineticLaw_t structure and returns a pointer to it. More...

LocalParameter_t *	KineticLaw_removeLocalParameterById (KineticLaw_t kl, const char sid)
	Removes the LocalParameter_t structure with the given "id" attribute from the list of local parameters in this KineticLaw_t structure and returns a pointer to it. More...

Parameter_t *	KineticLaw_removeParameter (KineticLaw_t *kl, unsigned int n)
	Removes the nth Parameter_t structure from the list of parameters in this KineticLaw_t structure and returns a pointer to it. More...

Parameter_t *	KineticLaw_removeParameterById (KineticLaw_t kl, const char sid)
	Removes the Parameter_t structure with the given "id" attribute from the list of parameters in this KineticLaw_t structure and returns a pointer to it. More...

int	KineticLaw_setFormula (KineticLaw_t kl, const char formula)
	Sets the formula of the given KineticLaw_t structure. More...

int	KineticLaw_setMath (KineticLaw_t kl, const ASTNode_t math)
	Sets the formula of the given KineticLaw_t structure. More...

int	KineticLaw_setSubstanceUnits (KineticLaw_t kl, const char sid)
	Sets the "substanceUnits" attribute of the given KineticLaw_t structure. More...

int	KineticLaw_setTimeUnits (KineticLaw_t kl, const char sid)
	Sets the "timeUnits" attribute of the given KineticLaw_t structure. More...

int	KineticLaw_unsetSubstanceUnits (KineticLaw_t *kl)
	Unsets the "substanceUnits" attribute of the given KineticLaw_t structure. More...

int	KineticLaw_unsetTimeUnits (KineticLaw_t *kl)
	Unsets the "timeUnits" attribute of the given KineticLaw_t structure. More...

Member Function Documentation

int KineticLaw_addLocalParameter	(	KineticLaw_t *	kl,
		const LocalParameter_t *	p
	)

Adds a copy of the given LocalParameter_t structure to the list of local parameters in the given KineticLaw_t structure.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
p	a pointer to a LocalParameter_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

int KineticLaw_addParameter	(	KineticLaw_t *	kl,
		const Parameter_t *	p
	)

Adds a copy of the given Parameter_t structure to the list of local parameters in the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.
p	a pointer to a Parameter_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

KineticLaw_t * KineticLaw_clone ( const KineticLaw_t * kl )

Returns a deep copy of the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns: a (deep) copy of this KineticLaw_t structure.

int KineticLaw_containsUndeclaredUnits ( KineticLaw_t * kl )

Predicate returning true or false depending on whether the math expression of this KineticLaw_t contains parameters/numbers with undeclared units.

Returns: true if the math expression of this KineticLaw_t includes parameters/numbers with undeclared units, false otherwise.

Note: a return value of true indicates that the UnitDefinition_t returned by the getDerivedUnitDefinition function may not accurately represent the units of the expression.

See also: KineticLaw_getDerivedUnitDefinition()

Examples:: printUnits.c.

KineticLaw_t * KineticLaw_create	(	unsigned int	level,
		unsigned int	version
	)

Creates a new KineticLaw_t structure using the given SBML level and version values.

Parameters

level	an unsigned int, the SBML Level to assign to this KineticLaw_t.
version	an unsigned int, the SBML Version to assign to this KineticLaw_t.

Returns: a pointer to the newly created KineticLaw_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

LocalParameter_t * KineticLaw_createLocalParameter ( KineticLaw_t * kl )

Creates a new LocalParameter_t structure, adds it to the given KineticLaw_t structures's list of local parameters, and returns a pointer to the LocalParameter_t created.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: a pointer to a LocalParameter_t structure, or NULL if kl is NULL, or if its namepace indicates it is an SBML Level 1 or 2 object.

See also: KineticLaw_createParameter()

Parameter_t * KineticLaw_createParameter ( KineticLaw_t * kl )

Creates a new Parameter_t structure, adds it to the given KineticLaw_t structures's list of parameters, and returns a pointer to the Parameter_t created.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: a pointer to a Parameter_t structure, or NULL if kl is NULL, or if its namepace indicates it is an SBML Level 3 object.

See also: KineticLaw_createLocalParameter()

Examples:: createExampleSBML.c.

KineticLaw_t * KineticLaw_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new KineticLaw_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this KineticLaw_t.

Returns: a pointer to the newly created KineticLaw_t structure.

Note: Attempting to add an object to an SBMLDocument_t having a different combination of SBML Level, Version and XML namespaces than the object itself will result in an error at the time a caller attempts to make the addition. A parent object must have compatible Level, Version and XML namespaces. (Strictly speaking, a parent may also have more XML namespaces than a child, but the reverse is not permitted.) The restriction is necessary to ensure that an SBML model has a consistent overall structure. This requires callers to manage their objects carefully, but the benefit is increased flexibility in how models can be created by permitting callers to create objects bottom-up if desired. In situations where objects are not yet attached to parents (e.g., SBMLDocument_t), knowledge of the intented SBML Level and Version help libSBML determine such things as whether it is valid to assign a particular value to an attribute.

void KineticLaw_free ( KineticLaw_t * kl )

Frees the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

UnitDefinition_t * KineticLaw_getDerivedUnitDefinition ( KineticLaw_t * kl )

Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this KineticLaw_t.

Returns: a UnitDefinition_t that expresses the units of the math expression of this KineticLaw_t.

Note that the functionality that facilitates unit analysis depends on the model as a whole. Thus, in cases where the object has not been added to a model or the model itself is incomplete, unit analysis is not possible and this method will return NULL.

Note: The units are calculated by applying the mathematics from the expression to the units of the <ci> elements used within the expression. Where there are parameters/numbers with undeclared units the UnitDefinition_t returned by this function may not accurately represent the units of the expression.

See also: KineticLaw_containsUndeclaredUnits()

Examples:: printUnits.c.

const char * KineticLaw_getFormula ( const KineticLaw_t * kl )

Gets the mathematical expression of this KineticLaw_t structure as a formula in text-string form.

This is fundamentally equivalent to KineticLaw_getMath(). It is provided principally for compatibility with SBML Level 1.

Parameters

kl	the KineticLaw_t structure.

Returns: the formula of this KineticLaw_t structure.

See also: KineticLaw_getMath().

Note: SBML Level 1 uses a text-string format for mathematical formulas. Other levels of SBML use MathML, an XML format for representing mathematical expressions. LibSBML provides an Abstract Syntax Tree API for working with mathematical expressions; this API is more powerful than working with formulas directly in text form, and ASTs can be translated into either MathML or the text-string syntax. The libSBML methods that accept text-string formulas directly (such as this constructor) are provided for SBML Level 1 compatibility, but developers are encouraged to use the AST mechanisms. See KineticLaw_createWithMath for a version that takes an ASTNode_t structure.

ListOf_t * KineticLaw_getListOfLocalParameters ( KineticLaw_t * kl )

Get the list of local parameters defined for the given KineticLaw_t structure.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: a list of LocalParameters

ListOf_t * KineticLaw_getListOfParameters ( KineticLaw_t * kl )

Get the list of parameters defined for the given KineticLaw_t structure.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: a list of Parameters

LocalParameter_t * KineticLaw_getLocalParameter	(	KineticLaw_t *	kl,
		unsigned int	n
	)

Get the nth parameter in the list of local parameters in the given KineticLaw_t structure.

Callers should first find out how many parameters are in the list by calling KineticLaw_getNumLocalParameters().

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
n	the index of the LocalParameter_t structure sought.

Returns: a pointer to the LocalParameter_t structure

See also: KineticLaw_getNumLocalParameters().

LocalParameter_t * KineticLaw_getLocalParameterById	(	KineticLaw_t *	kl,
		const char *	sid
	)

Get a parameter with identifier "id" out of the list of local parameters defined for the given KineticLaw_t structure.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
sid	the identifier of the LocalParameter_t structure sought.

Returns: the LocalParameter_t structure with the given id, or NULL if no such LocalParameter_t exists in the given KineticLaw_t structure.

const ASTNode_t * KineticLaw_getMath ( const KineticLaw_t * kl )

Gets the mathematical expression of this KineticLaw_t structure as an ASTNode_t structure.

This is fundamentally equivalent to KineticLaw_getFormula(). The latter is provided principally for compatibility with SBML Level 1, which represented mathematical formulas in text-string form.

Parameters

kl	the KineticLaw_t structure.

Returns: the formula in the form of an ASTNode_t structure

See also: KineticLaw_getFormula().

Examples:: printMath.c.

const XMLNamespaces_t * KineticLaw_getNamespaces ( KineticLaw_t * kl )

Returns a list of XMLNamespaces_t associated with this KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

unsigned int KineticLaw_getNumLocalParameters ( const KineticLaw_t * kl )

Get the number of local parameters defined in the given KineticLaw_t structure.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: the number of LocalParameter_t structures in the given KineticLaw_t structure.

unsigned int KineticLaw_getNumParameters ( const KineticLaw_t * kl )

Get the number of parameters defined in the given KineticLaw_t structure.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.

Returns: the number of Parameter_t structures in the given KineticLaw_t structure.

Examples:: printAnnotation.c, printNotes.c, unsetAnnotation.c, and unsetNotes.c.

Parameter_t * KineticLaw_getParameter	(	KineticLaw_t *	kl,
		unsigned int	n
	)

Get the nth parameter in the list of parameters in the given KineticLaw_t structure.

Callers should first find out how many parameters are in the list by calling KineticLaw_getNumParameters().

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
n	the index of the Parameter_t structure sought.

Returns: a pointer to the Parameter_t structure

See also: KineticLaw_getNumParameters().

Examples:: printAnnotation.c, printNotes.c, unsetAnnotation.c, and unsetNotes.c.

Parameter_t * KineticLaw_getParameterById	(	KineticLaw_t *	kl,
		const char *	sid
	)

Get a parameter with identifier "id" out of the list of local parameters defined for the given KineticLaw_t structure.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
sid	the identifier of the Parameter_t structure sought.

Returns: the Parameter_t structure with the given id, or NULL if no such Parameter_t exists in the given KineticLaw_t structure.

const char * KineticLaw_getSubstanceUnits ( const KineticLaw_t * kl )

Gets the value of the "substanceUnits" attribute of the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns: the "substanceUnits" attribute value

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

const char * KineticLaw_getTimeUnits ( const KineticLaw_t * kl )

Gets the value of the "timeUnits" attribute of the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns: the "timeUnits" attribute value

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

int KineticLaw_isSetFormula ( const KineticLaw_t * kl )

Predicate returning 1 (true) or 0 (false) depending on whether the "formula" attribute of the given KineticLaw_t structure is set.

This is fundamentally equivalent to KineticLaw_isSetMath(). It is provided principally for compatibility with SBML Level 1.

Parameters

kl	the KineticLaw_t structure.

Returns: 1 (true) if the formula (or equivalently the "math" subelement) of the given KineticLaw_t structure is set, 0 (false) otherwise.

Note: SBML Level 1 uses a text-string format for mathematical formulas. Other levels of SBML use MathML, an XML format for representing mathematical expressions. LibSBML provides an Abstract Syntax Tree API for working with mathematical expressions; this API is more powerful than working with formulas directly in text form, and ASTs can be translated into either MathML or the text-string syntax. The libSBML methods that accept text-string formulas directly (such as this constructor) are provided for SBML Level 1 compatibility, but developers are encouraged to use the AST mechanisms. See KineticLaw_createWithMath for a version that takes an ASTNode_t structure.

int KineticLaw_isSetMath ( const KineticLaw_t * kl )

Predicate returning 1 (true) or 0 (false) depending on whether the "math" subelement of the given KineticLaw_t structure is set.

This is fundamentally equivalent to KineticLaw_isSetFormula(). The latter provided principally for compatibility with SBML Level 1, which represented mathematical formulas in text-string form.

Parameters

kl	the KineticLaw_t structure.

Returns: 1 (true) if the "math" subelement of the given KineticLaw_t structure is set, 0 (false) otherwise.

Examples:: printMath.c.

int KineticLaw_isSetSubstanceUnits ( const KineticLaw_t * kl )

Predicate returning 1 (true) or 0 (false) depending on whether the "timeUnits" attribute of the given KineticLaw_t structure is set.

Parameters

kl	the KineticLaw_t structure.

Returns: 1 (true) if the "timeUnits" attribute of the given KineticLaw_t structure is set, 0 (false) otherwise.

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

int KineticLaw_isSetTimeUnits ( const KineticLaw_t * kl )

Predicate returning 1 (true) or 0 (false) depending on whether the "timeUnits" attribute of the given KineticLaw_t structure is set.

Parameters

kl	the KineticLaw_t structure.

Returns: 1 (true) if the "timeUnits" attribute of the given KineticLaw_t structure is set, 0 (false) otherwise.

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

LocalParameter_t * KineticLaw_removeLocalParameter	(	KineticLaw_t *	kl,
		unsigned int	n
	)

Removes the nth LocalParameter_t structure from the list of local parameters in this KineticLaw_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
n	the integer index of the LocalParameter_t sought.

Returns: the LocalParameter_t structure removed. As mentioned above, the caller owns the returned item. NULL is returned if the given index is out of range.

LocalParameter_t * KineticLaw_removeLocalParameterById	(	KineticLaw_t *	kl,
		const char *	sid
	)

Removes the LocalParameter_t structure with the given "id" attribute from the list of local parameters in this KineticLaw_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

: This function should be used for SBML Level 3 documents, as the equivalent constructs in Level 2 and Level 1 are Parameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
sid	the string of the "id" attribute of the LocalParameter_t sought.

Returns: the LocalParameter_t structure removed. As mentioned above, the caller owns the returned structure. NULL is returned if no KineticLaw_t structure with the identifier exists in this KineticLaw_t structure.

Parameter_t * KineticLaw_removeParameter	(	KineticLaw_t *	kl,
		unsigned int	n
	)

Removes the nth Parameter_t structure from the list of parameters in this KineticLaw_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
n	the integer index of the Parameter_t sought.

Returns: the Parameter_t structure removed. As mentioned above, the caller owns the returned item. NULL is returned if the given index is out of range.

Parameter_t * KineticLaw_removeParameterById	(	KineticLaw_t *	kl,
		const char *	sid
	)

Removes the Parameter_t structure with the given "id" attribute from the list of parameters in this KineticLaw_t structure and returns a pointer to it.

The caller owns the returned structure and is responsible for deleting it.

: This function should be used for SBML Level 1 and Level 2 documents, as the equivalent constructs in Level 3 are LocalParameter_t objects instead.

Parameters

kl	the KineticLaw_t structure.
sid	the string of the "id" attribute of the Parameter_t sought.

Returns: the Parameter_t structure removed. As mentioned above, the caller owns the returned structure. NULL is returned if no KineticLaw_t structure with the identifier exists in this KineticLaw_t structure.

int KineticLaw_setFormula	(	KineticLaw_t *	kl,
		const char *	formula
	)

Sets the formula of the given KineticLaw_t structure.

This is fundamentally equivalent to KineticLaw_setMath(). It is provided principally for compatibility with SBML Level 1.

Parameters

kl	the KineticLaw_t structure.
formula	the mathematical expression, in text-string form.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: SBML Level 1 uses a text-string format for mathematical formulas. Other levels of SBML use MathML, an XML format for representing mathematical expressions. LibSBML provides an Abstract Syntax Tree API for working with mathematical expressions; this API is more powerful than working with formulas directly in text form, and ASTs can be translated into either MathML or the text-string syntax. The libSBML methods that accept text-string formulas directly (such as this constructor) are provided for SBML Level 1 compatibility, but developers are encouraged to use the AST mechanisms. See KineticLaw_createWithMath for a version that takes an ASTNode_t structure.

int KineticLaw_setMath	(	KineticLaw_t *	kl,
		const ASTNode_t *	math
	)

Sets the formula of the given KineticLaw_t structure.

This is fundamentally equivalent to KineticLaw_setFormula(). The latter provided principally for compatibility with SBML Level 1, which represented mathematical formulas in text-string form.

Parameters

kl	the KineticLaw_t structure.
math	an ASTNode_t structure representing the mathematical formula.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Examples:: createExampleSBML.c.

int KineticLaw_setSubstanceUnits	(	KineticLaw_t *	kl,
		const char *	sid
	)

Sets the "substanceUnits" attribute of the given KineticLaw_t structure.

The identifier string sid is copied.

Parameters

kl	the KineticLaw_t structure.
sid	the identifier of the units.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "substanceUnits" attribute.

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

int KineticLaw_setTimeUnits	(	KineticLaw_t *	kl,
		const char *	sid
	)

Sets the "timeUnits" attribute of the given KineticLaw_t structure.

The identifier string sid is copied.

Parameters

kl	the KineticLaw_t structure.
sid	the identifier of the units.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Note: Using this function with an sid of NULL is equivalent to unsetting the "timeUnits" attribute.

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

int KineticLaw_unsetSubstanceUnits ( KineticLaw_t * kl )

Unsets the "substanceUnits" attribute of the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

int KineticLaw_unsetTimeUnits ( KineticLaw_t * kl )

Unsets the "timeUnits" attribute of the given KineticLaw_t structure.

Parameters

kl	the KineticLaw_t structure.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

Warning: In SBML Level 2 Version 2, the "timeUnits" and "substanceUnits" attributes were removed. For compatibility with new versions of SBML, users are cautioned to avoid these attributes.

Detailed Description

A warning about identifier shadowing

SBML Level/Version differences

Public Member Functions

Member Function Documentation