Parameter_t Class Reference

Detailed Description

An SBML parameter: a named symbol with a value.

A Parameter_t 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_t 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_t object (unlike the case for, e.g., Species_t and Compartment_t).

• 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_t structure. There are no constraints on the units that can be chosen from these sets. There are no default units for parameters.

The Parameter_t 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_t. 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_t, for parameters that are local to a Reaction_t's KineticLaw_t. In Levels prior to SBML Level 3, the Parameter_t class is used both for definitions of global parameters, as well as reaction-local parameters stored in a list within KineticLaw_t objects. Parameter_t objects that are local to a reaction (that is, those defined within the KineticLaw_t structure of a Reaction_t) cannot be changed by rules and therefore are implicitly always constant; consequently, in SBML Level 2, parameter definitions within Reaction_t 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_t is derived from SBase_t, and the methods defined on SBase_t are available on Parameter_t.

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_t 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_t 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.

In SBML Level 3 Version 2, many restrictions were lifted requiring only Boolean values in Boolean contexts, and numeric values in numeric contexts. This means that a Parameter_t may now be used as a Boolean, despite canonically having a numeric value. To be consistent, one should always assign it a value of true or false, and use it in Boolean contexts exclusively. It would be appropriate to give it an SBO_t value of 602 ('Logical parameter') if one chooses to do this.

See also

ListOfParameters_t

Examples:

createExampleSBML.c, printAnnotation.c, printNotes.c, printUnits.c, unsetAnnotation.c, and unsetNotes.c.

Public Member Functions
Parameter_t *	Parameter_clone (const Parameter_t *p)
	Creates a deep copy of the given Parameter_t structure. More...
Parameter_t *	Parameter_create (unsigned int level, unsigned int version)
	Creates a new Parameter_t structure using the given SBML level and version values. More...
Parameter_t *	Parameter_createWithNS (SBMLNamespaces_t *sbmlns)
	Creates a new Parameter_t structure using the given SBMLNamespaces_t structure. More...
void	Parameter_free (Parameter_t *p)
	Frees the given Parameter_t structure. More...
int	Parameter_getConstant (const Parameter_t *p)
	Takes a Parameter_t structure and returns 1 (true) or 0 (false), depending on the value of the parameter's "constant" attribute. More...
UnitDefinition_t *	Parameter_getDerivedUnitDefinition (Parameter_t *p)
	Constructs and returns a UnitDefinition_t structure that expresses the units of this Parameter_t structure. More...
const char *	Parameter_getId (const Parameter_t *p)
	Takes a Parameter_t structure and returns its identifier. More...
const char *	Parameter_getName (const Parameter_t *p)
	Takes a Parameter_t structure and returns its name. More...
const XMLNamespaces_t *	Parameter_getNamespaces (Parameter_t *p)
	Returns a list of XMLNamespaces_t associated with this Parameter_t structure. More...
const char *	Parameter_getUnits (const Parameter_t *p)
	Takes a Parameter_t structure and returns its units. More...
double	Parameter_getValue (const Parameter_t *p)
	Takes a Parameter_t structure and returns its value. More...
