Detailed Description

A delay on the time of execution of an SBML event.

An Event_t object defines when the event can occur, the variables that are affected by the event, and how the variables are affected. The effect of the event can optionally be delayed after the occurrence of the condition which invokes it. An event delay is defined using an object of class Delay_t.

The object class Delay_t is derived from SBase_t and adds a single subelement called "math". This subelement is used to hold MathML content. The mathematical formula represented by "math" must evaluate to a numerical value. It is used as the length of time between when the event is triggered and when the event's assignments are actually executed. If no delay is present on a given Event_t, a time delay of zero is assumed.

The expression in "math" must be evaluated at the time the event is triggered. The expression must always evaluate to a nonnegative number (otherwise, a nonsensical situation could arise where an event is defined to execute before it is triggered!).

The units of the mathematical expression in a Delay_t

In SBML Level 2 versions before Version 4, the units of the numerical value computed by the Delay_t's "math" expression are required to be in units of time, or the model is considered to have a unit consistency error. In Level 2 Version 4 as well as SBML Level 3, this requirement is relaxed; these specifications only stipulate that the units of the numerical value computed by a Delay_t instance's "math" expression should match the model's units of time (meaning the definition of the time units in the model). LibSBML respects these requirements, and depending on whether an earlier Version of SBML Level 2 is in use, libSBML may or may not flag unit inconsistencies as errors or merely warnings.

Note that units are not predefined or assumed for the contents of "math" in a Delay_t object; rather, they must be defined explicitly for each instance of a Delay_t object in a model. This is an important point to bear in mind when literal numbers are used in delay expressions. For example, the following Event_t instance would result in a warning logged by SBMLDocument_t::checkConsistency() about the fact that libSBML cannot verify the consistency of the units of the expression. The reason is that the formula inside the "math" element does not have any declared units, whereas what is expected in this context is units of time:

<model>
    ...
    <listOfEvents>
        <event useValuesFromTriggerTime="true">
            ...
            <delay>
                <math xmlns="http://www.w3.org/1998/Math/MathML">
                    <cn> 1 </cn>
                </math>
            </delay>
            ...
        </event>
    </listOfEvents>
    ...
</model>

The <cn> 1 </cn> within the mathematical formula of the delay above has no units declared. To make the expression have the needed units of time, literal numbers should be avoided in favor of defining Parameter_t objects for each quantity, and declaring units for the Parameter_t values. The following fragment of SBML illustrates this approach:

<model>
    ...
    <listOfParameters>
        <parameter id="transcriptionDelay" value="10" units="second"/>
    </listOfParameters>
    ...
    <listOfEvents>
        <event useValuesFromTriggerTime="true">
            ...
            <delay>
                <math xmlns="http://www.w3.org/1998/Math/MathML">
                    <ci> transcriptionDelay </ci>
                </math>
            </delay>
            ...
        </event>
    </listOfEvents>
    ...
</model>

In SBML Level 3, an alternative approach is available in the form of the units attribute, which SBML Level 3 allows to appear on MathML cn elements. The value of this attribute can be used to indicate the unit of measurement to be associated with the number in the content of a cn element. The attribute is named units but, because it appears inside MathML element (which is in the XML namespace for MathML and not the namespace for SBML), it must always be prefixed with an XML namespace prefix for an SBML Level 3 namespace. The following is an example of this approach:

<model timeUnits="second" ...>
    ...
    <listOfEvents>
        <event useValuesFromTriggerTime="true">
            ...
            <delay>
                <math xmlns="http://www.w3.org/1998/Math/MathML"
                      xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
                    <cn sbml:units="second"> 10 </cn>
                </math>
            </delay>
            ...
        </event>
    </listOfEvents>
    ...
</model>

Restrictions relaxed in SBML Level 3 Version 2

In SBML Level 3 Version 2, the requirement that a Delay_t have a "math" subelement was relaxed, making it optional. In this case, the Delay_t remains undefined, and unless that information is provided in some other form (such as with an SBML Level 3 package), the Event_t behaves as if it had no Delay_t.

Examples:: printAnnotation.c, printMath.c, and printNotes.c.

Public Member Functions
Delay_t *	Delay_clone (const Delay_t *d)
	Creates and returns a deep copy of the given Delay_t structure. More...

int	Delay_containsUndeclaredUnits (Delay_t *d)
	Predicate returning `1` (true) or `0` (false) depending on whether the math expression of this Delay_t contains parameters/numbers with undeclared units. More...

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

Delay_t *	Delay_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Delay_t structure using the given SBMLNamespaces_t structure. More...

void	Delay_free (Delay_t *d)
	Frees the given Delay_t structure. More...

UnitDefinition_t *	Delay_getDerivedUnitDefinition (Delay_t *d)
	Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this Delay_t. More...

const ASTNode_t *	Delay_getMath (const Delay_t *d)
	Get the mathematical formula for a Delay_t structure and return it as as an ASTNode_t structure. More...

const XMLNamespaces_t *	Delay_getNamespaces (Delay_t *d)
	Returns a list of XMLNamespaces_t associated with this Delay_t structure. More...

int	Delay_isSetMath (const Delay_t *d)
	Predicate to test whether the formula for the given Delay_t structure is set. More...

int	Delay_setMath (Delay_t d, const ASTNode_t math)
	Sets the delay expression of the given Delay_t instance to a copy of the given ASTNode_t structure. More...

Member Function Documentation

Delay_t * Delay_clone ( const Delay_t * d )

Creates and returns a deep copy of the given Delay_t structure.

Parameters

d	the Delay_t structure to copy.

Returns: a (deep) copy of the given Delay_t structure t.

int Delay_containsUndeclaredUnits ( Delay_t * d )

Predicate returning 1 (true) or 0 (false) depending on whether the math expression of this Delay_t contains parameters/numbers with undeclared units.

Returns: 1 (true) if the math expression of this Delay_t includes parameters/numbers with undeclared units, 0 (false) otherwise.

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

See also: Delay_getDerivedUnitDefinition()

Examples:: printUnits.c.

Delay_t * Delay_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

Returns: a pointer to the newly created Delay_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.

Delay_t * Delay_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new Delay_t structure using the given SBMLNamespaces_t structure.

Parameters

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

Returns: a pointer to the newly created Delay_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 Delay_free ( Delay_t * d )

Frees the given Delay_t structure.

Parameters

d	the Delay_t structure to free.

UnitDefinition_t * Delay_getDerivedUnitDefinition ( Delay_t * d )

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

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

Note that the functionality that facilitates unit analysis depends on the model as a whole. Thus, in cases where the structure 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: Delay_containsUndeclaredUnits()

Examples:: printUnits.c.

const ASTNode_t * Delay_getMath ( const Delay_t * d )

Get the mathematical formula for a Delay_t structure and return it as as an ASTNode_t structure.

Parameters

d	the Delay_t structure to query.

Returns: an ASTNode_t structure representing the expression tree.

Examples:: printMath.c.

const XMLNamespaces_t * Delay_getNamespaces ( Delay_t * d )

Returns a list of XMLNamespaces_t associated with this Delay_t structure.

Parameters

d	the Delay_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

int Delay_isSetMath ( const Delay_t * d )

Predicate to test whether the formula for the given Delay_t structure is set.

Parameters

d	the Delay_t structure to query.

Returns: 1 (true) if the formula (meaning the math subelement) of this Delay_t is set, 0 (false) otherwise.

int Delay_setMath	(	Delay_t *	d,
		const ASTNode_t *	math
	)

Sets the delay expression of the given Delay_t instance to a copy of the given ASTNode_t structure.

Parameters

d	the Delay_t structure to set.
math	an ASTNode_t representing a formula tree.

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:

Detailed Description

The units of the mathematical expression in a Delay_t

Restrictions relaxed in SBML Level 3 Version 2

Public Member Functions

Member Function Documentation