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 subelement, 'math', containing a MathML
formula defining the condition of the constraint. This formula will
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.
In SBML Level 2 and SBML Level 3 Version 1, the 'math'
subelement is required, and its formula must be a Boolean value. In
SBML Level 3 Version 2, these restrictions were relaxed:
the 'math' subelement is optional, and numeric values are allowed
in Boolean contexts (a '0' is interpreted as false
, and all other
values are interpreted as true
). If a Constraint
with no 'math'
is present in a Model
, no restriction on the Model
's behavior is
implied or enforced.
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 object. |
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)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
UnitSIdRef type attribute value with
another value. |
int |
setMath(ASTNode math)
Sets the mathematical expression of this
Constraint to a copy of the
AST given as math . |
int |
setMessage(java.lang.String message)
Sets the message of this
Constraint . |
int |
setMessage(java.lang.String message,
boolean addXHTMLMarkup)
Sets the message of this
Constraint . |
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, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getId, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getName, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getObjectVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetId, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetName, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setId, setIdAttribute, setMetaId, setModelHistory, setName, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
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 are invalid
or if this object is incompatible with the given level and version.
SBMLDocument
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
), 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.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 sbmlns
is inconsistent or incompatible
with this object.
SBMLDocument
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
), 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.public Constraint(Constraint orig) throws SBMLConstructorException
Constraint
.
orig
- the object to copy.SBMLConstructorException
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 Constraint cloneObject()
Constraint
object.
cloneObject
 in class SBase
Constraint
object.public XMLNode getMessage()
Constraint
Constraint
, as an XMLNode
.public java.lang.String getMessageString()
Constraint
Constraint
, as a string.public ASTNode getMath()
Constraint
Constraint
, as an ASTNode
, or null
if the math is not set.public boolean isSetMessage()
true
if a
message is defined for this Constraint
.
true
if the message of this Constraint
is set,
false
otherwise.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 int setMessage(XMLNode xhtml)
Constraint
.
The XMLNode
tree passed in xhtml
is copied.
xhtml
- an XML tree containing XHTML content.
public int setMessage(java.lang.String message, boolean addXHTMLMarkup)
Constraint
.
message
- an XML string that is to be used as the content of the
'message' subelement of this object.
addXHTMLMarkup
- a boolean indicating whether to wrap the contents
of the message
argument with XHTML paragraph (<p>
)
tags. This is appropriate when the string in message
does not already
containg the appropriate XHTML markup.
public int setMessage(java.lang.String message)
Constraint
.
message
- an XML string that is to be used as the content of the
'message' subelement of this object.
addXHTMLMarkup
- a boolean indicating whether to wrap the contents
of the message
argument with XHTML paragraph (<p>
)
tags. This is appropriate when the string in message
does not already
containg the appropriate XHTML markup.
public 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 unsetMessage()
Constraint
.
public void renameSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given SIdRef
type attribute value with another
value.
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 in MathML content, comparing the referenced
identifiers to the value of oldid
. If any matches are found, the
matching values are replaced with newid
. The method does not
descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.public void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given UnitSIdRef
type attribute value with
another value.
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
referenced unit identifiers to the value of oldid
. If any matches
are found, the matching values are replaced with newid
. The method
does not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.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 SBML_
.
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 java.lang.String getElementName()
Constraint
, is
always 'constraint'.
getElementName
 in class SBase
'constraint'.
public boolean hasRequiredElements()
true
if
all the required elements for this Constraint
object
have been set.
hasRequiredElements
 in class SBase
Constraint
object are: