SBMLDocument_t Class Reference

Detailed Description

Overall SBML container object.

LibSBML uses the class SBMLDocument_t as a top-level container for storing SBML content and data associated with it (such as warnings and error messages). The two primary means of reading an SBML model, SBMLReader_t::readSBML() and SBMLReader_t::readSBMLFromString(), both return a pointer to an SBMLDocument_t object. From there, callers can inquire about any errors encountered (e.g., using SBMLDocument_t::getNumErrors()), access the Model_t object, and perform other actions such as consistency-checking and model translation.

When creating fresh models programmatically, the starting point is typically the creation of an SBMLDocument_t object instance. The SBMLDocument_t constructor accepts arguments for the SBML Level and Version of the model to be created. After creating the SBMLDocument_t object, calling programs then typically call SBMLDocument_t::createModel() almost immediately, and then proceed to call the methods on the Model_t object to fill out the model's contents.

SBMLDocument_t corresponds roughly to the class Sbml defined in the SBML Level 2 specification and SBML in the Level 3 specification. It does not have a direct correspondence in SBML Level 1. (However, to make matters simpler for applications, libSBML creates an SBMLDocument_t no matter whether the model is Level 1, Level 2 or Level 3.) In its barest form, when written out in XML format for (e.g.) SBML Level 2 Version 4, the corresponding structure is the following:

<sbml xmlns="http://www.sbml.org/sbml/level2/version4" level="2" version="4">
  ...
</sbml>

SBMLDocument_t is derived from SBase_t, and therefore contains the usual SBase_t attributes (in SBML Level 2 and Level 3) of "metaid" and "sboTerm", as well as the subelements "notes" and "annotation". It also contains the attributes "level" and "version" indicating the Level and Version of the SBML data structure. These can be accessed using the methods defined by the SBase_t class for that purpose.

Checking consistency and adherence to SBML specifications

One of the most important features of libSBML is its ability to perform SBML validation to ensure that a model adheres to the SBML specification for whatever Level+Version combination the model uses. SBMLDocument_t provides the methods for running consistency-checking and validation rules on the SBML content.

First, a brief explanation of the rationale is in order. In libSBML versions up to and including the version 3.3.x series, the individual methods for creating and setting attributes and other components were quite lenient, and allowed a caller to compose SBML entities that might not, in the end, represent valid SBML. This allowed applications the freedom to do things such as save incomplete models (which is useful when models are being developed over long periods of time). In the version 4.x series, libSBML is somewhat stricter, but still permits structures to be created independently and the results to be combined in a separate step. In all these cases, it means that a separate validation step is necessary when a calling program finally wants to finish a complete SBML document.

The primary interface to this validation facility is SBMLDocument_t's SBMLDocument_t::checkInternalConsistency() and SBMLDocument_t::checkConsistency(). The former verifies the basic internal consistency and syntax of an SBML document, and the latter implements more elaborate validation rules (both those defined by the SBML specifications, as well as additional rules offered by libSBML).

The checks performed by SBMLDocument_t::checkInternalConsistency() are hardwired and cannot be changed by calling programs, but the validation performed by SBMLDocument_t::checkConsistency() is under program control using the method SBMLDocument_t::setConsistencyChecks(). Applications can selectively disable specific kinds of checks that they may not be interested in, by calling SBMLDocument_t::setConsistencyChecks() with appropriate parameters.

These methods have slightly different relevance depending on whether a model is created programmaticaly from scratch, or whether it is read in from a file or data stream. The following list summarizes the possible scenarios.

Scenario 1: Creating a model from scratch. Before writing out the model,

• Call SBMLDocument_t::checkInternalConsistency(), then inquire about the results by calling SBMLDocument_t::getNumErrors()

• Call SBMLDocument_t::setConsistencyChecks() to configure which checks will be performed by SBMLDocument_t::checkConsistency()

• Call SBMLDocument_t::checkConsistency(), then inquire about the results by calling SBMLDocument_t::getNumErrors()

Scenario 2: Reading a model from a file or data stream. After reading the model,

• Basic consistency checks will have been performed automatically by libSBML upon reading the content, so you only need to inquire about the results by using SBMLDocument_t::getNumErrors()

• Call SBMLDocument_t::setConsistencyChecks() to configure which checks are performed by SBMLDocument_t::checkConsistency()

• Call SBMLDocument_t::checkConsistency(), then inquire about the results by calling SBMLDocument_t::getNumErrors()

An example of using the consistency-checking and validation facilities is provided in this manual in the section Tutorial: creating a complete model.

It should be noted that as of SBML Level 3 Version 2, the Model_t became an optional child of SBMLDocument_t, instead of being required. This means that one can no longer use SBMLDocument_t::getModel() as a cheap method of checking if an SBML document was read in properly: the more robust getError methods detailed above must be used instead.

Converting documents between Levels and Versions of SBML

LibSBML provides facilities for limited translation of SBML between Levels and Versions of the SBML specifications. The method for doing is is setLevelAndVersion() . In general, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier Version of Level 2 to the latest Version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.

Calling SBMLDocument_t::setLevelAndVersion() will not necessarily lead to a successful conversion. The method will return a boolean value to indicate success or failure. Callers must check the error log (see next section) attached to the SBMLDocument_t object after calling SBMLDocument_t::setLevelAndVersion() in order to assess whether any problems arose.

If an application is interested in translating to a lower Level and/or Version of SBML within a Level, the following methods allow for prior assessment of whether there is sufficient compatibility to make a translation possible:

• SBMLDocument_t::checkL1Compatibility(),
• SBMLDocument_t::checkL2v1Compatibility(),
• SBMLDocument_t::checkL2v2Compatibility(),
• SBMLDocument_t::checkL2v3Compatibility(),
• SBMLDocument_t::checkL2v4Compatibility(),
• SBMLDocument_t::checkL2v5Compatibility(), and
• SBMLDocument_t::checkL3v1Compatibility().

Some changes between Versions of SBML Level 2 may lead to unexpected behaviors when attempting conversions in either direction. For example, SBML Level 2 Version 4 relaxed the requirement for consistency in units of measurement between expressions annd quantities in a model. As a result, a model written in Version 4, if converted to Version 3 with no other changes, may fail validation as a Version 3 model because Version 3 imposed stricter requirements on unit consistency.

Other changes between SBML Level 2 and Level 3 make downward conversions challenging. In some cases, it means that a model converted to Level 2 from Level 3 will contain attributes that were not explicitly given in the Level 3 model, because in Level 2 these attributes may have been optional or have default values.

Error handling

Upon reading a model, SBMLDocument_t logs any problems encountered while reading the model from the file or data stream. The log contains objects that record diagnostic information about any notable issues that arose. Whether the problems are warnings or errors, they are both reported through a single common interface involving the object class SBMLError_t.

The methods SBMLDocument_t::getNumErrors(), SBMLDocument_t::getError() and SBMLDocument_t::printErrors() allow callers to interact with the warnings or errors logged. Alternatively, callers may retrieve the entire log as an SBMLErrorLog_t object using the method SBMLDocument_t::getErrorLog(). The SBMLErrorLog_t object provides some alternative methods for interacting with the set of errors and warnings. In either case, applications typically should first call SBMLDocument_t::getNumErrors() to find out if any issues have been logged after specific libSBML operations such as the ones discussed in the sections above. If they have, then an application will should proceed to inspect the individual reports using either the direct interfaces on SBMLDocument_t or using the methods on the SBMLErrorLog_t object.

An example of using the error facility is provided in this manual in the section Tutorial: creating a complete model.

Examples:

addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, createExampleSBML.c, echoSBML.c, flattenModel.c, printAnnotation.c, printMath.c, printNotes.c, printSBML.c, printUnits.c, promoteParameters.c, readSBML.c, spec_example1.c, stripPackage.c, translateL3Math.c, unsetAnnotation.c, unsetNotes.c, and validateSBML.c.

Public Member Functions
unsigned int	SBMLDocument_checkConsistency (SBMLDocument_t *d)
	Performs a set of consistency and validation checks on the given SBML document. More...
unsigned int	SBMLDocument_checkInternalConsistency (SBMLDocument_t *d)
	Performs consistency checking on libSBML's internal representation of an SBML Model_t. More...
unsigned int	SBMLDocument_checkL1Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1. More...
unsigned int	SBMLDocument_checkL2v1Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1. More...
unsigned int	SBMLDocument_checkL2v2Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2. More...
unsigned int	SBMLDocument_checkL2v3Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3. More...
unsigned int	SBMLDocument_checkL2v4Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4. More...
unsigned int	SBMLDocument_checkL2v5Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5. More...
unsigned int	SBMLDocument_checkL3v1Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1. More...
unsigned int	SBMLDocument_checkL3v2Compatibility (SBMLDocument_t *d)
	Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2. More...
SBMLDocument_t *	SBMLDocument_clone (const SBMLDocument_t *d)
	Creates and returns a deep copy of the given SBMLDocument_t structure. More...
int	SBMLDocument_convert (SBMLDocument_t *d, const ConversionProperties_t *props)
	Converts this document using the converter that best matches the given conversion properties. More...
SBMLDocument_t *	SBMLDocument_create (void)
	Creates a new, empty SBMLDocument_t structure. More...
Model_t *	SBMLDocument_createModel (SBMLDocument_t *d)
	Creates a new Model_t structure inside the given SBMLDocument_t structure and returns a pointer to it. More...
SBMLDocument_t *	SBMLDocument_createWithLevelAndVersion (unsigned int level, unsigned int version)
	Creates a new, empty SBMLDocument_t structure with given values for the SBML Level and Version. More...
SBMLDocument_t *	SBMLDocument_createWithSBMLNamespaces (SBMLNamespaces_t *sbmlns)
	Creates a new SBMLDocument_t using the given SBMLNamespaces_t structure sbmlns. More...
int	SBMLDocument_expandFunctionDefintions (SBMLDocument_t *d)
	Removes any FunctionDefinition_t's from the document and expands any instances of their use within <math> elements. More...
int	SBMLDocument_expandInitialAssignments (SBMLDocument_t *d)
	Removes any InitialAssignment_t's from the document and replaces the appropriate values. More...
void	SBMLDocument_free (SBMLDocument_t *d)
	Frees the given SBMLDocument_t structure. More...
unsigned int	SBMLDocument_getDefaultLevel ()
unsigned int	SBMLDocument_getDefaultVersion ()
const SBMLError_t *	SBMLDocument_getError (SBMLDocument_t *d, unsigned int n)
	Returns the nth error or warning encountered during parsing, consistency checking, or attempted translation of this model. More...
const SBMLError_t *	SBMLDocument_getErrorWithSeverity (SBMLDocument_t *d, unsigned int n, unsigned int severity)
	Returns the nth error or warning with the given severity encountered during parsing, consistency checking, or attempted translation of this model. More...
unsigned int	SBMLDocument_getLevel (const SBMLDocument_t *d)
	Returns the SBML Level of the given SBMLDocument_t structure. More...
char *	SBMLDocument_getLocationURI (SBMLDocument_t *d)
	Get the location of this SBMLDocument_t. More...
Model_t *	SBMLDocument_getModel (SBMLDocument_t *d)
	Returns the Model_t structure stored in this SBMLDocument_t structure. More...
const XMLNamespaces_t *	SBMLDocument_getNamespaces (SBMLDocument_t *d)
	Returns a list of XMLNamespaces_t associated with the XML content of this SBML document. More...
unsigned int	SBMLDocument_getNumErrors (const SBMLDocument_t *d)
	Returns the number of errors or warnings encountered during parsing, consistency checking, or attempted translation of this model. More...
unsigned int	SBMLDocument_getNumErrorsWithSeverity (const SBMLDocument_t *d, unsigned int severity)
	Returns the number of errors or warnings encountered during parsing, consistency checking, or attempted translation of this model. More...
int	SBMLDocument_getPackageRequired (SBMLDocument_t *d, const char *package)
	Returns the required attribute of the given package extension. More...
int	SBMLDocument_getPkgRequired (SBMLDocument_t *d, const char *package)
	Returns the required attribute of the given package extension. More...
unsigned int	SBMLDocument_getVersion (const SBMLDocument_t *d)
	Returns the Version within the SBML Level of the given SBMLDocument_t structure. More...
int	SBMLDocument_isSetModel (const SBMLDocument_t *d)
	Predicate for testing whether the identifier of a given SBMLDocument_t structure is assigned. More...
int	SBMLDocument_isSetPackageRequired (SBMLDocument_t *d, const char *package)
	Tests whether the required attribute of the given package extension is defined. More...
int	SBMLDocument_isSetPkgRequired (SBMLDocument_t *d, const char *package)
	Tests whether the required attribute of the given package extension is defined. More...
void	SBMLDocument_printErrors (SBMLDocument_t *d, FILE *stream)
	Prints to the given output stream all the errors or warnings encountered during parsing, consistency checking, or attempted translation of this model. More...
void	SBMLDocument_setConsistencyChecks (SBMLDocument_t *d, SBMLErrorCategory_t category, int apply)
	Allows particular validators to be turned on or off prior to calling checkConsistency. More...
void	SBMLDocument_setConsistencyChecksForConversion (SBMLDocument_t *d, SBMLErrorCategory_t category, int apply)
	Allows particular validators to be turned on or off prior to calling setLevelAndVersion. More...
int	SBMLDocument_setLevelAndVersion (SBMLDocument_t *d, unsigned int level, unsigned int version)
	Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed. More...
int	SBMLDocument_setLevelAndVersionNonStrict (SBMLDocument_t *d, unsigned int level, unsigned int version)
	Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed. More...
int	SBMLDocument_setLevelAndVersionStrict (SBMLDocument_t *d, unsigned int level, unsigned int version)
	Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed. More...
void	SBMLDocument_setLocationURI (SBMLDocument_t *d, const char *location)
	Sets the location of this SBMLDocument_t. More...
int	SBMLDocument_setModel (SBMLDocument_t *d, const Model_t *m)
	Sets the model contained in the given SBMLDocument_t structure to a copy of the given Model_t structure. More...
int	SBMLDocument_setPackageRequired (SBMLDocument_t *d, const char *package, int flag)
	Sets the value of the required attribute for the given package. More...
int	SBMLDocument_setPkgRequired (SBMLDocument_t *d, const char *package, int flag)
	Sets the value of the required attribute for the given package. More...
int	SBMLDocument_setSBMLNamespaces (SBMLDocument_t *d, SBMLNamespaces_t *sbmlns)
	Sets the SBMLNamespaces_t on the given SBMLDocument_t. More...
