Detailed Description

An SBML initial assignment, evaluated once only.

SBML Level 2 Versions 2–4 and SBML Level 3 provide two ways of assigning initial values to entities in a model. The simplest and most basic is to set the values of the appropriate attributes in the relevant components; for example, the initial value of a model parameter (whether it is a constant or a variable) can be assigned by setting its "value" attribute directly in the model definition. However, this approach is not suitable when the value must be calculated, because the initial value attributes on different components such as species, compartments, and parameters are single values and not mathematical expressions. In those situations, the InitialAssignment_t construct can be used; it permits the calculation of the value of a constant or the initial value of a variable from the values of other quantities in a model.

As explained below, the provision of InitialAssignment_t does not mean that models necessarily must use this construct when defining initial values of quantities in a model. If a value can be set directly using the relevant attribute of a component in a model, then that approach may be more efficient and more portable to other software tools. InitialAssignment_t should be used when the other mechanism is insufficient for the needs of a particular model.

The InitialAssignment_t construct has some similarities to AssignmentRule_t. The main differences are: (a) an InitialAssignment_t can set the value of a constant whereas an AssignmentRule_t cannot, and (b) unlike AssignmentRule_t, an InitialAssignment_t definition only applies up to and including the beginning of simulation time, i.e., t $\leq$ 0, while an AssignmentRule_t applies at all times.

InitialAssignment_t has a required attribute, "symbol", whose value must follow the guidelines for identifiers described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification). The value of this attribute in an InitialAssignment_t object can be the identifier of a Compartment_t, Species_t, SpeciesReference_t (in SBML Level 3), global Parameter_t, or (as of SBML Level 3 Version 2) the identifier of a SBML Level 3 package element with mathematical meaning. The InitialAssignment_t defines the initial value of the constant or variable referred to by the "symbol" attribute. (The attribute's name is "symbol" rather than "variable" because it may assign values to constants as well as variables in a model.) Note that an initial assignment cannot be made to reaction identifiers, that is, the "symbol" attribute value of an InitialAssignment_t cannot be an identifier that is the "id" attribute value of a Reaction_t object in the model. This is identical to a restriction placed on rules.

InitialAssignment_t also has a "math" subelement that contains a MathML expression used to calculate the value of the constant or the initial value of the variable. This subelement is required in SBML Level 2 and SBML Level 3 Version 1, but the requirement was relaxed in SBML Level 3 Version 2, making it optional. The units of the value computed by the formula in the "math" subelement should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be identical to be the units associated with the identifier given in the "symbol" attribute. (That is, the units are the units of the species, compartment, or parameter, as appropriate for the kind of object identified by the value of "symbol".)

InitialAssignment_t was introduced in SBML Level 2 Version 2. It is not available in SBML Level 2 Version 1 nor in any version of Level 1.

Semantics of Initial Assignments

The value calculated by an InitialAssignment_t object overrides the value assigned to the given symbol by the object defining that symbol. For example, if a compartment's "size" attribute is set in its definition, and the model also contains an InitialAssignment_t having that compartment's identifier as its "symbol" attribute value, then the interpretation is that the "size" assigned in the Compartment_t object should be ignored and the value assigned based on the computation defined in the InitialAssignment_t. Initial assignments can take place for Compartment_t, Species_t, global Parameter_t, SpeciesReference_t (in Level 3), and SBML Level 3 package elements (in Level 3 Version 2), regardless of the value of their "constant" attribute.

The actions of all InitialAssignment_t objects are in general terms the same, but differ in the precise details depending on the type of variable being set:

In the case of a species, an InitialAssignment_t sets the referenced species' initial quantity (concentration or amount of substance) to the value determined by the formula in the "math" subelement. The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the species.
In the case of a compartment, an InitialAssignment_t sets the referenced compartment's initial size to the size determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and in SBML Level 3) or must (in previous Versions) be the same as the units specified for the size of the compartment.
In the case of a parameter, an InitialAssignment_t sets the referenced parameter's initial value to that determined by the formula in "math". The overall units of the formula should (in SBML Level 2 Version 4 and SBML Level 3) or must (in previous Versions) be the same as the units defined for the parameter.
(For SBML Level 3 only) In the case of a species reference, an initial assignment sets the initial value of the stoichiometry of the referenced reactant or product to the value determined by the formula in "math". The unit associated with the value produced by the "math" formula should be consistent with the unit "dimensionless", because reactant and product stoichiometries in reactions are dimensionless quantities.
(For SBML Level 3 Version 2 only) In the case of an object from an SBML Level 3 package, an InitialAssignment_t sets the referenced object's initial value (however such values are defined by the package) to the value of the formula in math. The unit of measurement associated with the value produced by the formula should be the same as that object's units attribute value (if it has such an attribute), or be equal to the units of model components of that type (if objects of that class are defined by the package as having the same units).

If the symbol attribute of an InitialAssignment_t object references an object in an SBML namespace that is not understood by the interpreter reading a given SBML document (that is, if the object is defined by an SBML Level 3 package that the software does not support), the assignment must be ignored–the object's initial value will not need to be set, as the interpreter could not understand that package. If an interpreter cannot establish whether a referenced object is missing from the model or instead is defined in an SBML namespace not understood by the interpreter, it may produce a warning to the user. (The latter situation may only arise if an SBML package is present in the SBML document with a package:required attribute of "true".)

In the context of a simulation, initial assignments establish values that are in effect prior to and including the start of simulation time, i.e., t $\leq$ 0. Section 3.4.8 in the SBML Level 2 Version 4 and SBML Level 3 specifications provides information about the interpretation of assignments, rules, and entity values for simulation time up to and including the start time t = 0; this is important for establishing the initial conditions of a simulation if the model involves expressions containing the delay "csymbol".

There cannot be two initial assignments for the same symbol in a model; that is, a model must not contain two or more InitialAssignment_t objects that both have the same identifier as their "symbol" attribute value. A model must also not define initial assignments and assignment rules for the same entity. That is, there cannot be both an InitialAssignment_t and an AssignmentRule_t for the same symbol in a model, because both kinds of constructs apply prior to and at the start of simulated time—allowing both to exist for a given symbol would result in indeterminism).

The ordering of InitialAssignment_t objects is not significant. The combined set of InitialAssignment_t, AssignmentRule_t and KineticLaw_t objects form a set of assignment statements that must be considered as a whole. The combined set of assignment statements should not contain algebraic loops: a chain of dependency between these statements should terminate. (More formally, consider the directed graph of assignment statements where nodes are a model's assignment statements and directed arcs exist for each occurrence of a symbol in an assignment statement "math" attribute. The directed arcs in this graph start from the statement assigning the symbol and end at the statement that contains the symbol in their math elements. Such a graph must be acyclic.)

Finally, it is worth being explicit about the expected behavior in the following situation. Suppose (1) a given symbol has a value x assigned to it in its definition, and (2) there is an initial assignment having the identifier as its "symbol" value and reassigning the value to y, and (3) the identifier is also used in the mathematical formula of a second initial assignment. What value should the second initial assignment use? It is y, the value assigned to the symbol by the first initial assignment, not whatever value was given in the symbol's definition. This follows directly from the behavior described above: if an InitialAssignment_t object exists for a given symbol, then the symbol's value is overridden by that initial assignment.

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

Public Member Functions
InitialAssignment_t *	InitialAssignment_clone (const InitialAssignment_t *ia)
	Copy constructor; creates a copy of this InitialAssignment_t. More...

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

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

InitialAssignment_t *	InitialAssignment_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new InitialAssignment_t structure using the given SBMLNamespaces_t structure. More...

void	InitialAssignment_free (InitialAssignment_t *ia)
	Frees the given InitialAssignment_t structure. More...

UnitDefinition_t *	InitialAssignment_getDerivedUnitDefinition (InitialAssignment_t *ia)
	Calculates and returns a UnitDefinition_t that expresses the units returned by the math expression of this InitialAssignment_t. More...

const ASTNode_t *	InitialAssignment_getMath (const InitialAssignment_t *ia)
	Get the mathematical formula of this InitialAssignment_t. More...

const XMLNamespaces_t *	InitialAssignment_getNamespaces (InitialAssignment_t *ia)
	Returns a list of XMLNamespaces_t associated with this InitialAssignment_t structure. More...

const char *	InitialAssignment_getSymbol (const InitialAssignment_t *ia)
	Get the value of the "symbol" attribute of this InitialAssignment_t. More...

int	InitialAssignment_isSetMath (const InitialAssignment_t *ia)
	Predicate returning `1` (true) or `0` (false) depending on whether this InitialAssignment_t's "math" subelement contains a value. More...

int	InitialAssignment_isSetSymbol (const InitialAssignment_t *ia)
	Predicate returning `1` (true) or `0` (false) depending on whether this InitialAssignment_t's "symbol" attribute is set. More...

int	InitialAssignment_setMath (InitialAssignment_t ia, const ASTNode_t math)
	Sets the "math" subelement of this InitialAssignment_t. More...

int	InitialAssignment_setSymbol (InitialAssignment_t ia, const char sid)
	Sets the "symbol" attribute value of this InitialAssignment_t. More...

int	InitialAssignment_unsetSymbol (InitialAssignment_t *ia)
	Unsets the "symbol" attribute value of this InitialAssignment_t. More...

Member Function Documentation

InitialAssignment_t * InitialAssignment_clone ( const InitialAssignment_t * ia )

Copy constructor; creates a copy of this InitialAssignment_t.

Parameters

ia	the InitialAssignment_t structure.

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

int InitialAssignment_containsUndeclaredUnits ( InitialAssignment_t * ia )

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

Returns: 1 (true) if the math expression of this InitialAssignment_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: InitialAssignment_getDerivedUnitDefinition()

Examples:: printUnits.c.

InitialAssignment_t * InitialAssignment_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

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

InitialAssignment_t * InitialAssignment_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new InitialAssignment_t structure using the given SBMLNamespaces_t structure.

Parameters

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

Returns: a pointer to the newly created InitialAssignment_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 InitialAssignment_free ( InitialAssignment_t * ia )

Frees the given InitialAssignment_t structure.

Parameters

ia	the InitialAssignment_t structure to free.

UnitDefinition_t * InitialAssignment_getDerivedUnitDefinition ( InitialAssignment_t * ia )

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

Returns: a UnitDefinition_t that expresses the units of the math expression of this InitialAssignment_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: InitialAssignment_containsUndeclaredUnits()

Examples:: printUnits.c.

const ASTNode_t * InitialAssignment_getMath ( const InitialAssignment_t * ia )

Get the mathematical formula of this InitialAssignment_t.

Parameters

ia	the InitialAssignment_t structure.

Returns: an ASTNode_t, the value of the "math" subelement of this InitialAssignment_t

const XMLNamespaces_t * InitialAssignment_getNamespaces ( InitialAssignment_t * ia )

Returns a list of XMLNamespaces_t associated with this InitialAssignment_t structure.

Parameters

ia	the InitialAssignment_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

const char * InitialAssignment_getSymbol ( const InitialAssignment_t * ia )

Get the value of the "symbol" attribute of this InitialAssignment_t.

Parameters

ia	the InitialAssignment_t structure.

Returns: the identifier string stored as the "symbol" attribute value in this InitialAssignment_t.

int InitialAssignment_isSetMath ( const InitialAssignment_t * ia )

Predicate returning 1 (true) or 0 (false) depending on whether this InitialAssignment_t's "math" subelement contains a value.

Parameters

ia	the InitialAssignment_t structure.

Returns: 1 (true) if the "math" for this InitialAssignment_t is set, 0 (false) otherwise.

int InitialAssignment_isSetSymbol ( const InitialAssignment_t * ia )

Predicate returning 1 (true) or 0 (false) depending on whether this InitialAssignment_t's "symbol" attribute is set.

Parameters

ia	the InitialAssignment_t structure.

Returns: 1 (true) if the "symbol" attribute of this InitialAssignment_t is set, 0 (false) otherwise.

int InitialAssignment_setMath	(	InitialAssignment_t *	ia,
		const ASTNode_t *	math
	)

Sets the "math" subelement of this InitialAssignment_t.

The ASTNode_t tree passed in math is copied.

Parameters

ia	the InitialAssignment_t structure.
math	an ASTNode_t tree containing the mathematical expression to be used as the formula for this InitialAssignment_t.

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 InitialAssignment_setSymbol	(	InitialAssignment_t *	ia,
		const char *	sid
	)

Sets the "symbol" attribute value of this InitialAssignment_t.

Parameters

ia	the InitialAssignment_t structure.
sid	the identifier of an element defined in this model whose value can be set.

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 "symbol" attribute.

int InitialAssignment_unsetSymbol ( InitialAssignment_t * ia )

Unsets the "symbol" attribute value of this InitialAssignment_t.

Parameters

ia	the InitialAssignment_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:

Detailed Description

Semantics of Initial Assignments

Public Member Functions

Member Function Documentation