public class Constraint extends SBase
The Constraint
object class was introduced in SBML Level 2
Version 2 as a mechanism for stating the assumptions under which a
model is designed to operate. The constraints are statements
about permissible values of different quantities in a model.
Constraints are not used to compute dynamical values for simulation or
analysis, but rather, they serve an advisory role for
simulation/analysis tools.
SBML's Constraint
object class has one required attribute, 'id', to
give the parameter a unique identifier by which other parts of an SBML
model definition can refer to it. A Constraint
object can also have an
optional 'name' attribute of type string.
Identifiers and names must
be used according to the guidelines described in the SBML specification
(e.g., Section 3.3 in the Level 2 Version 4 specification).
Constraint
has one required subelement, 'math', containing a MathML
formula defining the condition of the constraint. This formula must
return a boolean value of true
when the model is a valid
state. The formula can be an arbitrary expression referencing the
variables and other entities in an SBML model. The evaluation of 'math'
and behavior of constraints are described in more detail below.
A Constraint
structure also has an optional subelement called 'message'.
This can contain a message in XHTML format that may be displayed to the
user when the condition of the formula in the 'math' subelement
evaluates to a value of false.
Software tools are not required to
display the message, but it is recommended that they do so as a matter
of best practice. The XHTML content within a 'message' subelement must
follow the same restrictions as for the 'notes' element on SBase
described in in the SBML Level 2 specification please consult the
SBML
specification document corresponding to the SBML Level and Version
of your model for more information about the requirements for 'notes'
content.
Constraint
was introduced in SBML Level 2 Version 2. It is
not available in earlier versions of Level 2 nor in any version of
Level 1.
In the context of a simulation, a Constraint
has effect at all times
t ≥ 0. Each Constraint
's 'math' subelement is first
evaluated after any InitialAssignment
definitions in a model at t =
0 and can conceivably trigger at that point. (In other words, a
simulation could fail a constraint immediately.)
Constraint
structures cannot and should not be used to compute
the dynamical behavior of a model as part of, for example, simulation.
Constraints may be used as input to non-dynamical analysis, for instance
by expressing flux constraints for flux balance analysis.
The results of a simulation of a model containing a constraint are
invalid from any simulation time at and after a point when the function
given by the 'math' subelement returns a value of false.
Invalid
simulation results do not make a prediction of the behavior of the
biochemical reaction network represented by the model. The precise
behavior of simulation tools is left undefined with respect to
constraints. If invalid results are detected with respect to a given
constraint, the 'message' subelement may optionally be displayed to the
user. The simulation tool may also halt the simulation or clearly
delimit in output data the simulation time point at which the simulation
results become invalid.
SBML does not impose restrictions on duplicate Constraint
definitions or
the order of evaluation of Constraint
objects in a model. It is
possible for a model to define multiple constraints all with the same
mathematical expression. Since the failure of any constraint indicates
that the model simulation has entered an invalid state, a system is not
required to attempt to detect whether other constraints in the model
have failed once any one constraint has failed.
Constructor and Description |
---|
Constraint(Constraint orig)
Copy constructor creates a copy of this
Constraint . |
Constraint(long level,
long version)
|
Constraint(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
Constraint |
cloneObject()
Creates and returns a deep copy of this
Constraint . |
void |
delete()
Explicitly deletes the underlying native object.
|
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Constraint , is
always 'constraint'. |
ASTNode |
getMath()
Get the mathematical expression of this
Constraint |
XMLNode |
getMessage()
Get the message, if any, associated with this
Constraint |
java.lang.String |
getMessageString()
Get the message string, if any, associated with this
Constraint |
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for this Constraint object
have been set. |
boolean |
isSetMath()
Predicate returning
true if a
mathematical formula is defined for this Constraint . |
boolean |
isSetMessage()
Predicate returning
true if a
message is defined for this Constraint . |
void |
renameSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
SIdRef attributes on this element, including any
found in MathML. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
UnitSIdRef attributes on this element. |
int |
setMath(ASTNode math)
Sets the mathematical expression of this
Constraint to a copy of the
AST given as math . |
int |
setMessage(XMLNode xhtml)
Sets the message of this
Constraint . |
int |
unsetMessage()
Unsets the 'message' subelement of this
Constraint . |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm
public Constraint(Constraint orig) throws SBMLConstructorException
Constraint
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public Constraint(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Constraint
version
- a long integer, the SBML Version to assign to this
Constraint
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Constraint
object to an SBMLDocument
(e.g., using Model.addConstraint(Constraint c)
), the
SBML Level, SBML Version and XML namespace of the document
override the values used when creating the Constraint
object via this
constructor. This is necessary to ensure that an SBML document is a
consistent structure. Nevertheless, the ability to supply the values
at the time of creation of a Constraint
is an important aid to
producing valid SBML. Knowledge of the intented SBML Level and
Version determine whether it is valid to assign a particular value to
an attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public Constraint(SBMLNamespaces sbmlns) throws SBMLConstructorException
Constraint
using the given SBMLNamespaces
object
sbmlns
.
The SBMLNamespaces
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
facilities is to create an
SBMLNamespaces
object somewhere in a program once, then hand that object
as needed to object constructors that accept SBMLNamespaces
as arguments.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Constraint
object to an SBMLDocument
(e.g., using Model.addConstraint(Constraint c)
), the
SBML Level, SBML Version and XML namespace of the document
override the values used when creating the Constraint
object via this
constructor. This is necessary to ensure that an SBML document is a
consistent structure. Nevertheless, the ability to supply the values
at the time of creation of a Constraint
is an important aid to
producing valid SBML. Knowledge of the intented SBML Level and
Version determine whether it is valid to assign a particular value to
an attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public Constraint cloneObject()
Constraint
.
cloneObject
 in class SBase
Constraint
.public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the Constraint.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke Constraint.delete()
themselves.
public java.lang.String getElementName()
Constraint
, is
always 'constraint'.
getElementName
 in class SBase
'constraint'.
public ASTNode getMath()
Constraint
Constraint
, as an ASTNode
.public XMLNode getMessage()
Constraint
Constraint
, as an XMLNode
.public java.lang.String getMessageString()
Constraint
Constraint
, as a string.public int getTypeCode()
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters &ldquoSBML_
&rdquo.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the getPackageName()
method on the object.
getTypeCode
 in class SBase
SBML_CONSTRAINT
(default).
Constraint.getElementName()
,
SBase.getPackageName()
public boolean hasRequiredElements()
true
if
all the required elements for this Constraint
object
have been set.
hasRequiredElements
 in class SBase
Constraint
object are:
public boolean isSetMath()
true
if a
mathematical formula is defined for this Constraint
.
true
if the 'math' subelement for this Constraint
is
set, false
otherwise.public boolean isSetMessage()
true
if a
message is defined for this Constraint
.
true
if the message of this Constraint
is set,
false
otherwise.public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
SIdRef
attributes on this element, including any
found in MathML.
In SBML, object identifiers are of a data type called SId
.
In SBML Level 3, an explicit data type called SIdRef
was
introduced for attribute values that refer to SId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to an identifier', but the effective
data type was the same as SIdRef
in Level 3. These and
other methods of libSBML refer to the type SIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all attributes and (if appropriate)
mathematical formulas, comparing the identifiers to the value of
oldid
. If any matches are found, the matching identifiers are replaced
with newid
. The method does not descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
UnitSIdRef
attributes on this element.
In SBML, unit definitions have identifiers of type UnitSId
. In
SBML Level 3, an explicit data type called UnitSIdRef
was
introduced for attribute values that refer to UnitSId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to a unit identifier', but the effective
data type was the same as UnitSIdRef
in Level 3. These and
other methods of libSBML refer to the type UnitSIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all unit identifier attribute values
(including, if appropriate, inside mathematical formulas), comparing the
unit identifiers to the value of oldid
. If any matches are found,
the matching identifiers are replaced with newid
. The method does
not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setMath(ASTNode math)
Constraint
to a copy of the
AST given as math
.
math
- an ASTNode
expression to be assigned as the 'math'
subelement of this Constraint
public int setMessage(XMLNode xhtml)
Constraint
.
The XMLNode
tree passed in xhtml
is copied.
xhtml
- an XML tree containing XHTML content.
public int unsetMessage()
Constraint
.