unsigned int	SBMLDocument_validateSBML (SBMLDocument_t *d)
	Performs consistency checking and validation on the given SBML document. More...

Member Function Documentation

unsigned int SBMLDocument_checkConsistency

(

SBMLDocument_t *

d

)

Performs a set of consistency and validation checks on the given SBML document.

If this method returns a nonzero value (meaning, one or more consistency checks have failed for SBML document), the failures may be due to warnings or errors. Callers should inspect the severity flag in the individual SBMLError_t structures returned by SBMLDocument_getError() to determine the nature of the failures.

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

Examples:

createExampleSBML.c, and validateSBML.c.

unsigned int SBMLDocument_checkInternalConsistency

(

SBMLDocument_t *

d

)

Performs consistency checking on libSBML's internal representation of an SBML Model_t.

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

Note

The consistency checks performed by this function are limited to inconsistencies that are not caught by other consistency checks.

See also

setConsistencyChecks()

Examples:

createExampleSBML.c.

unsigned int SBMLDocument_checkL1Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL2v1Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL2v2Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL2v3Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL2v4Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL2v5Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL3v1Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

unsigned int SBMLDocument_checkL3v2Compatibility

(

SBMLDocument_t *

d

)

Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2.

Callers should query the results of the consistency check by calling SBMLDocument_getError().

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

SBMLDocument_t * SBMLDocument_clone

(

const SBMLDocument_t *

d

)

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

Parameters

d	the SBMLDocument_t structure.

Returns

a (deep) copy of the SBMLDocument_t structure

int SBMLDocument_convert	(	SBMLDocument_t *	d,
		const ConversionProperties_t *	props
	)

Converts this document using the converter that best matches the given conversion properties.

Parameters

d	the SBMLDocument_t structure.
props	the conversion properties 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_OPERATION_FAILED
• LIBSBML_CONV_CONVERSION_NOT_AVAILABLE
• LIBSBML_INVALID_OBJECT

Examples:

flattenModel.c, promoteParameters.c, and stripPackage.c.

SBMLDocument_t * SBMLDocument_create

(

void

)

Creates a new, empty SBMLDocument_t structure.

The SBML Level and Version attributes default to the most recent SBML specification (at the time this libSBML was released).

Returns

the SBMLDocument_t structure created

Model_t * SBMLDocument_createModel

(

SBMLDocument_t *

d

)

Creates a new Model_t structure inside the given SBMLDocument_t structure and returns a pointer to it.

Parameters

d	the SBMLDocument_t structure.

Returns

the Model_t structure created

Examples:

createExampleSBML.c, and spec_example1.c.

SBMLDocument_t * SBMLDocument_createWithLevelAndVersion	(	unsigned int	level,
		unsigned int	version
	)

Creates a new, empty SBMLDocument_t structure with given values for the SBML Level and Version.

If not specified, the SBML Level and Version attributes default to the most recent SBML specification (at the time this libSBML was released).

Parameters

level	an integer for the SBML Level.
version	an integer for the Version within the SBML Level.

Returns

the SBMLDocument_t structure created

Examples:

createExampleSBML.c.

SBMLDocument_t * SBMLDocument_createWithSBMLNamespaces

(

SBMLNamespaces_t *

sbmlns

)

Creates a new SBMLDocument_t using the given SBMLNamespaces_t structure sbmlns.

Returns NULL if the sbmlns is invalid.

The SBMLNamespaces_t object encapsulates SBML Level/Version/namespaces information. It is used to communicate the SBML Level, Version, and (in Level 3) packages used in addition to SBML Level 3 Core. A common approach to using libSBML's SBMLNamespaces_t facilities is to create an SBMLNamespaces_t object somewhere in a program once, then hand that object as needed to object constructors that accept SBMLNamespaces_t as arguments.

Parameters

sbmlns

an SBMLNamespaces_t structure.

Examples:

spec_example1.c.

int SBMLDocument_expandFunctionDefintions

(

SBMLDocument_t *

d

)

Removes any FunctionDefinition_t's from the document and expands any instances of their use within <math> elements.

For example a Model_t contains a FunctionDefinition_t with id f representing the math expression: f(x, y) = x * y. The math element of the KineticLaw_t uses f(s, p). The outcome of the function is that the math of the KineticLaw_t now represents the math expression: s * p and the model no longer contains any FunctionDefinition_t's.

Parameters

d	the SBMLDocument_t structure.

Returns

1 (true) if the transformation was successful, 0 (false) otherwise.

Note

This function will check the consistency of a model before attemptimg the transformation. In the case of a model with invalid SBML the transformation will not be done and the function will return false.

int SBMLDocument_expandInitialAssignments

(

SBMLDocument_t *

d

)

Removes any InitialAssignment_t's from the document and replaces the appropriate values.

For example a Model_t contains a InitialAssignment_t with symbol k where k is the id of a Parameter_t. The outcome of the function is that the value attribute of the Parameter_t is the value calculated using the math expression of the InitialAssignment_t and the corresponding InitialAssignment_t has been removed from the Model_t.

Parameters

d	the SBMLDocument_t structure.

Returns

1 (true) if the transformation was successful, 0 (false) otherwise.

Note

This function will check the consistency of a model before attemptimg the transformation. In the case of a model with invalid SBML the transformation will not be done and the function will return false. As part of the process the function will check that it has values for any components referred to by the math elements of InitialAssignment_t's. In the case where not all values have been declared the particular InitialAssignment_t will not be removed and the function will return false.

void SBMLDocument_free

(

SBMLDocument_t *

d

)

Frees the given SBMLDocument_t structure.

Parameters

d	the SBMLDocument_t structure.

Examples:

addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, createExampleSBML.c, printAnnotation.c, printMath.c, printNotes.c, printSBML.c, printUnits.c, readSBML.c, translateL3Math.c, unsetAnnotation.c, unsetNotes.c, and validateSBML.c.

unsigned int SBMLDocument_getDefaultLevel

(

)

Returns

the most recent SBML specification level (at the time this libSBML was released).

Examples:

convertSBML.c.

unsigned int SBMLDocument_getDefaultVersion

(

)

Returns

the most recent SBML specification version (at the time this libSBML was released).

Examples:

convertSBML.c.

const SBMLError_t * SBMLDocument_getError	(	SBMLDocument_t *	d,
		unsigned int	n
	)

Returns the nth error or warning encountered during parsing, consistency checking, or attempted translation of this model.

Callers can use method XMLError_getSeverity() on the result to assess the severity of the problem. The severity levels range from informationl messages to fatal errors.

Returns

the error or warning indexed by integer n, or return NULL if n > (SBMLDocument_getNumErrors() - 1).

Parameters

d	the SBMLDocument_t structure.
n	the index of the error sought.

See also

SBMLDocument_getNumErrors(), SBMLDocument_setLevelAndVersion(), SBMLDocument_checkConsistency(), SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility() SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), SBMLDocument_checkL3v2Compatibility(), SBMLReader_readSBML(), SBMLReader_readSBMLFromString().

Examples:

createExampleSBML.c.

const SBMLError_t * SBMLDocument_getErrorWithSeverity	(	SBMLDocument_t *	d,
		unsigned int	n,
		unsigned int	severity
	)

Returns the nth error or warning with the given severity encountered during parsing, consistency checking, or attempted translation of this model.

Returns

the error or warning indexed by integer n, or return NULL if n > (SBMLDocument_getNumErrorsWithSeverity() - 1).

Parameters

d	the SBMLDocument_t structure.
n	the index of the error sought.
severity	the severity of the error sought.

See also

SBMLDocument_getNumErrorsWithSeverity(), SBMLDocument_setLevelAndVersion(), SBMLDocument_checkConsistency(), SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility() SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), SBMLDocument_checkL3v2Compatibility(), SBMLReader_readSBML(), SBMLReader_readSBMLFromString().

unsigned int SBMLDocument_getLevel

(

const SBMLDocument_t *

d

)

Returns the SBML Level of the given SBMLDocument_t structure.

Parameters

d	the SBMLDocument_t structure.

Returns

the SBML Level number

Examples:

convertSBML.c, and printSBML.c.

char * SBMLDocument_getLocationURI

(

SBMLDocument_t *

d

)

Get the location of this SBMLDocument_t.

If this document was read from a file or had its location set manually, that filename or set location will be returned, otherwise, an empty string is returned.

Parameters

d	the SBMLDocument_t structure to query.

Returns

The filename or set location of the document, or an empty string if no such information is found.

Model_t * SBMLDocument_getModel

(

SBMLDocument_t *

d

)

Returns the Model_t structure stored in this SBMLDocument_t structure.

Parameters

d	the SBMLDocument_t structure.

Returns

the Model_t contained in this SBMLDocument_t structure.

Examples:

addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, createExampleSBML.c, printAnnotation.c, printMath.c, printNotes.c, printSBML.c, printUnits.c, translateL3Math.c, unsetAnnotation.c, and unsetNotes.c.

const XMLNamespaces_t * SBMLDocument_getNamespaces

(

SBMLDocument_t *

d

)

Returns a list of XMLNamespaces_t associated with the XML content of this SBML document.

Parameters

d	the SBMLDocument_t structure.

Returns

pointer to the XMLNamespaces_t structure associated with this SBML structure.

Examples:

createExampleSBML.c.

unsigned int SBMLDocument_getNumErrors

(

const SBMLDocument_t *

d

)

Returns the number of errors or warnings encountered during parsing, consistency checking, or attempted translation of this model.

Parameters

d	the SBMLDocument_t structure.

Returns

the number of errors or warnings encountered

See also

SBMLDocument_setLevelAndVersion(), SBMLDocument_checkConsistency(), SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility() SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), SBMLDocument_checkL3v2Compatibility(), SBMLReader_readSBML(), SBMLReader_readSBMLFromString().

Examples:

addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, echoSBML.c, printAnnotation.c, printNotes.c, printUnits.c, readSBML.c, unsetAnnotation.c, unsetNotes.c, and validateSBML.c.

unsigned int SBMLDocument_getNumErrorsWithSeverity	(	const SBMLDocument_t *	d,
		unsigned int	severity
	)

Returns the number of errors or warnings encountered during parsing, consistency checking, or attempted translation of this model.

Parameters

d	the SBMLDocument_t structure.
severity	the severity requested.

Returns

the number of errors or warnings encountered with the given severity level

See also

SBMLDocument_setLevelAndVersion(), SBMLDocument_checkConsistency(), SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility() SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), SBMLDocument_checkL3v2Compatibility(), SBMLReader_readSBML(), SBMLReader_readSBMLFromString().

Examples:

flattenModel.c, promoteParameters.c, and stripPackage.c.

int SBMLDocument_getPackageRequired	(	SBMLDocument_t *	d,
		const char *	package
	)

Returns the required attribute of the given package extension.

Parameters

d	the SBMLDocument_t structure to check.
package	the name or URI of the package extension.

Returns

1 (true) if the package is flagged as being required in this SBML document, 0 (false) otherwise.

int SBMLDocument_getPkgRequired	(	SBMLDocument_t *	d,
		const char *	package
	)

Returns the required attribute of the given package extension.

Parameters

d	the SBMLDocument_t structure to check.
package	the name or URI of the package extension.

Returns

1 (true) if the package is flagged as being required in this SBML document, 0 (false) otherwise.

unsigned int SBMLDocument_getVersion

(

const SBMLDocument_t *

d

)

Returns the Version within the SBML Level of the given SBMLDocument_t structure.

Parameters

d	the SBMLDocument_t structure.

Returns

the version number

Examples:

convertSBML.c, and printSBML.c.

int SBMLDocument_isSetModel

(

const SBMLDocument_t *

d

)

Predicate for testing whether the identifier of a given SBMLDocument_t structure is assigned.

Parameters

d	the SBMLDocument_t structure.

Returns

1 (true) if the model object of this SBMLDocument_t structure is set, 0 (false) otherwise.

int SBMLDocument_isSetPackageRequired	(	SBMLDocument_t *	d,
		const char *	package
	)

Tests whether the required attribute of the given package extension is defined.

Parameters

d	the SBMLDocument_t structure.
package	the name or URI of the package extension.

Returns

1 (true) if the required attribute of the given package extension is defined, 0 (false) otherwise.

int SBMLDocument_isSetPkgRequired	(	SBMLDocument_t *	d,
		const char *	package
	)

Tests whether the required attribute of the given package extension is defined.

Parameters

d	the SBMLDocument_t structure.
package	the name or URI of the package extension.

Returns

1 (true) if the required attribute of the given package extension is defined, 0 (false) otherwise.

void SBMLDocument_printErrors	(	SBMLDocument_t *	d,
		FILE *	stream
	)

Prints to the given output stream all the errors or warnings encountered during parsing, consistency checking, or attempted translation of this model.

If no errors have occurred, i.e., SBMLDocument_getNumErrors() == 0, no output will be sent to the stream.

The format of the output is:

N error(s): line NNN: (id) message

Parameters

d	the SBMLDocument_t structure.
stream	the output stream where the messages should be printed.

Examples:

addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, createExampleSBML.c, echoSBML.c, flattenModel.c, printAnnotation.c, printMath.c, printNotes.c, printSBML.c, printUnits.c, promoteParameters.c, readSBML.c, stripPackage.c, unsetAnnotation.c, unsetNotes.c, and validateSBML.c.

void SBMLDocument_setConsistencyChecks	(	SBMLDocument_t *	d,
		SBMLErrorCategory_t	category,
		int	apply
	)

Allows particular validators to be turned on or off prior to calling checkConsistency.

The second argument (category) to this method indicates which category of consistency/error checks are being turned on or off, and the third argument (an integer treated as a boolean, with nonzero indicating true and zero indicating false) indicates whether to turn on (true) or off (false) that particular category of checks. The possible categories are represented as values of the enumeration SBMLErrorCategory_t. The following are the possible choices:

• LIBSBML_CAT_GENERAL_CONSISTENCY: General overall SBML consistency.

• LIBSBML_CAT_IDENTIFIER_CONSISTENCY: Consistency of identifiers. An example of inconsistency would be using a species identifier in a reaction rate formula without first having declared the species.

• LIBSBML_CAT_UNITS_CONSISTENCY: Consistency of units of measure.

• LIBSBML_CAT_MATHML_CONSISTENCY: Consistency of MathML constructs.

• LIBSBML_CAT_SBO_CONSISTENCY: Consistency of SBO_t identifiers.

• LIBSBML_CAT_OVERDETERMINED_MODEL: Checking whether the system of equations implied by a model is mathematically overdetermined.

• LIBSBML_CAT_MODELING_PRACTICE: General good practice in model construction.

By default, all validation checks are applied to the model in an SBMLDocument_t structure unless setConsistencyChecks() is called to indicate that only a subset should be applied.

Parameters

d	the SBMLDocument_t structure.
category	a value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off.
apply	an integer indicating whether the checks indicated by category should be applied or not, with nonzero indicating true, and zero indicating false.

Note

The default (i.e., performing all checks) applies to each new SBMLDocument_t structure created. This means that each time a model is read using SBMLReader_readSBML(), SBMLReader_readSBMLFromString(), or the global functions readSBML() and readSBMLFromString(), a new SBMLDocument_t is created and for that document all checks are enabled.

See also

SBMLDocument_checkConsistency()

void SBMLDocument_setConsistencyChecksForConversion	(	SBMLDocument_t *	d,
		SBMLErrorCategory_t	category,
		int	apply
	)

Allows particular validators to be turned on or off prior to calling setLevelAndVersion.

The second argument (category) to this method indicates which category of consistency/error checks are being turned on or off, and the second argument (a boolean) indicates whether to turn on (value of true) or off (value of false) that particula category of checks. The possible categories are represented as values of the enumeration SBMLErrorCategory_t. The following are the possible choices in libSBML version 3.0.2:

• LIBSBML_CAT_GENERAL_CONSISTENCY: General overall SBML consistency.

• LIBSBML_CAT_IDENTIFIER_CONSISTENCY: Consistency of identifiers. An example of inconsistency would be using a species identifier in a reaction rate formula without first having declared the species.

• LIBSBML_CAT_UNITS_CONSISTENCY: Consistency of units of measure.

• LIBSBML_CAT_MATHML_CONSISTENCY: Consistency of MathML constructs.

• LIBSBML_CAT_SBO_CONSISTENCY: Consistency of SBO_t identifiers.

• LIBSBML_CAT_OVERDETERMINED_MODEL: Checking whether the system of equations implied by a model is mathematically overdetermined.

• LIBSBML_CAT_MODELING_PRACTICE: General good practice in model construction.

By default, all validation checks are applied to the model in an SBMLDocument_t structure unless setConsistencyChecks() is called to indicate that only a subset should be applied.

Parameters

d	the SBMLDocument_t structure.
category	a value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off.
apply	an integer indicating whether the checks indicated by category should be applied or not, with nonzero indicating true, and zero indicating false.

Note

The default (i.e., performing all checks) applies to each new SBMLDocument_t structure created. This means that each time a model is read using SBMLReader_readSBML(), SBMLReader_readSBMLFromString(), or the global functions readSBML() and readSBMLFromString(), a new SBMLDocument_t is created and for that document all checks are enabled.

See also

SBMLDocument_setLevelAndVersionStrict()

int SBMLDocument_setLevelAndVersion	(	SBMLDocument_t *	d,
		unsigned int	level,
		unsigned int	version
	)

Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed.

This method is used to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier version of Level 2 to the latest version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.

Callers can also check compatibility directly using the methods SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility(), SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), and SBMLDocument_checkL3v2Compatibility().

The valid combinations as of this release of libSBML are the following:

• Level 1 Version 1
• Level 1 Version 2
• Level 2 Version 1
• Level 2 Version 2
• Level 2 Version 3
• Level 2 Version 4
• Level 2 Version 5
• Level 3 Version 1
• Level 3 Version 2

Parameters

d	the SBMLDocument_t structure.
level	the desired SBML Level.
version	the desired Version within the SBML Level.

Note

Calling this method will not necessarily lead to successful conversion. If the conversion fails, it will be logged in the error list associated with this SBMLDocument_t structure. Callers should consult SBMLDocument_getNumErrors() to find out if the conversion succeeded without problems. For conversions from Level 2 to Level 1, callers can also check the Level of the model after calling this method to find out whether it is Level 1. (If the conversion to Level 1 failed, the Level of this model will be left unchanged.)

Examples:

convertSBML.c.

int SBMLDocument_setLevelAndVersionNonStrict	(	SBMLDocument_t *	d,
		unsigned int	level,
		unsigned int	version
	)

Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed.

This method is used to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier version of Level 2 to the latest version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.

Callers can also check compatibility directly using the methods SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility(), SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), and SBMLDocument_checkL3v2Compatibility().

The valid combinations as of this release of libSBML are the following:

• Level 1 Version 1
• Level 1 Version 2
• Level 2 Version 1
• Level 2 Version 2
• Level 2 Version 3
• Level 2 Version 4
• Level 2 Version 5
• Level 3 Version 1
• Level 3 Version 2

Parameters

d	the SBMLDocument_t structure.
level	the desired SBML Level.
version	the desired Version within the SBML Level.

Note

Calling this method will not necessarily lead to successful conversion. If the conversion fails, it will be logged in the error list associated with this SBMLDocument_t structure. Callers should consult SBMLDocument_getNumErrors() to find out if the conversion succeeded without problems. For conversions from Level 2 to Level 1, callers can also check the Level of the model after calling this method to find out whether it is Level 1. (If the conversion to Level 1 failed, the Level of this model will be left unchanged.)

int SBMLDocument_setLevelAndVersionStrict	(	SBMLDocument_t *	d,
		unsigned int	level,
		unsigned int	version
	)

Sets the SBML Level and Version of this SBMLDocument_t, attempting to convert the model as needed.

This method is used to convert models between Levels and Versions of SBML. Generally, models can be converted upward without difficulty (e.g., from SBML Level 1 to Level 2, or from an earlier version of Level 2 to the latest version of Level 2). Sometimes models can be translated downward as well, if they do not use constructs specific to more advanced Levels of SBML.

Callers can also check compatibility directly using the methods SBMLDocument_checkL1Compatibility(), SBMLDocument_checkL2v1Compatibility(), SBMLDocument_checkL2v2Compatibility(), SBMLDocument_checkL2v3Compatibility(), SBMLDocument_checkL2v4Compatibility(), SBMLDocument_checkL2v5Compatibility(), SBMLDocument_checkL3v1Compatibility(), and SBMLDocument_checkL3v2Compatibility().

The valid combinations as of this release of libSBML are the following:

• Level 1 Version 1
• Level 1 Version 2
• Level 2 Version 1
• Level 2 Version 2
• Level 2 Version 3
• Level 2 Version 4
• Level 2 Version 5
• Level 3 Version 1
• Level 3 Version 2

Parameters

d	the SBMLDocument_t structure.
level	the desired SBML Level.
version	the desired Version within the SBML Level.

Note

Calling this method will not necessarily lead to successful conversion. If the conversion fails, it will be logged in the error list associated with this SBMLDocument_t structure. Callers should consult SBMLDocument_getNumErrors() to find out if the conversion succeeded without problems. For conversions from Level 2 to Level 1, callers can also check the Level of the model after calling this method to find out whether it is Level 1. (If the conversion to Level 1 failed, the Level of this model will be left unchanged.)

Strict conversion applies the additional criteria that both the source and the target model must be consistent SBML. Users can control the consistency checks that are applied using the SBMLDocument_setConsistencyChecks() function. If either the source or the potential target model have validation errors, the conversion is not performed. When a strict conversion is successful, the underlying SBML structure model is altered to reflect the new level and version. Thus information that cannot be converted (e.g. sboTerms) will be lost.

void SBMLDocument_setLocationURI	(	SBMLDocument_t *	d,
		const char *	location
	)

Sets the location of this SBMLDocument_t.

Called automatically when readSBMLFromFile() is used, but may be set manually as well.

Parameters

d	the SBMLDocument_t structure.
location	the location URI of the document.

int SBMLDocument_setModel	(	SBMLDocument_t *	d,
		const Model_t *	m
	)

Sets the model contained in the given SBMLDocument_t structure to a copy of the given Model_t structure.

Parameters

d	the SBMLDocument_t structure.
m	the new Model_t structure 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_LEVEL_MISMATCH
• LIBSBML_VERSION_MISMATCH

int SBMLDocument_setPackageRequired	(	SBMLDocument_t *	d,
		const char *	package,
		int	flag
	)

Sets the value of the required attribute for the given package.

Parameters

d	the SBMLDocument_t structure.
package	the name or URI of the package extension.
flag	integer, with nonzero indicating true, and zero indicating false.

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_PKG_UNKNOWN_VERSION

int SBMLDocument_setPkgRequired	(	SBMLDocument_t *	d,
		const char *	package,
		int	flag
	)

Sets the value of the required attribute for the given package.

Parameters

d	the SBMLDocument_t structure.
package	the name or URI of the package extension.
flag	integer, with nonzero indicating true, and zero indicating false.

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_PKG_UNKNOWN_VERSION

int SBMLDocument_setSBMLNamespaces	(	SBMLDocument_t *	d,
		SBMLNamespaces_t *	sbmlns
	)

Sets the SBMLNamespaces_t on the given SBMLDocument_t.

Parameters

d	the SBMLDocument_t structure to change.
sbmlns	the SBMLNamespaces_t structure to 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:

• LIBSBML_OPERATION_SUCCESS
• LIBSBML_INVALID_OBJECT

unsigned int SBMLDocument_validateSBML

(

SBMLDocument_t *

d

)

Performs consistency checking and validation on the given SBML document.

If this method returns a nonzero value (meaning, one or more consistency checks have failed for SBML document), the failures may be due to warnings or errors. Callers should inspect the severity flag in the individual SBMLError_t structures returned by SBMLDocument_getError() to determine the nature of the failures.

Note

unlike SBMLDocument_checkConsistency(), this method will write the document in order to determine all errors for the document. This will also clear the error log.

Parameters

d	the SBMLDocument_t structure.

Returns

the number of failed checks (errors) encountered.

See also

SBMLDocument_checkConsistency()