public class UnitDefinition extends SBase
Units of measurement may be supplied in a number of contexts in an SBML
model. The SBML unit definition facility uses two classes of objects,
UnitDefinition
and Unit
. The approach to defining units in SBML is
compositional for example, meter second &ndash2 is
constructed by combining a Unit
object representing meter with
another Unit
object representing second &ndash2.
The combination is wrapped inside a UnitDefinition
, which provides for
assigning an identifier and optional name to the combination. The
identifier can then be referenced from elsewhere in a model. Thus, the
UnitDefinition
class is the container, and Unit
instances are placed
inside UnitDefinition
instances.
Two points are worth discussing in the context of SBML units. First,
unit declarations in SBML models are optional. The consequence of
this is that a model must be numerically self-consistent independently
of unit declarations, for the benefit of software tools that cannot
interpret or manipulate units. Unit
declarations in SBML are thus more
akin to a type of annotation they can indicate intentions, and can be
used by model readers for checking the consistency of the model,
labeling simulation output, etc., but any transformations of values
implied by different units must be incorporated explicitly into a
model.
Second, the vast majority of situations that require new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example is moles per litre per second. What distinguishes these sorts of unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML, the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed to simplify implementation of unit support for the most common cases in systems biology. The cost of this simplification is to require units with offsets to be handled explicitly by the modeler.
UnitDefinition
construct
UnitDefinition
has two attributes and one subelement. The two
attributes are 'id' and 'name', and the subelement is ListOfUnits
.
The required attribute 'id' and optional attribute 'name' are both strings. The 'id' attribute is used to give the defined unit a unique identifier by which other parts of an SBML model definition can refer to it. The 'name' attribute is intended to be used for giving the unit definition an optional human-readable name. Please see the next section for information about the values permitted for 'id'.
A UnitDefinition
may contain exactly one ListOfUnits
, and this list
may contain one or more Unit
definitions see the definitions of these
other object classes for more information about them. In SBML
Level 2 and SBML Level 3 Version 1, if the ListOfUnits
was present, it must have one or more Unit
definitions. In SBML
Level 3 Version 2, this restriction was relaxed, and
a ListOfUnits
was allowed to be empty. In either case, if a
UnitDefinition
had no child Unit
elements, the unit was considered
to be undefined.
The following example illustrates a complete unit definition (when written in XML) when all the pieces are combined together. This defines 'mmls' to be millimoles per litre per second.
<listOfUnitDefinitions> <unitDefinition id='mmls'> <listOfUnits> <unit kind='mole' scale='-3'/> <unit kind='litre' exponent='-1'/> <unit kind='second' exponent='-1'/> </listOfUnits> </unitDefinition> </listOfUnitDefinitions>
Unit
object identifiers
The attribute 'id' in UnitDefinition
cannot be given simply any value,
and the precise details of the values permitted differ slightly between
Levels of SBML:
UnitDefinition
must not contain a value from the
list of SBML's predefined base unit names (i.e., the strings gram
,
litre
, etc.). In SBML Level 3, this list consists of the
following:
ampere | farad | joule | lux | radian | volt |
avogadro | gram | katal | metre | second | watt |
becquerel | gray | kelvin | mole | siemens | weber |
candela | henry | kilogram | newton | sievert | |
coulomb | hertz | litre | ohm | steradian | |
dimensionless | item | lumen | pascal | tesla |
This list of predefined base units is nearly identical in SBML
Level 2 Version 4, the exception being that Level 2 does
not define avogadro.
SBML Level 2 Version 1 (and only
this Level+Version combination) provides an additional predefined unit
name, Celsius
, not available in Level 3. Finally, SBML
Level 1 Versions 2&ndash3 provide two more additional
predefined unit names, meter
and liter.
This is explained in
somewhat greater detail in the description of the Unit
class.
substance
, volume
, area
, length
, and
time.
Using one of these values for the attribute 'id' of a
UnitDefinition
has the effect of redefining the model-wide default units
for the corresponding quantities. The list of special unit names in
SBML Level 2 is given in the table below:
Identifier | Possible scalable units | Default units |
---|---|---|
substance | mole, item, gram, kilogram, dimensionless | mole |
volume | litre, cubic metre, dimensionless | litre |
area | square metre, dimensionless | square metre |
length | metre, dimensionless | metre |
time | second, dimensionless | second |
Also, SBML Level 2 imposes two limitations on redefining the
predefined unit substance
, volume
, area
, length
, and
time:
(1) The UnitDefinition
of a predefined SBML unit can only contain
a single Unit
object within it. (2) The value of the 'kind' attribute
in a Unit
instance must be drawn from one of the values in the second
column of the table above.
The special unit names substance
, volume
, area
, length
, and
time
are not defined by SBML Level 3, which uses a different
approach to setting model-wide inherited units.
The vast majority of modeling situations requiring new SBML unit definitions involve simple multiplicative combinations of base units and factors. An example of this might be moles per litre per second. What distinguishes these sorts of simpler unit definitions from more complex ones is that they may be expressed without the use of an additive offset from a zero point. The use of offsets complicates all unit definition systems, yet in the domain of SBML the real-life cases requiring offsets are few (and in fact, to the best of our knowledge, only involve temperature). Consequently, the SBML unit system has been consciously designed in a way that attempts to simplify implementation of unit support for the most common cases in systems biology.
As of SBML Level 2 Version 2, Unit
no longer has the
attribute called 'offset' introduced in SBML Level 2
Version 1. It turned out that the general case involving units
with offsets was incorrectly defined, and few (if any) developers even
attempted to support offset-based units in their software. In the
development of Level 2 Version 2, a consensus among SBML
developers emerged that a fully generalized unit scheme is so
confusing and complicated that it actually impedes interoperability.
SBML Level 2 Version 2, Version 3 and Version 4 acknowledge this
reality by reducing and simplifying the unit system, specifically by
removing the 'offset' attribute on Unit
and Celsius
as a pre-defined
unit.
The following guidelines suggest methods for handling units that do require the use of zero offsets for their definitions:
FunctionDefinition
object to define a function encapsulating this
relationship above and then using that in the rest of the model as
needed. Since Celsius is a commonly-used unit, software tools could
help users by providing users with the ability to express temperatures
in Celsius in the tools' interfaces, and making substitutions
automatically when writing out the SBML.
FunctionDefinition
to define a function
encapsulating the necessary mathematical relationship, then
substituting a call to this function wherever the original quantity
appeared in the model. For example, here is a possible definition for
converting Fahrenheit to Celsius degrees:
<functionDefinition id='Fahrenheit_to_kelvin'> <math xmlns='http://www.w3.org/1998/Math/MathML'> <lambda> <bvar><ci> temp_in_fahrenheit </ci></bvar> <apply> <divide/> <apply> <plus/> <ci> temp_in_fahrenheit </ci> <cn> 459.67 </cn> </apply> <cn> 1.8 </cn> </apply> </lambda> </math> </functionDefinition>
AssignmentRule
for each variable in Fahrenheit units.
The AssignmentRule
could compute the conversion from Fahrenheit to
(say) kelvin, assign its value to a variable (in Kelvin units), and
then that variable could be used elsewhere in the model.
Please consult the SBML specifications for more information about this and other issues involving units.
Constructor and Description |
---|
UnitDefinition(long level,
long version)
|
UnitDefinition(SBMLNamespaces sbmlns)
|
UnitDefinition(UnitDefinition orig)
Copy constructor creates a copy of this
UnitDefinition . |
Modifier and Type | Method and Description |
---|---|
int |
addUnit(Unit u)
Adds a copy of the given
Unit to this UnitDefinition . |
static boolean |
areEquivalent(UnitDefinition ud1,
UnitDefinition ud2)
Predicate returning
true if two
UnitDefinition objects are equivalent. |
static boolean |
areIdentical(UnitDefinition ud1,
UnitDefinition ud2)
Predicate returning
true if two
UnitDefinition objects are identical. |
UnitDefinition |
cloneObject()
Creates and returns a deep copy of this
UnitDefinition object. |
static UnitDefinition |
combine(UnitDefinition ud1,
UnitDefinition ud2)
Combines two
UnitDefinition objects into a single UnitDefinition . |
void |
connectToChild()   |
static UnitDefinition |
convertToSI(UnitDefinition ud)
Convert a given
UnitDefinition into a new UnitDefinition object
that uses SI units. |
Unit |
createUnit()
Creates a new and empty
Unit , adds it to this UnitDefinition 's list of
units, and returns it. |
void |
delete()
Explicitly deletes the underlying native object.
|
static UnitDefinition |
divide(UnitDefinition ud1,
UnitDefinition ud2)
Combines two
UnitDefinition objects into a single UnitDefinition as
a division. |
SBase |
getElementByMetaId(java.lang.String metaid)
Returns the first child element it can find with the given
metaid , or
null if no such object is found. |
SBase |
getElementBySId(java.lang.String id)
Returns the first child element found that has the given
id in the
model-wide SId namespace, or null if no such object is found. |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
UnitDefinition ,
is always 'unitDefinition'. |
java.lang.String |
getId()
Returns the value of the 'id' attribute of this
UnitDefinition . |
ListOfUnits |
getListOfUnits()
Returns the list of Units for this
UnitDefinition instance. |
java.lang.String |
getName()
Returns the value of the 'name' attribute of this
UnitDefinition object. |
long |
getNumUnits()
Returns the number of
Unit objects contained within this
UnitDefinition . |
int |
getTypeCode()
Returns the libSBML type code for this object instance.
|
Unit |
getUnit(long n)
Returns a specific
Unit instance belonging to this UnitDefinition . |
boolean |
hasRequiredAttributes()
Predicate returning
true if
all the required attributes for this UnitDefinition object
have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for this UnitDefinition object
have been set. |
boolean |
isSetId()
Predicate returning
true if this
UnitDefinition 's 'id' attribute is set. |
boolean |
isSetName()
Predicate returning
true if this
UnitDefinition 's 'name' attribute is set. |
boolean |
isVariantOfArea()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'area'. |
boolean |
isVariantOfArea(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'area'. |
boolean |
isVariantOfDimensionless()
Convenience function for testing if a given unit definition is a
variant of the unit
'dimensionless'. |
boolean |
isVariantOfDimensionless(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the unit
'dimensionless'. |
boolean |
isVariantOfLength()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'length'. |
boolean |
isVariantOfLength(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'length'. |
boolean |
isVariantOfMass()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'mass'. |
boolean |
isVariantOfMass(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'mass'. |
boolean |
isVariantOfSubstance()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'substance'. |
boolean |
isVariantOfSubstance(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'substance'. |
boolean |
isVariantOfSubstancePerTime()
Convenience function for testing if a given unit definition is a
variant of the predefined unit
'substance' divided by the predefined
unit 'time'. |
boolean |
isVariantOfSubstancePerTime(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit
'substance' divided by the predefined
unit 'time'. |
boolean |
isVariantOfTime()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'time'. |
boolean |
isVariantOfTime(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'time'. |
boolean |
isVariantOfVolume()
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'volume'. |
boolean |
isVariantOfVolume(boolean relaxed)
Convenience function for testing if a given unit definition is a
variant of the predefined unit identifier
'volume'. |
static java.lang.String |
printUnits(UnitDefinition ud)
Expresses the given definition in a plain-text form.
|
static java.lang.String |
printUnits(UnitDefinition ud,
boolean compact)
Expresses the given definition in a plain-text form.
|
Unit |
removeUnit(long n)
Removes the nth
Unit object from this UnitDefinition object and
returns a pointer to it. |
static void |
reorder(UnitDefinition ud)
|
int |
setId(java.lang.String sid)
Sets the value of the 'id' attribute of this
UnitDefinition . |
int |
setName(java.lang.String name)
Sets the value of the 'name' attribute of this
UnitDefinition . |
static void |
simplify(UnitDefinition ud)
Simplifies the
UnitDefinition such that any given kind of Unit object
occurs only once in the ListOfUnits . |
int |
unsetName()
Unsets the value of the 'name' attribute of this
UnitDefinition . |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageCoreVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, renameUnitSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setIdAttribute, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm, unsetUserData
public UnitDefinition(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this UnitDefinition
.
version
- a long integer, the SBML Version to assign to this
UnitDefinition
.
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 UnitDefinition(SBMLNamespaces sbmlns) throws SBMLConstructorException
UnitDefinition
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 UnitDefinition(UnitDefinition orig) throws SBMLConstructorException
UnitDefinition
.
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 UnitDefinition.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 UnitDefinition.delete()
themselves.
public UnitDefinition cloneObject()
UnitDefinition
object.
cloneObject
 in class SBase
UnitDefinition
object.public SBase getElementBySId(java.lang.String id)
id
in the
model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of the object to find.
id
.public SBase getElementByMetaId(java.lang.String metaid)
metaid
, or
null
if no such object is found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of the object to find.
metaid
.public java.lang.String getId()
UnitDefinition
.
getId
 in class SBase
UnitDefinition
.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public java.lang.String getName()
UnitDefinition
object.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
getName
 in class SBase
SBase.getIdAttribute()
,
UnitDefinition.isSetName()
,
UnitDefinition.setName(String sid)
,
UnitDefinition.unsetName()
public boolean isSetId()
isSetId
 in class SBase
true
if the 'id' attribute of this SBML object is
set, false
otherwise.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.unsetIdAttribute()
,
SBase.isSetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public boolean isSetName()
true
if this
UnitDefinition
's 'name' attribute is set.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
isSetName
 in class SBase
true
if the 'name' attribute of this SBML object is
set, false
otherwise.
UnitDefinition.getName()
,
UnitDefinition.setName(String sid)
,
UnitDefinition.unsetName()
public int setId(java.lang.String sid)
UnitDefinition
.
The string sid
is copied.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
setId
 in class SBase
sid
- the string to use as the identifier of this object.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public int setName(java.lang.String name)
public int unsetName()
UnitDefinition
.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
unsetName
 in class SBase
UnitDefinition.getName()
,
UnitDefinition.setName(String sid)
,
UnitDefinition.isSetName()
public boolean isVariantOfArea(boolean relaxed)
'area'.
true
if this UnitDefinition
is a variant of the predefined
unit area
, meaning square metres with only arbitrary variations
in scale or multiplier values false
otherwise.public boolean isVariantOfArea()
'area'.
true
if this UnitDefinition
is a variant of the predefined
unit area
, meaning square metres with only arbitrary variations
in scale or multiplier values false
otherwise.public boolean isVariantOfLength(boolean relaxed)
'length'.
true
if this UnitDefinition
is a variant of the predefined
unit length
, meaning metres with only arbitrary variations in scale
or multiplier values false
otherwise.public boolean isVariantOfLength()
'length'.
true
if this UnitDefinition
is a variant of the predefined
unit length
, meaning metres with only arbitrary variations in scale
or multiplier values false
otherwise.public boolean isVariantOfSubstance(boolean relaxed)
'substance'.
true
if this UnitDefinition
is a variant of the predefined
unit substance
, meaning moles or items (and grams or kilograms from
SBML Level 2 Version 2 onwards) with only arbitrary variations
in scale or multiplier values false
otherwise.public boolean isVariantOfSubstance()
'substance'.
true
if this UnitDefinition
is a variant of the predefined
unit substance
, meaning moles or items (and grams or kilograms from
SBML Level 2 Version 2 onwards) with only arbitrary variations
in scale or multiplier values false
otherwise.public boolean isVariantOfTime(boolean relaxed)
'time'.
true
if this UnitDefinition
is a variant of the predefined
unit time
, meaning seconds with only arbitrary variations in scale or
multiplier values false
otherwise.public boolean isVariantOfTime()
'time'.
true
if this UnitDefinition
is a variant of the predefined
unit time
, meaning seconds with only arbitrary variations in scale or
multiplier values false
otherwise.public boolean isVariantOfVolume(boolean relaxed)
'volume'.
true
if this UnitDefinition
is a variant of the predefined
unit volume
, meaning litre or cubic metre with only arbitrary
variations in scale or multiplier values false
otherwise.public boolean isVariantOfVolume()
'volume'.
true
if this UnitDefinition
is a variant of the predefined
unit volume
, meaning litre or cubic metre with only arbitrary
variations in scale or multiplier values false
otherwise.public boolean isVariantOfDimensionless(boolean relaxed)
'dimensionless'.
true
if this UnitDefinition
is a variant of
dimensionless
, meaning dimensionless with only arbitrary variations in
scale or multiplier values false
otherwise.public boolean isVariantOfDimensionless()
'dimensionless'.
true
if this UnitDefinition
is a variant of
dimensionless
, meaning dimensionless with only arbitrary variations in
scale or multiplier values false
otherwise.public boolean isVariantOfMass(boolean relaxed)
'mass'.
true
if this UnitDefinition
is a variant of mass units,
meaning gram or kilogram with only arbitrary variations in scale or
multiplier values false
otherwise.public boolean isVariantOfMass()
'mass'.
true
if this UnitDefinition
is a variant of mass units,
meaning gram or kilogram with only arbitrary variations in scale or
multiplier values false
otherwise.public boolean isVariantOfSubstancePerTime(boolean relaxed)
'substance'
divided by the predefined
unit 'time'.
true
if this UnitDefinition
is a variant of the predefined
unit substance
per predefined unit time
, meaning it contains two
units one of which is a variant of substance and the other is a
variant of time which an exponent of -1 false
otherwise.public boolean isVariantOfSubstancePerTime()
'substance'
divided by the predefined
unit 'time'.
true
if this UnitDefinition
is a variant of the predefined
unit substance
per predefined unit time
, meaning it contains two
units one of which is a variant of substance and the other is a
variant of time which an exponent of -1 false
otherwise.public int addUnit(Unit u)
Unit
to this UnitDefinition
.
u
- the Unit
instance to add to this UnitDefinition
.
LIBSBML_OPERATION_SUCCESS
LIBSBML_LEVEL_MISMATCH
LIBSBML_VERSION_MISMATCH
LIBSBML_INVALID_OBJECT
LIBSBML_OPERATION_FAILED
UnitDefinition.createUnit()
create
)
for alternatives that do not lead to these issues.
public Unit createUnit()
Unit
, adds it to this UnitDefinition
's list of
units, and returns it.
Unit
instance.
UnitDefinition.addUnit(Unit u)
Unit
is a required attribute for a valid Unit
definition. The
createUnit() method does not assign a valid kind to the constructed
unit (instead, it sets the 'kind' to UNIT_KIND_INVALID
).
Callers are cautioned to set the newly-constructed Unit
's kind using
Unit.setKind(int)
soon after calling this method.
public ListOfUnits getListOfUnits()
UnitDefinition
instance.ListOfUnits
value for this UnitDefinition
.public Unit getUnit(long n)
Unit
instance belonging to this UnitDefinition
.
n
- an integer, the index of the Unit
to be returned.
Unit
of this UnitDefinition
.
UnitDefinition.getNumUnits()
public long getNumUnits()
Unit
objects contained within this
UnitDefinition
.
UnitDefinition
.public Unit removeUnit(long n)
Unit
object from this UnitDefinition
object and
returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
public void connectToChild()
connectToChild
 in class SBase
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
method on the object.
SBase.getPackageName()
getTypeCode
 in class SBase
SBML_UNIT_DEFINITION
(default).
SBase.getPackageName()
,
UnitDefinition.getElementName()
public java.lang.String getElementName()
UnitDefinition
,
is always 'unitDefinition'.
getElementName
 in class SBase
'unitDefinition'.
public static void simplify(UnitDefinition ud)
UnitDefinition
such that any given kind of Unit
object
occurs only once in the ListOfUnits
.
For example, the following definition,
<unitDefinition> <listOfUnits> <unit kind='metre' exponent='1'/> <unit kind='metre' exponent='2'/> </listOfUnits> <unitDefinition>will be simplified to
<unitDefinition> <listOfUnits> <unit kind='metre' exponent='3'/> </listOfUnits> <unitDefinition>
ud
- the UnitDefinition
object to be simplified.
public static void reorder(UnitDefinition ud)
ud
- the UnitDefinition
object whose units are to be reordered.
public static UnitDefinition convertToSI(UnitDefinition ud)
UnitDefinition
into a new UnitDefinition
object
that uses SI units.
ud
- the UnitDefinition
object to convert to SI.
UnitDefinition
object representing the results of the
conversion.
public static boolean areIdentical(UnitDefinition ud1, UnitDefinition ud2)
true
if two
UnitDefinition
objects are identical.
For the purposes of performing this comparison, two UnitDefinition
objects are considered identical when they contain identical lists of
Unit
objects. Pairs of Unit
objects in the lists are in turn
considered identical if they satisfy the predicate
Unit.areIdentical(Unit, Unit)
.
The predicate compares every attribute of the
Unit
objects.
ud1
- the first UnitDefinition
object to compare.ud2
- the second UnitDefinition
object to compare.
true
if all the Unit
objects in ud1
are identical to the
Unit
objects of ud2
, false
otherwise.
UnitDefinition.areEquivalent(UnitDefinition ud1, UnitDefinition ud2)
,
Unit.areIdentical(Unit unit1, Unit unit2)
public static boolean areEquivalent(UnitDefinition ud1, UnitDefinition ud2)
true
if two
UnitDefinition
objects are equivalent.
For the purposes of performing this comparison, two UnitDefinition
objects are considered equivalent when they contain equivalent
list of Unit
objects. Unit
objects are in turn considered equivalent
if they satisfy the predicate
Unit.areEquivalent(Unit, Unit)
.
The predicate tests a subset of the objects's attributes.
ud1
- the first UnitDefinition
object to compare.
ud2
- the second UnitDefinition
object to compare.
true
if all the Unit
objects in ud1
are equivalent
to the Unit
objects in ud2
, false
otherwise.
UnitDefinition.areIdentical(UnitDefinition ud1, UnitDefinition ud2)
,
Unit.areEquivalent(Unit unit1, Unit unit2)
public static UnitDefinition combine(UnitDefinition ud1, UnitDefinition ud2)
UnitDefinition
objects into a single UnitDefinition
.
This takes UnitDefinition
objects ud1
and ud2
, and creates a
UnitDefinition
object that expresses the product of the units of
ud1
and ud2
.
ud1
- the first UnitDefinition
object.ud2
- the second UnitDefinition
object.
UnitDefinition
which represents the product of the
units of the two argument UnitDefinitions.
public static UnitDefinition divide(UnitDefinition ud1, UnitDefinition ud2)
UnitDefinition
objects into a single UnitDefinition
as
a division.
This takes UnitDefinition
objects ud1
and ud2
, and creates a
UnitDefinition
object that expresses the division of the units of
ud1
and ud2
.
ud1
- the first UnitDefinition
object.ud2
- the second UnitDefinition
object.
UnitDefinition
which represents the division of the
units of the two argument UnitDefinitions.
public static java.lang.String printUnits(UnitDefinition ud, boolean compact)
For example,
UnitDefinition.printUnits(UnitDefinition)
applied to
<unitDefinition> <listOfUnits> <unit kind='metre' exponent='1'/> <unit kind='second' exponent='-2'/> </listOfUnits> <unitDefinition>will return the string
'metre (exponent = 1, multiplier = 1,
scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'
or, if the optional parameter compact
is given the value true
,
the string '(1 metre)^1 (1 second)^-2'
. This method may
be useful for printing unit information to human users, or in
debugging software, or other situations.
ud
- the UnitDefinition
object.compact
- boolean indicating whether the compact form
should be used (defaults to false).
UnitDefinition
object ud
.
public static java.lang.String printUnits(UnitDefinition ud)
For example,
UnitDefinition.printUnits(UnitDefinition)
applied to
<unitDefinition> <listOfUnits> <unit kind='metre' exponent='1'/> <unit kind='second' exponent='-2'/> </listOfUnits> <unitDefinition>will return the string
'metre (exponent = 1, multiplier = 1,
scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'
or, if the optional parameter compact
is given the value true
,
the string '(1 metre)^1 (1 second)^-2'
. This method may
be useful for printing unit information to human users, or in
debugging software, or other situations.
ud
- the UnitDefinition
object.compact
- boolean indicating whether the compact form
should be used (defaults to false).
UnitDefinition
object ud
.
public boolean hasRequiredAttributes()
true
if
all the required attributes for this UnitDefinition
object
have been set.
The required attributes for a UnitDefinition
object are:
hasRequiredAttributes
 in class SBase
true
if the required attributes have been set, false
otherwise.public boolean hasRequiredElements()
true
if
all the required elements for this UnitDefinition
object
have been set.
hasRequiredElements
 in class SBase
Constraint
object are: