Detailed Description

A user-defined function in an SBML model.

The FunctionDefinition_t structure associates an identifier with a function definition. This identifier can then be used as the function called in subsequent MathML content elsewhere in an SBML model.

FunctionDefinition_t has one required attribute, "id", to give the function a unique identifier by which other parts of an SBML model definition can refer to it. A FunctionDefinition_t instance can also have an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification (e.g., Section 3.3 in the Level 2 Version 4 specification).

FunctionDefinition_t has a "math" subelement containing a MathML expression defining the function body. In SBML Level 2 and SBML Level 3 Version 1, that "math" subelement is required; in SBML Level 3 Version 2, this restriction was relaxed, making the "math" subelement optional. The content of this element can only be a MathML "lambda" element. The "lambda" element must begin with zero or more "bvar" elements, followed by any other of the elements in the MathML subset allowed in SBML Level 2 except "lambda" (i.e., a "lambda" element cannot contain another "lambda" element). This is the only place in SBML where a "lambda" element can be used. The function defined by a FunctionDefinition_t is only available for use in other MathML elements that follow the FunctionDefinition_t definition in the model. (These restrictions prevent recursive and mutually-recursive functions from being expressed.)

A further restriction on the content of "math" is that it cannot contain references to variables other than the variables declared to the "lambda" itself. That is, the contents of MathML "ci" elements inside the body of the "lambda" can only be the variables declared by its "bvar" elements, or the identifiers of other FunctionDefinition_t instances in the model. This means must be written so that all variables or parameters used in the MathML content are passed to them via their function parameters. In SBML Level 2, this restriction applies also to the MathML csymbol elements for time and delay; in SBML Level 3, it additionally applies to the csymbol element for avogadro.

In SBML Level 3 Version 2, if no math element is present in the FunctionDefinition_t, the function has no mathematical meaning defined in SBML Level 3 Core. This situation may arise when models are incomplete, or when additional meanings are provided by an SBML Level 3 package.

Note: Function definitions (also informally known as user-defined functions) were introduced in SBML Level 2. They have purposefully limited capabilities. A function cannot reference parameters or other model quantities outside of itself; values must be passed as parameters to the function. Moreover, recursive and mutually-recursive functions are not permitted. The purpose of these limitations is to balance power against complexity of implementation. With the restrictions as they are, function definitions could be implemented as textual substitutions—they are simply macros. Software implementations therefore do not need the full function-definition machinery typically associated with programming languages.

Another important point to note is FunctionDefinition_t does not have a separate attribute for defining the units of the value returned by the function. The units associated with the function's return value, when the function is called from within MathML expressions elsewhere in SBML, are simply the overall units of the expression in FunctionDefinition_t's "math" subelement when applied to the arguments supplied in the call to the function. Ascertaining these units requires performing dimensional analysis on the expression. (Readers may wonder why there is no attribute. The reason is that having a separate attribute for declaring the units would not only be redundant, but also lead to the potential for having conflicting information. In the case of a conflict between the declared units and those of the value actually returned by the function, the only logical resolution rule would be to assume that the correct units are those of the expression anyway.)

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

Public Member Functions
FunctionDefinition_t *	FunctionDefinition_clone (const FunctionDefinition_t *fd)
	Creates a deep copy of the given FunctionDefinition_t structure. More...

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

FunctionDefinition_t *	FunctionDefinition_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new FunctionDefinition_t structure using the given SBMLNamespaces_t structure. More...

void	FunctionDefinition_free (FunctionDefinition_t *fd)
	Frees the given FunctionDefinition_t. More...

const ASTNode_t *	FunctionDefinition_getArgument (const FunctionDefinition_t *fd, unsigned int n)
	Get the nth argument (bound variable) to the given FunctionDefinition_t structure. More...

const ASTNode_t *	FunctionDefinition_getArgumentByName (FunctionDefinition_t fd, const char name)
	Get the argument named `name` to the given FunctionDefinition_t structure. More...

const ASTNode_t *	FunctionDefinition_getBody (const FunctionDefinition_t *fd)
	Get the mathematical expression that constitutes the body of the given function definition. More...

const char *	FunctionDefinition_getId (const FunctionDefinition_t *fd)
	Get the identifier of the given FunctionDefinition_t structure. More...

const ASTNode_t *	FunctionDefinition_getMath (const FunctionDefinition_t *fd)
	Get the mathematical formula implemented by the given function. More...

const char *	FunctionDefinition_getName (const FunctionDefinition_t *fd)
	Get the name of the given FunctionDefinition_t structure. More...

const XMLNamespaces_t *	FunctionDefinition_getNamespaces (FunctionDefinition_t *fd)
	Returns a list of XMLNamespaces_t associated with this FunctionDefinition_t structure. More...

unsigned int	FunctionDefinition_getNumArguments (const FunctionDefinition_t *fd)
	Get the number of arguments that the given function definition takes. More...

int	FunctionDefinition_isSetBody (const FunctionDefinition_t *fd)
	Predicate returning `1` (true) or `0` (false) depending on whether the given FunctionDefinition_t structure's "math" subelement has a body. More...

int	FunctionDefinition_isSetId (const FunctionDefinition_t *fd)
	Predicate returning `1` (true) or `0` (false) depending on whether the given FunctionDefinition_t structure's "id" attribute is set. More...

int	FunctionDefinition_isSetMath (const FunctionDefinition_t *fd)
	Predicate returning `1` (true) or `0` (false) depending on whether the given FunctionDefinition_t structure's "math" subelement is set. More...

int	FunctionDefinition_isSetName (const FunctionDefinition_t *fd)
	Predicate returning `1` (true) or `0` (false) depending on whether the given FunctionDefinition_t structure's "name" attribute is set. More...

int	FunctionDefinition_setId (FunctionDefinition_t fd, const char sid)
	Sets the value of the "id" attribute of a FunctionDefinition_t structure. More...

int	FunctionDefinition_setMath (FunctionDefinition_t fd, const ASTNode_t math)
	Sets the "math" subelement of a given FunctionDefinition_t structure. More...

int	FunctionDefinition_setName (FunctionDefinition_t fd, const char name)
	Sets the value of the "name" attribute of a FunctionDefinition_t structure. More...

int	FunctionDefinition_unsetName (FunctionDefinition_t *fd)
	Unsets the "name" attribute of the given FunctionDefinition_t structure. More...

Member Function Documentation

FunctionDefinition_t * FunctionDefinition_clone ( const FunctionDefinition_t * fd )

Creates a deep copy of the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure to be copied.

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

FunctionDefinition_t * FunctionDefinition_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

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

FunctionDefinition_t * FunctionDefinition_createWithNS ( SBMLNamespaces_t * sbmlns )

Creates a new FunctionDefinition_t structure using the given SBMLNamespaces_t structure.

Parameters

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

Returns: a pointer to the newly created FunctionDefinition_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 FunctionDefinition_free ( FunctionDefinition_t * fd )

Frees the given FunctionDefinition_t.

Parameters

fd	the FunctionDefinition_t structure.

const ASTNode_t * FunctionDefinition_getArgument	(	const FunctionDefinition_t *	fd,
		unsigned int	n
	)

Get the nth argument (bound variable) to the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure.
n	the index of the argument to return.

Returns: an ASTNode_t tree structure for the argument.

const ASTNode_t * FunctionDefinition_getArgumentByName	(	FunctionDefinition_t *	fd,
		const char *	name
	)

Get the argument named name to the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure.
name	the exact name (case-sensitive) of the sought-after argument.

Returns: an ASTNode_t structure representing the argument (bound variable)

const ASTNode_t * FunctionDefinition_getBody ( const FunctionDefinition_t * fd )

Get the mathematical expression that constitutes the body of the given function definition.

Parameters

fd	the FunctionDefinition_t structure.

Returns: an ASTNode_t tree that is the "math" subelement of this FunctionDefinition_t structure.

const char * FunctionDefinition_getId ( const FunctionDefinition_t * fd )

Get the identifier of the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure.

Returns: the value of the "id" attribute of this FunctionDefinition_t structure.

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

const ASTNode_t * FunctionDefinition_getMath ( const FunctionDefinition_t * fd )

Get the mathematical formula implemented by the given function.

Parameters

fd	the FunctionDefinition_t structure.

Returns: an ASTNode_t tree representing the mathematical formula of this FunctionDefinition_t structure.

Examples:: printMath.c.

const char * FunctionDefinition_getName ( const FunctionDefinition_t * fd )

Get the name of the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure.

Returns: the name of this FunctionDefinition_t structure.

const XMLNamespaces_t * FunctionDefinition_getNamespaces ( FunctionDefinition_t * fd )

Returns a list of XMLNamespaces_t associated with this FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure.

Returns: pointer to the XMLNamespaces_t structure associated with this structure

unsigned int FunctionDefinition_getNumArguments ( const FunctionDefinition_t * fd )

Get the number of arguments that the given function definition takes.

Parameters

fd	the FunctionDefinition_t structure.

Returns: the number of arguments (bound variables) that must be passed to this FunctionDefinition_t structure.

int FunctionDefinition_isSetBody ( const FunctionDefinition_t * fd )

Predicate returning 1 (true) or 0 (false) depending on whether the given FunctionDefinition_t structure's "math" subelement has a body.

Parameters

fd	the FunctionDefinition_t structure.

Returns: 1 (true) if the body of this FunctionDefinition_t is set, 0 (false) otherwise.

int FunctionDefinition_isSetId ( const FunctionDefinition_t * fd )

Predicate returning 1 (true) or 0 (false) depending on whether the given FunctionDefinition_t structure's "id" attribute is set.

Parameters

fd	the FunctionDefinition_t structure.

Returns: 1 (true) if the "id" attribute of the FunctionDefinition_t structure is set, 0 (false) otherwise.

int FunctionDefinition_isSetMath ( const FunctionDefinition_t * fd )

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

Parameters

fd	the FunctionDefinition_t structure.

Returns: 1 (true) if the mathematical expression of this FunctionDefinition_t is set, 0 (false) otherwise.

Examples:: printMath.c.

int FunctionDefinition_isSetName ( const FunctionDefinition_t * fd )

Predicate returning 1 (true) or 0 (false) depending on whether the given FunctionDefinition_t structure's "name" attribute is set.

Parameters

fd	the FunctionDefinition_t structure.

Returns: 1 (true) if the "name" attribute of the FunctionDefinition_t structure is set, 0 (false) otherwise.

int FunctionDefinition_setId	(	FunctionDefinition_t *	fd,
		const char *	sid
	)

Sets the value of the "id" attribute of a FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure to set.
sid	the identifier to assign to the "id" attribute of `fd`.

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

Examples:: createExampleSBML.c.

int FunctionDefinition_setMath	(	FunctionDefinition_t *	fd,
		const ASTNode_t *	math
	)

Sets the "math" subelement of a given FunctionDefinition_t structure.

The ASTNode_t structure given in math is copied.

Parameters

fd	the FunctionDefinition_t structure to set.
math	the ASTNode_t structure to copy and assign to the "math" subelement of the given FunctionDefinition_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:

Examples:: createExampleSBML.c.

int FunctionDefinition_setName	(	FunctionDefinition_t *	fd,
		const char *	name
	)

Sets the value of the "name" attribute of a FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_t structure to set.
name	the identifier to assign to the "name" attribute of `fd`.

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 the name set to NULL is equivalent to unsetting the "name" attribute.

int FunctionDefinition_unsetName ( FunctionDefinition_t * fd )

Unsets the "name" attribute of the given FunctionDefinition_t structure.

Parameters

fd	the FunctionDefinition_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

Public Member Functions

Member Function Documentation