int	Parameter_hasRequiredAttributes (Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for this Parameter_t structure have been set. More...
void	Parameter_initDefaults (Parameter_t *p)
	Initializes the attributes of this Parameter_t structure to their defaults. More...
int	Parameter_isSetConstant (const Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's constant attribute have been set. More...
int	Parameter_isSetId (const Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's identifier is set. More...
int	Parameter_isSetName (const Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's name is set. More...
int	Parameter_isSetUnits (const Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's units have been set. More...
int	Parameter_isSetValue (const Parameter_t *p)
	Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's value is set. More...
int	Parameter_setConstant (Parameter_t *p, int value)
	Assign the "constant" attribute of a Parameter_t structure. More...
int	Parameter_setId (Parameter_t *p, const char *sid)
	Assigns the identifier of a Parameter_t structure. More...
int	Parameter_setName (Parameter_t *p, const char *name)
	Assign the name of a Parameter_t structure. More...
int	Parameter_setUnits (Parameter_t *p, const char *units)
	Assign the units of a Parameter_t structure. More...
int	Parameter_setValue (Parameter_t *p, double value)
	Assign the value of a Parameter_t structure. More...
int	Parameter_unsetConstant (Parameter_t *c)
	Unsets the value of the "constant" attribute of the given Parameter_t structure. More...
int	Parameter_unsetName (Parameter_t *p)
	Unsets the name of this Parameter_t structure. More...
int	Parameter_unsetUnits (Parameter_t *p)
	Unsets the units of this Parameter_t structure. More...
int	Parameter_unsetValue (Parameter_t *p)
	Unsets the value of this Parameter_t structure. More...

Member Function Documentation

Parameter_t * Parameter_clone

(

const Parameter_t *

p

)

Creates a deep copy of the given Parameter_t structure.

Parameters

p	the Parameter_t structure to be copied.

Returns

a (deep) copy of the given Parameter_t structure.

Parameter_t * Parameter_create	(	unsigned int	level,
		unsigned int	version
	)

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

Parameters

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

Returns

a pointer to the newly created Parameter_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.

Parameter_t * Parameter_createWithNS

(

SBMLNamespaces_t *

sbmlns

)

Creates a new Parameter_t structure using the given SBMLNamespaces_t structure.

Parameters

sbmlns

SBMLNamespaces_t, a pointer to an SBMLNamespaces_t structure to assign to this Parameter_t.

Returns

a pointer to the newly created Parameter_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 Parameter_free

(

Parameter_t *

p

)

Frees the given Parameter_t structure.

Parameters

p	the Parameter_t structure to be freed.

int Parameter_getConstant

(

const Parameter_t *

p

)

Takes a Parameter_t structure and returns 1 (true) or 0 (false), depending on the value of the parameter's "constant" attribute.

Parameters

p	the Parameter_t whose constant value is sought.

Returns

the value of the "constant" attribute, with nonzero meaning true and zero meaning false.

UnitDefinition_t * Parameter_getDerivedUnitDefinition

(

Parameter_t *

p

)

Constructs and returns a UnitDefinition_t structure that expresses the units of this Parameter_t structure.

Parameters

p	the Parameter_t structure whose units are to be returned.

Returns

a UnitDefinition_t structure that expresses the units of this Parameter_t strucuture.

Note

This function returns the units of the Parameter_t expressed as a UnitDefinition_t. The units may be those explicitly declared. In the case where no units have been declared, NULL is returned.

Examples:

printUnits.c.

const char * Parameter_getId

(

const Parameter_t *

p

)

Takes a Parameter_t structure and returns its identifier.

Parameters

p	the Parameter_t structure whose identifier is sought.

Returns

the identifier of this Parameter_t, as a pointer to a string.

Examples:

printAnnotation.c, and printNotes.c.

const char * Parameter_getName

(

const Parameter_t *

p

)

Takes a Parameter_t structure and returns its name.

Parameters

p	the Parameter_t whose name is sought.

Returns

the name of this Parameter_t, as a pointer to a string.

const XMLNamespaces_t * Parameter_getNamespaces

(

Parameter_t *

p

)

Returns a list of XMLNamespaces_t associated with this Parameter_t structure.

Parameters

p	the Parameter_t structure.

Returns

pointer to the XMLNamespaces_t structure associated with this structure

const char * Parameter_getUnits

(

const Parameter_t *

p

)

Takes a Parameter_t structure and returns its units.

Parameters

p	the Parameter_t whose units are sought.

Returns

the units assigned to this Parameter_t structure, as a pointer to a string.

double Parameter_getValue

(

const Parameter_t *

p

)

Takes a Parameter_t structure and returns its value.

Parameters

p	the Parameter_t whose value is sought.

Returns

the value assigned to this Parameter_t structure, as a double.

int Parameter_hasRequiredAttributes

(

Parameter_t *

p

)

Predicate returning 1 (true) or 0 (false) depending on whether all the required attributes for this Parameter_t structure have been set.

The required attributes for a Parameter_t structure are:

• id (name in L1)
• constant (in L3 only)

Parameters

p	the Parameter_t structure to check.

Returns

1 (true) if all the required attributes for this structure have been defined, 0 (false) otherwise.

void Parameter_initDefaults

(

Parameter_t *

p

)

Initializes the attributes of this Parameter_t structure to their defaults.

The exact results depends on the SBML Level and Version in use. The cases are currently the following:

• (SBML Level 2 only) constant = true

Parameters

p	the Parameter_t structure to initialize.

int Parameter_isSetConstant

(

const Parameter_t *

p

)

Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's constant attribute have been set.

Parameters

p	the Parameter_t structure to query.

Returns

1 (true) if the "constant" attribute of the given Parameter_t structure is set, 0 (false) otherwise.

int Parameter_isSetId

(

const Parameter_t *

p

)

Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's identifier is set.

Parameters

p	the Parameter_t structure to query.

Returns

1 (true) if the "id" attribute of the given Parameter_t structure is set, 0 (false) otherwise.

int Parameter_isSetName

(

const Parameter_t *

p

)

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

Parameters

p	the Parameter_t structure to query.

Returns

1 (true) if the "name" attribute of the given Parameter_t structure is set, 0 (false) otherwise.

int Parameter_isSetUnits

(

const Parameter_t *

p

)

Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's units have been set.

Parameters

p	the Parameter_t structure to query.

Returns

1 (true) if the "units" attribute of the given Parameter_t structure is set, 0 (false) otherwise.

int Parameter_isSetValue

(

const Parameter_t *

p

)

Predicate returning 1 (true) or 0 (false) depending on whether the given Parameter_t structure's value is set.

Parameters

p	the Parameter_t structure to query.

Returns

1 (true) if the "value" attribute of the given Parameter_t structure is set, 0 (false) otherwise.

Note

In SBML Level 1 Version 1, a Parameter_t value is required and therefore should always be set. In Level 1 Version 2 and later, the value is optional, and as such, may or may not be set.

int Parameter_setConstant	(	Parameter_t *	p,
		int	value
	)

Assign the "constant" attribute of a Parameter_t structure.

Parameters

p	the Parameter_t structure to set.
value	the value to assign as the "constant" attribute of the parameter, either zero for false or nonzero for true.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_UNEXPECTED_ATTRIBUTE

int Parameter_setId	(	Parameter_t *	p,
		const char *	sid
	)

Assigns the identifier of a Parameter_t structure.

This makes a copy of the string passed in the parameter sid.

Parameters

p	the Parameter_t structure to set.
sid	the string to use as the identifier.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE

Note

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

Examples:

createExampleSBML.c.

int Parameter_setName	(	Parameter_t *	p,
		const char *	name
	)

Assign the name of a Parameter_t structure.

This makes a copy of the string passed in as the argument name.

Parameters

p	the Parameter_t structure to set.
name	the string to use as the name.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE

Note

Using this function with the name set to NULL is equivalent to unsetting the "name" attribute.

int Parameter_setUnits	(	Parameter_t *	p,
		const char *	units
	)

Assign the units of a Parameter_t structure.

This makes a copy of the string passed in as the argument units.

Parameters

p	the Parameter_t structure to set.
units	the string to use as the identifier of the units to assign.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_ATTRIBUTE_VALUE

Note

Using this function with units set to NULL is equivalent to unsetting the "units" attribute.

Examples:

createExampleSBML.c.

int Parameter_setValue	(	Parameter_t *	p,
		double	value
	)

Assign the value of a Parameter_t structure.

Parameters

p	the Parameter_t structure to set.
value	the double value to use.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

Examples:

createExampleSBML.c.

int Parameter_unsetConstant

(

Parameter_t *

c

)

Unsets the value of the "constant" attribute of the given Parameter_t structure.

Parameters

c	the 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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_OPERATION_FAILED
• LIBSBML_INVALID_OBJECT

int Parameter_unsetName

(

Parameter_t *

p

)

Unsets the name of this Parameter_t structure.

Parameters

p	the Parameter_t structure whose name is to be unset.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_OPERATION_FAILED

int Parameter_unsetUnits

(

Parameter_t *

p

)

Unsets the units of this Parameter_t structure.

Parameters

p	the Parameter_t structure whose units are to be unset.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_OPERATION_FAILED

int Parameter_unsetValue

(

Parameter_t *

p

)

Unsets the value of this Parameter_t structure.

In SBML Level 1 Version 1, a parameter is required to have a value and therefore this attribute should always be set. In Level 1 Version 2 and beyond, a value is optional, and as such, may or may not be set.

Parameters

p	the Parameter_t structure whose value is to be unset.

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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT