Detailed Description

comp A model instance inside another model.

The Submodel_t class was introduced by the SBML Level 3 Hierarchical Model_t Composition (“comp”) package as the principle way by which models are structured hierarchically. Submodels are instantiations of models contained within other models. They reference another Model_t that is to be instantiated within its parent Model_t, and additionally define how that Model_t is to be modified before instantiation.

The Submodel_t object class has a required attribute "modelRef", which must reference another Model_t or ExternalModelDefinition_t object present in the SBML Document. This referenced Model_t is the model to be instantiated.

It also has a required attribute, "id", to give the submodel a unique identifier by which other parts of an SBML model definition can refer to it, and an optional "name" attribute of type string. Identifiers and names must be used according to the guidelines described in the SBML specification.

The Submodel_t class also provides constructs that define how the referenced Model_t object is to be modified before it is instantiated in the enclosing model. If numerical values in the referenced model must be changed in order to fit them into their new context as part of the submodel, the changes can be handled through conversion factors. If one or more structural features in the referenced model are undesirable and should be removed, the changes can be handled through deletions. (For example, an initial assignment or reaction may not be relevant in its new context and should be removed.)

In some cases, the referenced Model_t may have been written with different units than the containing model. For most model elements, this is not a problem: it is already possible to have Species_t and Parameter_t objects with different units in a single model, for example, so in this case the resulting hierarchical model would be treated in exactly the same way as any other model with Species_t and Parameters with different units.

However, two units in SBML models are fixed and must not vary between SBML elements: time and extent. The units of time are set once per model, and affect the core elements of RateRule_t, KineticLaw_t, Delay_t, and the csymbols 'time' and 'delay'. Even if the model does not explicitly state what the units of time actually are, they are defined to be consistent across the model, and therefore might differ from the units of time across a parent model. To correct this imbalance, the optional attribute "timeConversionFactor" may be used, which, if defined, must reference a constant parameter in the parent model. The value of the time conversion factor should be defined such that a single unit of time in the Submodel_t multiplied by the time conversion factor should equal a single unit of time in the parent model.

Extent is the unit in SBML that defines how the KineticLaw_t of a Reaction_t affects species quantities: kinetic laws are defined to be in units of extent/time. No other SBML core construct is defined in terms of extent. If the effective units of extent in a submodel differ from the effective units of extent in the parent model (regardless of whether either defined what those units actually are), the optional attribute "extentConversionFactor" may be used, which, if defined, must reference a constant parameter in the parent model. The value of the extent conversion factor should be defined such that a single unit of extent in the Submodel_t multiplied by the extent conversion factor should equal a single unit of extent in the parent model.

If features of the referenced model must be removed, a Deletion_t should be added to the Submodel_t object. A Submodel_t may contain a child ListOfDeletions_t, which in turn may contain one or more Deletion_t items. Each Deletion_t references a single element of the referenced Model_t that must be removed before instantiating that Model_t as a submodel of the parent Model_t.

Examples:: spec_example1.c.

Public Member Functions
int	Submodel_addDeletion (Submodel_t s, Deletion_t d)
	Appends a copy of the given Deletion_t structure to the given Submodel_t structure. More...

Submodel_t *	Submodel_clone (Submodel_t *s)
	Returns a copy of the given Submodel_t structure. More...

Submodel_t *	Submodel_create (unsigned int level, unsigned int version, unsigned int pkgVersion)
	Creates a new Submodel_t structure using the given SBML `level` and `version`, and the `pkgVersion` package version. More...

Deletion_t *	Submodel_createDeletion (Submodel_t *s)
	Creates a new, empty Deletion_t structure, adds it to the given Submodel_t, and returns the Deletion_t. More...

void	Submodel_free (Submodel_t *s)
	Frees the given Submodel_t structure. More...

Deletion_t *	Submodel_getDeletion (Submodel_t *s, unsigned int n)
	Return a specific Deletion_t structure of the given Submodel_t. More...

Deletion_t *	Submodel_getDeletionById (Submodel_t s, const char sid)
	Return the Deletion_t indicated by the given `sid`. More...

char *	Submodel_getExtentConversionFactor (Submodel_t *s)
	Takes a Submodel_t structure and returns its extentConversionFactor. More...

char *	Submodel_getId (Submodel_t *s)
	Takes an Submodel_t structure and returns its identifier. More...

ListOf_t *	Submodel_getListOfDeletions (Submodel_t *s)
	Get the list of Deletion_t structures from the given Submodel_t structure. More...

char *	Submodel_getModelRef (Submodel_t *s)
	Takes a Submodel_t structure and returns its modelRef. More...

char *	Submodel_getName (Submodel_t *s)
	Takes a Submodel_t structure and returns its name. More...

unsigned int	Submodel_getNumDeletions (Submodel_t *s)
	Returns the number of EventAssignment_t structures attached to the given Submodel_t. More...

char *	Submodel_getSubstanceConversionFactor (Submodel_t *s)
	Returns NULL, since "substanceConversionFactor" is not a part of the comp spec. More...

char *	Submodel_getTimeConversionFactor (Submodel_t *s)
	Takes a Submodel_t structure and returns its timeConversionFactor. More...

int	Submodel_hasRequiredAttributes (Submodel_t *s)
	Predicate returning `true` or `false` depending on whether all the required attributes for the given Submodel_t structure have been set. More...

int	Submodel_hasRequiredElements (Submodel_t *s)
	Predicate returning `true` or `false` depending on whether all the required elements for the given Submodel_t structure have been set. More...

int	Submodel_isSetExtentConversionFactor (Submodel_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Submodel_t structure's extentConversionFactor is set. More...

int	Submodel_isSetId (Submodel_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Submodel_t structure's identifier is set. More...

int	Submodel_isSetModelRef (Submodel_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Submodel_t structure's modelRef is set. More...

int	Submodel_isSetName (Submodel_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Submodel_t structure's name is set. More...

int	Submodel_isSetSubstanceConversionFactor (Submodel_t *s)
	Returns `false`, since "substanceConversionFactor" is not a part of the comp spec. More...

int	Submodel_isSetTimeConversionFactor (Submodel_t *s)
	Predicate returning `1` (true) or `0` (false) depending on whether the given Submodel_t structure's timeConversionFactor is set. More...

Deletion_t *	Submodel_removeDeletion (Submodel_t *s, unsigned int n)
	Removes the nth Deletion_t structure from the given Submodel_t structure and returns a pointer to it. More...

Deletion_t *	Submodel_removeDeletionById (Submodel_t s, const char sid)
	Removes the Deletion_t structure with the given `sid` from the given Submodel_t structure and returns a pointer to it. More...

int	Submodel_setExtentConversionFactor (Submodel_t s, const char extentConversionFactor)
	Sets the extentConversionFactor of the given Submodel_t to a copy of `extentConversionFactor`. More...

int	Submodel_setId (Submodel_t s, const char sid)
	Assigns the identifier of an Submodel_t structure. More...

int	Submodel_setModelRef (Submodel_t s, const char modelRef)
	Sets the modelRef of the given Submodel_t to a copy of `modelRef`. More...

int	Submodel_setName (Submodel_t s, const char name)
	Sets the name of the given Submodel_t to a copy of `name`. More...

int	Submodel_setSubstanceConversionFactor (Submodel_t s, const char substanceConversionFactor)
	Automatically fails, since "substanceConversionFactor" is not a part of the comp spec. More...

int	Submodel_setTimeConversionFactor (Submodel_t s, const char timeConversionFactor)
	Sets the timeConversionFactor of the given Submodel_t to a copy of `timeConversionFactor`. More...

int	Submodel_unsetExtentConversionFactor (Submodel_t *s)
	Unsets the "extentConversionFactor" attribute of the given Submodel_t structure. More...

int	Submodel_unsetId (Submodel_t *s)
	Unsets the "id" attribute of the given Submodel_t structure. More...

int	Submodel_unsetModelRef (Submodel_t *s)
	Unsets the "modelRef" attribute of the given Submodel_t structure. More...

int	Submodel_unsetName (Submodel_t *s)
	Unsets the "name" attribute of the given Submodel_t structure. More...

int	Submodel_unsetSubstanceConversionFactor (Submodel_t *s)
	Automatically fails, since "substanceConversionFactor" is not a part of the comp spec. More...

int	Submodel_unsetTimeConversionFactor (Submodel_t *s)
	Unsets the "timeConversionFactor" attribute of the given Submodel_t structure. More...

Member Function Documentation

int Submodel_addDeletion	(	Submodel_t *	s,
		Deletion_t *	d
	)

Appends a copy of the given Deletion_t structure to the given Submodel_t structure.

Parameters

s	the Submodel_t structure to which the Deletion_t should be added.
d	a Deletion_t structure to add.

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:

Submodel_t * Submodel_clone ( Submodel_t * s )

Returns a copy of the given Submodel_t structure.

Parameters

s	the Submodel_t structure to copy.

Returns: a (deep) copy of the Submodel_t.

Submodel_t * Submodel_create	(	unsigned int	level,
		unsigned int	version,
		unsigned int	pkgVersion
	)

Creates a new Submodel_t structure using the given SBML level and version, and the pkgVersion package version.

Parameters

level	an unsigned int, the SBML Level to assign to this Submodel_t.
version	an unsigned int, the SBML Version to assign to this Submodel_t.
pkgVersion	an unsigned int, the SBML 'comp' package Version to assign to this Submodel_t.

Returns: a pointer to the newly created Submodel_t structure.

Deletion_t * Submodel_createDeletion ( Submodel_t * s )

Creates a new, empty Deletion_t structure, adds it to the given Submodel_t, and returns the Deletion_t.

Parameters

s	the Submodel_t structure to which the Deletion_t should be added.

Returns: the newly-created empty Deletion_t.

void Submodel_free ( Submodel_t * s )

Frees the given Submodel_t structure.

Parameters

s	the Submodel_t structure to free.

Deletion_t * Submodel_getDeletion	(	Submodel_t *	s,
		unsigned int	n
	)

Return a specific Deletion_t structure of the given Submodel_t.

Parameters

s	the Submodel_t structure to use.
n	an integer, the index of the Deletion_t structure to return.

Returns: the nth Deletion_t of the given Submodel_t, or NULL if no such Deletion_t exists.

Deletion_t * Submodel_getDeletionById	(	Submodel_t *	s,
		const char *	sid
	)

Return the Deletion_t indicated by the given sid.

Parameters

s	the Submodel_t structure to use.
sid	a string, the identifier of the Deletion_t being sought.

Returns: the Deletion_t for the given variable, or NULL if no such Deletion_t exists.

char * Submodel_getExtentConversionFactor ( Submodel_t * s )

Takes a Submodel_t structure and returns its extentConversionFactor.

Parameters

s	the Submodel_t whose extentConversionFactor is sought.

Returns: the extentConversionFactor of the given Submodel_t, as a pointer to a string.

char * Submodel_getId ( Submodel_t * s )

Takes an Submodel_t structure and returns its identifier.

Parameters

s	the Submodel_t structure whose identifier is sought.

Returns: the identifier of the given Submodel_t, as a pointer to a string.

ListOf_t * Submodel_getListOfDeletions ( Submodel_t * s )

Get the list of Deletion_t structures from the given Submodel_t structure.

Parameters

s	the Submodel_t structure to use.

Returns: the list of Deletion_t structures for the given Submodel_t.

char * Submodel_getModelRef ( Submodel_t * s )

Takes a Submodel_t structure and returns its modelRef.

Parameters

s	the Submodel_t whose modelRef is sought.

Returns: the modelRef of the given Submodel_t, as a pointer to a string.

char * Submodel_getName ( Submodel_t * s )

Takes a Submodel_t structure and returns its name.

Parameters

s	the Submodel_t whose name is sought.

Returns: the name of the given Submodel_t, as a pointer to a string.

unsigned int Submodel_getNumDeletions ( Submodel_t * s )

Returns the number of EventAssignment_t structures attached to the given Submodel_t.

Parameters

s	the Submodel_t structure to use.

Returns: the number of EventAssignment_t structures in the given Submodel_t.

char * Submodel_getSubstanceConversionFactor ( Submodel_t * s )

Returns NULL, since "substanceConversionFactor" is not a part of the comp spec.

Parameters

s	the Submodel_t whose substanceConversionFactor is sought.

Returns: NULL

char * Submodel_getTimeConversionFactor ( Submodel_t * s )

Takes a Submodel_t structure and returns its timeConversionFactor.

Parameters

s	the Submodel_t whose timeConversionFactor is sought.

Returns: the timeConversionFactor of the given Submodel_t, as a pointer to a string.

int Submodel_hasRequiredAttributes ( Submodel_t * s )

Predicate returning true or false depending on whether all the required attributes for the given Submodel_t structure have been set.

Note

The required attributes for a Submodel_t structure are:

id
modelRef

int Submodel_hasRequiredElements ( Submodel_t * s )

Predicate returning true or false depending on whether all the required elements for the given Submodel_t structure have been set.

Note: A Submodel_t structure has no required child elements.

int Submodel_isSetExtentConversionFactor ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to query.

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

int Submodel_isSetId ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to query.

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

int Submodel_isSetModelRef ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to query.

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

int Submodel_isSetName ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to query.

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

int Submodel_isSetSubstanceConversionFactor ( Submodel_t * s )

Returns false, since "substanceConversionFactor" is not a part of the comp spec.

Parameters

s	the Submodel_t structure to query.

Returns: 0 (false)

int Submodel_isSetTimeConversionFactor ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to query.

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

Deletion_t * Submodel_removeDeletion	(	Submodel_t *	s,
		unsigned int	n
	)

Removes the nth Deletion_t structure from the given Submodel_t structure and returns a pointer to it.

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

Parameters

s	the Submodel_t structure.
n	the integer index of the Deletion_t sought.

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

Deletion_t * Submodel_removeDeletionById	(	Submodel_t *	s,
		const char *	sid
	)

Removes the Deletion_t structure with the given sid from the given Submodel_t structure and returns a pointer to it.

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

Parameters

s	the Submodel_t structure.
sid	the string of the "id" attribute of the Deletion_t sought.

Returns: the Deletion_t structure removed. As mentioned above, the caller owns the returned structure. NULL is returned if no Deletion_t structure with the "id" attribute exists in the given Submodel_t structure.

int Submodel_setExtentConversionFactor	(	Submodel_t *	s,
		const char *	extentConversionFactor
	)

Sets the extentConversionFactor of the given Submodel_t to a copy of extentConversionFactor.

Parameters

s	the Submodel_t structure to set.
extentConversionFactor	the extentConversionFactor to assign to the given Submodel_t's "extentConversionFactor" attribute.

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

int Submodel_setId	(	Submodel_t *	s,
		const char *	sid
	)

Assigns the identifier of an Submodel_t structure.

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

Parameters

s	the Submodel_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:

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

Examples:: spec_example1.c.

int Submodel_setModelRef	(	Submodel_t *	s,
		const char *	modelRef
	)

Sets the modelRef of the given Submodel_t to a copy of modelRef.

Parameters

s	the Submodel_t structure to set.
modelRef	the modelRef to assign to the given Submodel_t's "modelRef" attribute.

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

Examples:: spec_example1.c.

int Submodel_setName	(	Submodel_t *	s,
		const char *	name
	)

Sets the name of the given Submodel_t to a copy of name.

Parameters

s	the Submodel_t structure to set.
name	the name to assign to the given Submodel_t's "name" attribute.

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 Submodel_setSubstanceConversionFactor	(	Submodel_t *	s,
		const char *	substanceConversionFactor
	)

Automatically fails, since "substanceConversionFactor" is not a part of the comp spec.

Parameters

s	the Submodel_t structure to set.
substanceConversionFactor	the substanceConversionFactor to ignore.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_INVALID_ATTRIBUTE_VALUE

int Submodel_setTimeConversionFactor	(	Submodel_t *	s,
		const char *	timeConversionFactor
	)

Sets the timeConversionFactor of the given Submodel_t to a copy of timeConversionFactor.

Parameters

s	the Submodel_t structure to set.
timeConversionFactor	the timeConversionFactor to assign to the given Submodel_t's "timeConversionFactor" attribute.

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

int Submodel_unsetExtentConversionFactor ( Submodel_t * s )

Unsets the "extentConversionFactor" attribute of the given Submodel_t structure.

Parameters

s	the Submodel_t structure to 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:

int Submodel_unsetId ( Submodel_t * s )

Unsets the "id" attribute of the given Submodel_t structure.

Parameters

s	the Submodel_t structure to 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:

int Submodel_unsetModelRef ( Submodel_t * s )

Unsets the "modelRef" attribute of the given Submodel_t structure.

Parameters

s	the Submodel_t structure to 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:

int Submodel_unsetName ( Submodel_t * s )

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

Parameters

s	the Submodel_t structure to 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:

int Submodel_unsetSubstanceConversionFactor ( Submodel_t * s )

Automatically fails, since "substanceConversionFactor" is not a part of the comp spec.

Parameters

s	the Submodel_t structure to unset.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:

LIBSBML_OPERATION_FAILED

int Submodel_unsetTimeConversionFactor ( Submodel_t * s )

Unsets the "timeConversionFactor" attribute of the given Submodel_t structure.

Parameters

s	the Submodel_t structure to 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:

Detailed Description

Public Member Functions

Member Function Documentation