public class ASTNode extends Object
This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.
Abstract Syntax Trees (ASTs) are a simple kind of data structure used in
libSBML for storing mathematical expressions. The ASTNode
is the
cornerstone of libSBML's AST representation. An AST 'node' represents the
most basic, indivisible part of a mathematical formula and come in many
types. For instance, there are node types to represent numbers (with
subtypes to distinguish integer, real, and rational numbers), names
(e.g., constants or variables), simple mathematical operators, logical
or relational operators and functions. LibSBML ASTs provide a canonical,
in-memory representation for all mathematical formulas regardless of
their original format (which might be MathML or might be text strings).
An AST node in libSBML is a recursive structure containing a pointer
to the node's value (which might be, for example, a number or a symbol)
and a list of children nodes. Each ASTNode
node may have none, one,
two, or more children depending on its type. The following diagram
illustrates an example of how the mathematical expression '1 +
2'
is represented as an AST with one plus node having two
integer children nodes for the numbers 1
and
2
. The figure also shows the corresponding MathML
representation:
Infix | AST | MathML |
---|---|---|
1 + 2
|
<math xmlns='http://www.w3.org/1998/Math/MathML'>   <apply>     <plus/>     <cn type='integer'> 1 </cn>     <cn type='integer'> 2 </cn>   </apply> </math>
|
The following are other noteworthy points about the AST representation in libSBML:
double
data type. This is done
so that when an SBML model is read in and then written out again, the
amount of change introduced by libSBML to the SBML during the round-trip
activity is minimized.
ASTNode.getNumerator()
and ASTNode.getDenominator()
.
ASTNode
are other ASTNode
objects. The list of
children is empty for nodes that are leaf elements, such as numbers.
For nodes that are actually roots of expression subtrees, the list of
children points to the parsed objects that make up the rest of the
expression.
Every ASTNode
has an associated type code to indicate,
for example, whether it holds a number or stands for an arithmetic
operator.
The type is recorded as a value drawn from a
set of static integer constants defined in the class libsbmlConstants
. Their names begin with the characters AST_.
The list of possible types is quite long, because it covers all the mathematical functions that are permitted in SBML. The values are shown in the following table:
The types have the following meanings:
'+'
), then the
node's type will be AST_PLUS
, AST_MINUS
, AST_TIMES
, AST_DIVIDE
,
or AST_POWER
, as appropriate.
AST_FUNCTION_
X, AST_LOGICAL_
X, or
AST_RELATIONAL_
X,
as appropriate. (Examples: AST_FUNCTION_LOG
, AST_RELATIONAL_LEQ.
)
AST_FUNCTION
(because it holds the name of the function).
AST_LAMBDA.
'ExponentialE'
, 'Pi'
,
'True'
or 'False'
), then the node's type will be AST_CONSTANT_E
,
AST_CONSTANT_PI
, AST_CONSTANT_TRUE
, or AST_CONSTANT_FALSE.
time
,
the value of the node will be AST_NAME_TIME.
(Note, however, that the
MathML csymbol delay
is translated into a node of type
AST_FUNCTION_DELAY.
The difference is due to the fact that time
is a
single variable, whereas delay
is actually a function taking
arguments.)
avogadro
,
the value of the node will be AST_NAME_AVOGADRO.
AST_INTEGER
, AST_REAL
, AST_REAL_E
, or AST_RATIONAL
,
as appropriate.
The text-string form of mathematical formulas produced by libsbml.formulaToString()
and
read by libsbml.parseFormula(String formula)
and
libsbml.parseL3Formula(String formula)
are in a simple C-inspired infix notation. A
formula in this text-string form can be handed to a program that
understands SBML mathematical expressions, or used as part
of a translation system. The libSBML distribution comes with an example
program in the 'examples'
subdirectory called translateMath
that
implements an interactive command-line demonstration of translating
infix formulas into MathML and vice-versa.
The formula strings may contain operators, function calls, symbols, and white space characters. The allowable white space characters are tab and space. The following are illustrative examples of formulas expressed in the syntax:
0.10 * k4^2
(vm * s1)/(km + s1)
The following table shows the precedence rules in this syntax. In the
Class column, operand implies the construct is an operand,
prefix implies the operation is applied to the following arguments,
unary implies there is one argument, and binary implies there are
two arguments. The values in the Precedence column show how the order
of different types of operation are determined. For example, the
expression a * b + c is evaluated as (a * b) + c
because the *
operator has higher precedence. The
Associates column shows how the order of similar precedence operations
is determined for example, a - b + c is evaluated as (a -
b) + c because the +
and -
operators are
left-associative. The precedence and associativity rules are taken from
the C programming language, except for the symbol ^
, which
is used in C for a different purpose. (Exponentiation can be invoked
using either ^
or the function power.
)
Token | Operation | Class | Precedence | Associates |
---|---|---|---|---|
name | symbol reference | operand | 6 | n/a |
( expression) | expression grouping | operand | 6 | n/a |
f( ...) | function call | prefix | 6 | left |
- | negation | unary | 5 | right |
^ | power | binary | 4 | left |
* | multiplication | binary | 3 | left |
/ | divison | binary | 3 | left |
+ | addition | binary | 2 | left |
- | subtraction | binary | 2 | left |
, | argument delimiter | binary | 1 | left |
A program parsing a formula in an SBML model should assume that names
appearing in the formula are the identifiers of Species
, Parameter
,
Compartment
, FunctionDefinition
, Reaction
(in SBML Levels 2
and 3), or SpeciesReference
(in SBML Level 3 only) objects
defined in a model. When a function call is involved, the syntax
consists of a function identifier, followed by optional white space,
followed by an opening parenthesis, followed by a sequence of zero or
more arguments separated by commas (with each comma optionally preceded
and/or followed by zero or more white space characters), followed by a
closing parenthesis. There is an almost one-to-one mapping between the
list of predefined functions available, and those defined in MathML.
All of the MathML functions are recognized this set is larger than the
functions defined in SBML Level 1. In the subset of functions that
overlap between MathML and SBML Level 1, there exist a few
differences. The following table summarizes the differences between the
predefined functions in SBML Level 1 and the MathML equivalents in
SBML Levels 2 and  3:
Text string formula functions | MathML equivalents in SBML Levels 2 and 3 |
---|---|
acos | arccos |
asin | arcsin |
atan | arctan |
ceil | ceiling |
log | ln |
log10(x) | log(10, x) |
pow(x, y) | power(x, y) |
sqr(x) | power(x, 2) |
sqrt(x) | root(2, x) |
libsbml.parseL3Formula(String formula)
Constructor and Description |
---|
ASTNode()
Creates and returns a new
ASTNode . |
ASTNode(ASTNode orig)
Copy constructor creates a deep copy of the given
ASTNode . |
ASTNode(int type)
Creates and returns a new
ASTNode . |
Modifier and Type | Method and Description |
---|---|
int |
addChild(ASTNode child)
Adds the given node as a child of this
ASTNode . |
int |
addSemanticsAnnotation(XMLNode sAnnotation)
|
boolean |
canonicalize()
|
ASTNode |
deepCopy()
Creates a recursive copy of this node and all its children.
|
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
equals(Object sb)
Equality comparison method for ASTNode.
|
int |
freeName()
Frees the name of this
ASTNode and sets it to null. |
char |
getCharacter()
Get the value of this node as a single character.
|
ASTNode |
getChild(long n)
Get a child of this node according to its index number.
|
String |
getClassName()
Get the class of this
ASTNode . |
XMLAttributes |
getDefinitionURL()
Gets the MathML
definitionURL attribute value. |
int |
getDenominator()
Get the value of the denominator of this node.
|
int |
getExponent()
Get the exponent value of this
ASTNode . |
String |
getId()
Get the id of this
ASTNode . |
int |
getInteger()
Get the value of this node as an integer.
|
ASTNode |
getLeftChild()
Get the left child of this node.
|
ASTNodeList |
getListOfNodes()   |
double |
getMantissa()
Get the mantissa value of this node.
|
String |
getName()
Get the value of this node as a string.
|
long |
getNumChildren()
Get the number of children that this node has.
|
int |
getNumerator()
Get the value of the numerator of this node.
|
long |
getNumSemanticsAnnotations()
Get the number of semantic annotation elements inside this node.
|
String |
getOperatorName()
Get the value of this operator node as a string.
|
SBase |
getParentSBMLObject()
Returns the parent SBML object.
|
int |
getPrecedence()
Get the precedence of this node in the infix math syntax of SBML
Level 1.
|
double |
getReal()
Get the real-numbered value of this node.
|
ASTNode |
getRightChild()
Get the right child of this node.
|
XMLNode |
getSemanticsAnnotation(long n)
Get the nth semantic annotation of this node.
|
String |
getStyle()
Get the style of this
ASTNode . |
int |
getType()
Get the type of this
ASTNode . |
String |
getUnits()
Get the units of this
ASTNode . |
boolean |
hasCorrectNumberArguments()
Predicate returning
true or false depending on whether this
ASTNode has the correct number of children for it's type. |
int |
hashCode()
Returns a hashcode for this ASTNode object.
|
boolean |
hasUnits()
Predicate returning
true (non-zero) if this node or any of its
children nodes have the attribute sbml:units . |
int |
insertChild(long n,
ASTNode newChild)
|
boolean |
isAvogadro()
Predicate returning
true (non-zero) if this node is the special
symbol avogadro. The predicate returns false (zero) otherwise. |
boolean |
isBoolean()
Predicate returning
true (non-zero) if this node has a boolean type
(a logical operator, a relational operator, or the constants true
or false ). |
boolean |
isConstant()
Predicate returning
true (non-zero) if this node represents a MathML
constant (e.g., true , Pi ). |
boolean |
isFunction()
Predicate returning
true (non-zero) if this node represents a
MathML function (e.g., abs() ), or an SBML Level 1
function, or a user-defined function. |
boolean |
isInfinity()
Predicate returning
true (non-zero) if this node represents
the special IEEE 754 value infinity, false (zero) otherwise. |
boolean |
isInteger()
Predicate returning
true (non-zero) if this node contains an
integer value, false (zero) otherwise. |
boolean |
isLambda()
Predicate returning
true (non-zero) if this node is a MathML
<lambda> , false (zero) otherwise. |
boolean |
isLog10()
Predicate returning
true (non-zero) if this node represents a
log10 function, false (zero) otherwise. |
boolean |
isLogical()
Predicate returning
true (non-zero) if this node is a MathML
logical operator (i.e., and , or , not , xor ). |
boolean |
isName()
Predicate returning
true (non-zero) if this node is a user-defined
variable name in SBML L1, L2 (MathML), or the special symbols delay
or time. The predicate returns false (zero) otherwise. |
boolean |
isNaN()
Predicate returning
true (non-zero) if this node represents the
special IEEE 754 value 'not a number' (NaN), false (zero)
otherwise. |
boolean |
isNegInfinity()
Predicate returning
true (non-zero) if this node represents the
special IEEE 754 value 'negative infinity', false (zero) otherwise. |
boolean |
isNumber()
Predicate returning
true (non-zero) if this node contains a number,
false (zero) otherwise. |
boolean |
isOperator()
Predicate returning
true (non-zero) if this node is a mathematical
operator, meaning, + , - , * ,
/ or ^ (power). |
boolean |
isPiecewise()
Predicate returning
true (non-zero) if this node is the MathML
<piecewise> construct, false (zero) otherwise. |
boolean |
isRational()
Predicate returning
true (non-zero) if this node represents a rational
number, false (zero) otherwise. |
boolean |
isReal()
Predicate returning
true (non-zero) if this node can represent a
real number, false (zero) otherwise. |
boolean |
isRelational()
Predicate returning
true (non-zero) if this node is a MathML
relational operator, meaning == , >= ,
> , < , and != . |
boolean |
isSetClass()
Predicate returning
true (non-zero) if this node has the mathml attribute
class . |
boolean |
isSetId()
Predicate returning
true (non-zero) if this node has the mathml attribute
id . |
boolean |
isSetStyle()
Predicate returning
true (non-zero) if this node has the mathml attribute
style . |
boolean |
isSetUnits()
Predicate returning
true (non-zero) if this node has the attribute
sbml:units . |
boolean |
isSqrt()
Predicate returning
true (non-zero) if this node represents a
square root function, false (zero) otherwise. |
boolean |
isUMinus()
Predicate returning
true (non-zero) if this node is a unary minus
operator, false (zero) otherwise. |
boolean |
isUnknown()
Predicate returning
true (non-zero) if this node has an unknown type. |
boolean |
isUPlus()
Predicate returning
true (non-zero) if this node is a unary plus
operator, false (zero) otherwise. |
boolean |
isWellFormedASTNode()
|
int |
prependChild(ASTNode child)
Adds the given node as a child of this
ASTNode . |
void |
reduceToBinary()
Reduces this
ASTNode to a binary tree. |
int |
removeChild(long n)
Removes the nth child of this
ASTNode object. |
void |
renameSIdRefs(String oldid,
String newid)
Renames all the SIdRef attributes on this node and any child node
|
void |
renameUnitSIdRefs(String oldid,
String newid)
Renames all the UnitSIdRef attributes on this node and any child node.
|
void |
replaceArgument(String bvar,
ASTNode arg)
Replaces occurences of a given name within this
ASTNode with the
name/value/formula represented by arg . |
int |
replaceChild(long n,
ASTNode newChild)
|
boolean |
returnsBoolean()
Predicate returning
true (non-zero) if this node returns a boolean type
or false (zero) otherwise. |
boolean |
returnsBoolean(Model model)
Predicate returning
true (non-zero) if this node returns a boolean type
or false (zero) otherwise. |
int |
setCharacter(char value)
Sets the value of this
ASTNode to the given character. |
int |
setClassName(String className)
Sets the mathml class of this
ASTNode to className. |
int |
setId(String id)
Sets the mathml id of this
ASTNode to id. |
int |
setName(String name)
Sets the value of this
ASTNode to the given name. |
int |
setStyle(String style)
Sets the mathml style of this
ASTNode to style. |
int |
setType(int type)
Sets the type of this
ASTNode to the given type code. |
int |
setUnits(String units)
Sets the units of this
ASTNode to units. |
int |
setValue(double value)
|
int |
setValue(double mantissa,
int exponent)
Sets the value of this
ASTNode to the given real (double ) in two
parts: the mantissa and the exponent. |
int |
setValue(int value)
|
int |
setValue(int numerator,
int denominator)
Sets the value of this
ASTNode to the given rational in two parts: the
numerator and denominator. |
int |
swapChildren(ASTNode that)
|
int |
unsetClass()
Unsets the mathml class of this
ASTNode . |
int |
unsetId()
Unsets the mathml id of this
ASTNode . |
int |
unsetStyle()
Unsets the mathml style of this
ASTNode . |
int |
unsetUnits()
Unsets the units of this
ASTNode . |
public ASTNode()
ASTNode
.
Unless the argument type
is given, the returned node will by
default have a type of AST_UNKNOWN
. If the type isn't supplied when caling this
constructor, the caller should set the node type to something else as
soon as possible using
ASTNode.setType(int)
.
type
- an optional
type
code indicating the type of node to create.
public ASTNode(ASTNode orig)
ASTNode
.
orig
- the ASTNode
to be copied.public ASTNode(int type)
ASTNode
.
Unless the argument type
is given, the returned node will by
default have a type of AST_UNKNOWN
. If the type isn't supplied when caling this
constructor, the caller should set the node type to something else as
soon as possible using
ASTNode.setType(int)
.
type
- an optional
type
code indicating the type of node to create.
public int addChild(ASTNode child)
ASTNode
. Child nodes are added
in-order, from left to right.
child
- the ASTNode
instance to add
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
,
ASTNode.isWellFormedASTNode()
ASTNode
may change the structure of the
mathematical formula being represented by the tree structure, and may
render the representation invalid. Callers need to be careful to use
this method in the context of other operations to create complete and
correct formulas. The method
ASTNode.isWellFormedASTNode()
may also be useful for checking the results of node modifications.
public int addSemanticsAnnotation(XMLNode sAnnotation)
XMLNode
as a semantic annotation of this ASTNode
.
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
sAnnotation
- the annotation to add.
public boolean canonicalize()
ASTNode
to a canonical form and returns true
if
successful, false
otherwise.
The rules determining the canonical form conversion are as follows:
AST_NAME
and the node name matches 'ExponentialE'
, 'Pi'
, 'True'
or
'False'
the node type is converted to the corresponding
AST_CONSTANT_
X type.
AST_FUNCTION
and the node name matches an SBML (MathML) function name, logical operator name, or
relational operator name, the node is converted to the corresponding
AST_FUNCTION_
X or
AST_LOGICAL_
X type.
SBML Level 1 function names are searched first thus, for
example, canonicalizing log
will result in a node type of AST_FUNCTION_LN
. (See the SBML
Level 1 Version 2 Specification, Appendix C.)
Sometimes, canonicalization of a node results in a structural
conversion of the node as a result of adding a child. For example, a
node with the SBML Level 1 function name sqr
and a single
child node (the argument) will be transformed to a node of type
AST_FUNCTION_POWER
with
two children. The first child will remain unchanged, but the second
child will be an ASTNode
of type AST_INTEGER
and a value of 2. The function names that result
in structural changes are: log10
, sqr
, and sqrt.
public ASTNode deepCopy()
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 ASTNode.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 ASTNode.delete()
themselves.
public boolean equals(Object sb)
Because the Java methods for libSBML are actually wrappers around code
implemented in C++ and C, certain operations will not behave as
expected. Equality comparison is one such case. An instance of a
libSBML object class is actually a proxy object
wrapping the real underlying C/C++ object. The normal ==
equality operator in Java will only compare the Java proxy objects,
not the underlying native object. The result is almost never what you
want in practical situations. Unfortunately, Java does not provide a
way to override ==
.
The alternative that must be followed is to use the
equals()
method. The equals
method on this
class overrides the default java.lang.Object one, and performs an
intelligent comparison of instances of objects of this class. The
result is an assessment of whether two libSBML Java objects are truly
the same underlying native-code objects.
The use of this method in practice is the same as the use of any other
Java equals
method. For example,
a.equals(
b)
returns
true
if a and b are references to the
same underlying object.
public int freeName()
ASTNode
and sets it to null.
This operation is only applicable to ASTNode
objects corresponding to
operators, numbers, or AST_UNKNOWN
. This method has no effect on other types of
nodes.
public char getCharacter()
ASTNode.getType()
returns
AST_PLUS
,
AST_MINUS
,
AST_TIMES
,
AST_DIVIDE
or
AST_POWER
.
ASTNode
as a single characterpublic ASTNode getChild(long n)
n
- the index of the child to get
ASTNode
or null
if this node has no nth
child (n >
ASTNode.getNumChildren()
- 1
).public String getClassName()
ASTNode
.
ASTNode
.public XMLAttributes getDefinitionURL()
definitionURL
attribute value.
definitionURL
attribute, in the form of
a libSBML XMLAttributes
object.public int getDenominator()
ASTNode.getType()
== AST_RATIONAL
.
ASTNode
.public int getExponent()
ASTNode
. This function should be
called only when
ASTNode.getType()
returns AST_REAL_E
or AST_REAL
.
ASTNode
.public String getId()
ASTNode
.
ASTNode
.public int getInteger()
ASTNode.getType()
== AST_INTEGER
.
ASTNode
as a (long
) integer.public ASTNode getLeftChild()
ASTNode
. This is equivalent to calling
ASTNode.getChild(long)
with an argument of 0.
public ASTNodeList getListOfNodes()
public double getMantissa()
ASTNode.getType()
returns AST_REAL_E
or AST_REAL
.
If ASTNode.getType()
returns AST_REAL
,
this method is identical to
ASTNode.getReal()
.
ASTNode
.public String getName()
ASTNode.isOperator()
returns false
, and (2) are not numbers, i.e.,
ASTNode.isNumber()
returns false.
ASTNode
as a string.public long getNumChildren()
ASTNode
, or 0 is this node has
no children.public int getNumerator()
ASTNode.getType()
== AST_RATIONAL
.
ASTNode
.public long getNumSemanticsAnnotations()
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
ASTNode
.
ASTNode.addSemanticsAnnotation(XMLNode sAnnotation)
public String getOperatorName()
ASTNode.isOperator()
returns true.
ASTNode
as a string (or null if not an operator).public SBase getParentSBMLObject()
ASTNode
.public int getPrecedence()
ASTNode
.
ASTNode
public double getReal()
ASTNode.isReal()
== true
.
This function performs the necessary arithmetic if the node type is
AST_REAL_E
(mantissa *
10 exponent) or AST_RATIONAL
(numerator / denominator).
ASTNode
as a real (double).public ASTNode getRightChild()
ASTNode
, or null
if this node has no
right child. If
ASTNode.getNumChildren()
> 1
, then this is equivalent to:
getChild( getNumChildren() - 1 )
public XMLNode getSemanticsAnnotation(long n)
The <semantics>
element is a MathML 2.0 construct
that can be used to associate additional information with a MathML
construct. The construct can be used to decorate a MathML expressions with
a sequence of one or more <annotation>
or
<annotation-xml>
elements. Each such element contains a
pair of items the first is a symbol that acts as an attribute or key, and
the second is the value associated with the attribute or key. Please refer
to the MathML 2.0 documentation, particularly the Section
5.2, Semantic Annotations for more information about these constructs.
ASTNode
, or null
if this node has
no nth annotation (n >
ASTNode.getNumChildren()
- 1
).
ASTNode.addSemanticsAnnotation(XMLNode sAnnotation)
public String getStyle()
ASTNode
.
ASTNode
.public int getType()
ASTNode
. The value returned is one of the
enumeration values such as AST_LAMBDA
, AST_PLUS
,
etc.
ASTNode
.public String getUnits()
ASTNode
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model
. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns='http://www.w3.org/1998/Math/MathML' xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> <cn type='integer' sbml:units='second'> 10 </cn> </math>
ASTNode
.
libsbml.parseL3Formula(String formula)
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.
public boolean hasCorrectNumberArguments()
true
or false
depending on whether this
ASTNode
has the correct number of children for it's type.
For example, an ASTNode
with type AST_PLUS
expects 2 child nodes.
true
if this ASTNode
is has appropriate number of children
for it's type, false
otherwise.
ASTNode.isWellFormedASTNode()
public int hashCode()
public boolean hasUnits()
true
(non-zero) if this node or any of its
children nodes have the attribute sbml:units
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model
. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns='http://www.w3.org/1998/Math/MathML' xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> <cn type='integer' sbml:units='second'> 10 </cn> </math>
true
if this ASTNode
or its children has units associated
with it, false
otherwise.
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.public int insertChild(long n, ASTNode newChild)
n
- long the index of the ASTNode
being addednewChild
- ASTNode
to insert as the nth child
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
may change the structure of the
mathematical formula being represented by the tree structure, and may
render the representation invalid.
public boolean isAvogadro()
true
(non-zero) if this node is the special
symbol avogadro.
The predicate returns false
(zero) otherwise.
true
if this ASTNode
is the special symbol avogadro.
libsbml.parseL3Formula(String formula)
public boolean isBoolean()
true
(non-zero) if this node has a boolean type
(a logical operator, a relational operator, or the constants true
or false
).
ASTNode
is a boolean, false otherwise.public boolean isConstant()
true
(non-zero) if this node represents a MathML
constant (e.g., true
, Pi
).
true
if this ASTNode
is a MathML constant, false
otherwise.
true
for AST_NAME_AVOGADRO
in SBML Level 3.public boolean isFunction()
true
(non-zero) if this node represents a
MathML function (e.g., abs()
), or an SBML Level 1
function, or a user-defined function.
true
if this ASTNode
is a function, false
otherwise.public boolean isInfinity()
true
(non-zero) if this node represents
the special IEEE 754 value infinity, false
(zero) otherwise.
true
if this ASTNode
is the special IEEE 754 value infinity,
false
otherwise.public boolean isInteger()
true
(non-zero) if this node contains an
integer value, false
(zero) otherwise.
true
if this ASTNode
is of type AST_INTEGER
, false
otherwise.public boolean isLambda()
true
(non-zero) if this node is a MathML
<lambda>
, false
(zero) otherwise.
true
if this ASTNode
is of type AST_LAMBDA
, false
otherwise.public boolean isLog10()
true
(non-zero) if this node represents a
log10
function, false
(zero) otherwise. More precisely, this
predicate returns true
if the node type is AST_FUNCTION_LOG
with two
children, the first of which is an AST_INTEGER
equal to 10.
true
if the given ASTNode
represents a log10() function,
false
otherwise.
libsbml.parseL3Formula(String formula)
public boolean isLogical()
true
(non-zero) if this node is a MathML
logical operator (i.e., and
, or
, not
, xor
).
true
if this ASTNode
is a MathML logical operatorpublic boolean isName()
true
(non-zero) if this node is a user-defined
variable name in SBML L1, L2 (MathML), or the special symbols delay
or time.
The predicate returns false
(zero) otherwise.
true
if this ASTNode
is a user-defined variable name in SBML
L1, L2 (MathML) or the special symbols delay or time.public boolean isNaN()
true
(non-zero) if this node represents the
special IEEE 754 value 'not a number' (NaN), false
(zero)
otherwise.
true
if this ASTNode
is the special IEEE 754 NaN.public boolean isNegInfinity()
true
(non-zero) if this node represents the
special IEEE 754 value 'negative infinity', false
(zero) otherwise.
true
if this ASTNode
is the special IEEE 754 value negative
infinity, false
otherwise.public boolean isNumber()
true
(non-zero) if this node contains a number,
false
(zero) otherwise. This is functionally equivalent to the
following code:
isInteger() || isReal()
true
if this ASTNode
is a number, false
otherwise.public boolean isOperator()
true
(non-zero) if this node is a mathematical
operator, meaning, +
, -
, *
,
/
or ^
(power).
true
if this ASTNode
is an operator.public boolean isPiecewise()
true
(non-zero) if this node is the MathML
<piecewise>
construct, false
(zero) otherwise.
true
if this ASTNode
is a MathML piecewise
functionpublic boolean isRational()
true
(non-zero) if this node represents a rational
number, false
(zero) otherwise.
true
if this ASTNode
is of type AST_RATIONAL
.public boolean isReal()
true
(non-zero) if this node can represent a
real number, false
(zero) otherwise. More precisely, this node
must be of one of the following types: AST_REAL
, AST_REAL_E
or
AST_RATIONAL
.
true
if the value of this ASTNode
can represented as a real
number, false
otherwise.public boolean isRelational()
true
(non-zero) if this node is a MathML
relational operator, meaning ==
, >=
,
>
, <
, and !=
.
true
if this ASTNode
is a MathML relational operator,
false
otherwisepublic boolean isSetClass()
true
(non-zero) if this node has the mathml attribute
class
.
ASTNode
has an attribute class, false otherwise.public boolean isSetId()
true
(non-zero) if this node has the mathml attribute
id
.
ASTNode
has an attribute id, false otherwise.public boolean isSetStyle()
true
(non-zero) if this node has the mathml attribute
style
.
ASTNode
has an attribute style, false otherwise.public boolean isSetUnits()
true
(non-zero) if this node has the attribute
sbml:units
.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model
. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns='http://www.w3.org/1998/Math/MathML' xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> <cn type='integer' sbml:units='second'> 10 </cn> </math>
true
if this ASTNode
has units associated with it, false
otherwise.
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.public boolean isSqrt()
true
(non-zero) if this node represents a
square root function, false
(zero) otherwise. More precisely, the
node type must be AST_FUNCTION_ROOT
with two children, the first of which is an
AST_INTEGER
node having value
equal to 2.
true
if the given ASTNode
represents a sqrt() function,
false
otherwise.public boolean isUMinus()
true
(non-zero) if this node is a unary minus
operator, false
(zero) otherwise. A node is defined as a unary
minus node if it is of type AST_MINUS
and has exactly one child.
For numbers, unary minus nodes can be 'collapsed' by negating the
number. In fact,
libsbml.parseFormula(String formula)
does this during its parsing process, and
libsbml.parseL3Formula(String formula)
has a configuration option that allows this behavior to be turned
on or off. However, unary minus nodes for symbols
(AST_NAME
) cannot
be 'collapsed', so this predicate function is necessary.
true
if this ASTNode
is a unary minus, false
otherwise.
libsbml.parseL3Formula(String formula)
public boolean isUnknown()
true
(non-zero) if this node has an unknown type.
'Unknown' nodes have the type AST_UNKNOWN
. Nodes with unknown types will not appear in an
ASTNode
tree returned by libSBML based upon valid SBML input the only
situation in which a node with type AST_UNKNOWN
may appear is immediately after having create a
new, untyped node using the ASTNode
constructor. Callers creating
nodes should endeavor to set the type to a valid node type as soon as
possible after creating new nodes.
true
if this ASTNode
is of type AST_UNKNOWN
, false
otherwise.public boolean isUPlus()
true
(non-zero) if this node is a unary plus
operator, false
(zero) otherwise. A node is defined as a unary
minus node if it is of type AST_MINUS
and has exactly one child.
true
if this ASTNode
is a unary plus, false
otherwise.public boolean isWellFormedASTNode()
true
if this ASTNode
is well-formed, false
otherwise.
ASTNode.hasCorrectNumberArguments()
ASTNode
may be well-formed, with each node and its children
having the appropriate number of children for the given type, but may
still be invalid in the context of its use within an SBML model.
public int prependChild(ASTNode child)
ASTNode
. This method adds
child nodes from right to left.
child
- the ASTNode
instance to add
ASTNode.addChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
may change the structure of the
mathematical formula being represented by the tree structure, and may
render the representation invalid.
public void reduceToBinary()
public int removeChild(long n)
ASTNode
object.
n
- long the index of the child to remove
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.replaceChild(long n, ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
ASTNode
may change the structure of the
mathematical formula being represented by the tree structure, and may
render the representation invalid.
public void renameSIdRefs(String oldid, String newid)
public void renameUnitSIdRefs(String oldid, String newid)
<cn>
elements.)public void replaceArgument(String bvar, ASTNode arg)
ASTNode
with the
name/value/formula represented by arg
.
For example, if the formula in this ASTNode
is x + y
,
then the <bvar>
is x
and arg
is an ASTNode
representing the real value 3.
This method substitutes 3
for
x
within this ASTNode
object.
bvar
- a string representing the variable name to be substitutedarg
- an ASTNode
representing the name/value/formula to substitutepublic int replaceChild(long n, ASTNode newChild)
n
- long the index of the child to replacenewChild
- ASTNode
to replace the nth child
ASTNode.addChild(ASTNode child)
,
ASTNode.prependChild(ASTNode child)
,
ASTNode.insertChild(long n, ASTNode child)
,
ASTNode.removeChild(long n)
ASTNode
may change the structure of the
mathematical formula being represented by the tree structure, and may
render the representation invalid.
public boolean returnsBoolean()
true
(non-zero) if this node returns a boolean type
or false
(zero) otherwise.
This function looks at the whole ASTNode
rather than just the top
level of the ASTNode
. Thus it will consider return values from
piecewise statements. In addition, if this ASTNode
uses a function
call, the return value of the functionDefinition will be determined.
Note that this is only possible where the ASTNode
can trace its parent
Model
, that is, the ASTNode
must represent the math element of some
SBML object that has already been added to an instance of an SBMLDocument
.
ASTNode
returns a boolean, false otherwise.
public boolean returnsBoolean(Model model)
true
(non-zero) if this node returns a boolean type
or false
(zero) otherwise.
This function looks at the whole ASTNode
rather than just the top
level of the ASTNode
. Thus it will consider return values from
piecewise statements. In addition, if this ASTNode
uses a function
call, the return value of the functionDefinition will be determined.
Note that this is only possible where the ASTNode
can trace its parent
Model
, that is, the ASTNode
must represent the math element of some
SBML object that has already been added to an instance of an SBMLDocument
.
ASTNode
returns a boolean, false otherwise.
public int setCharacter(char value)
ASTNode
to the given character. If character
is one of +
, -
, *
, /
or ^
, the node
type will be set accordingly. For all other characters, the node type
will be set to AST_UNKNOWN
.
value
- the character value to which the node's value should be
set.
public int setClassName(String className)
ASTNode
to className.
className
- string
representing the mathml class for this node.
public int setId(String id)
ASTNode
to id.
id
- string
representing the identifier.
public int setName(String name)
ASTNode
to the given name.
As a side-effect, this ASTNode
object's type will be reset to
AST_NAME
if (and only
if) the ASTNode
was previously an operator (
ASTNode.isOperator()
== true
), number (
ASTNode.isNumber()
== true
), or unknown.
This allows names to be set for AST_FUNCTION
nodes and the like.
name
- the string containing the name to which this node's value
should be set
public int setStyle(String style)
ASTNode
to style.
style
- string
representing the identifier.
public int setType(int type)
ASTNode
to the given type code. A side-effect
of doing this is that any numerical values previously stored in this
node are reset to zero.
type
- the type to which this node should be set
public int setUnits(String units)
ASTNode
to units.
The units will be set only if this ASTNode
object represents a
MathML <cn>
element, i.e., represents a number.
Callers may use
ASTNode.isNumber()
to inquire whether the node is of that type.
SBML Level 3 Version 1 introduced the ability to include an
attribute sbml:units
on MathML cn
elements
appearing in SBML mathematical formulas. The value of this attribute can
be used to indicate the unit of measurement to be associated with the
number in the content of the cn
element. The value of this
attribute must be the identifier of a unit of measurement defined by SBML
or the enclosing Model
. Here, the sbml
portion is an XML
namespace prefix that must be associated with the SBML namespace for SBML
Level 3. The following example illustrates how this attribute can be
used to define a number with value 10
and unit of measurement
second
:
<math xmlns='http://www.w3.org/1998/Math/MathML' xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> <cn type='integer' sbml:units='second'> 10 </cn> </math>
units
- string
representing the unit identifier.
sbml:units
attribute is only available in SBML
Level 3. It may not be used in Levels 1&ndash2 of SBML.public int setValue(double value)
ASTNode
to the given real (double
) and sets
the node type to AST_REAL
.
This is functionally equivalent to:
setValue(value, 0)
value
- the double
format number to which this node's value
should be set
LIBSBML_OPERATION_SUCCESS
public int setValue(double mantissa, int exponent)
ASTNode
to the given real (double
) in two
parts: the mantissa and the exponent. The node type is set to
AST_REAL_E
.
mantissa
- the mantissa of this node's real-numbered valueexponent
- the exponent of this node's real-numbered value
public int setValue(int value)
value
- the integer to which this node's value should be set
public int setValue(int numerator, int denominator)
ASTNode
to the given rational in two parts: the
numerator and denominator. The node type is set to AST_RATIONAL
.
numerator
- the numerator value of the rationaldenominator
- the denominator value of the rational
public int swapChildren(ASTNode that)
that
- the other node whose children should be used to replace
this node's children
public int unsetClass()
ASTNode
.
public int unsetId()
ASTNode
.
public int unsetStyle()
ASTNode
.
public int unsetUnits()
ASTNode
.