libSBML Python API
5.18.0

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.
The function parseL3FormulaWithSettings(), along with its variants parseL3Formula() and parseL3FormulaWithModel(), are the interfaces to a parser for mathematical formulas written as text strings. The inverse function is formulaToL3String() and its variants such as formulaToL3StringWithSettings(). The parsers and the formula writers convert between a textstring representation of mathematical formulas and Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser and writer implemented by the functions parseFormula() and formulaToString(), which were designed primarily for converting the mathematical formula strings in SBML Level 1, the SBML Level 3 or 'L3' variants of the parser and writer use an extended formula syntax. They also have a number of configurable behaviors. This class (L3ParserSettings) is an object used to communicate the configuration settings with callers.
The following aspects of the parser are configurable using L3ParserSettings objects. (For the formula writer, only a subset of these settings is relevant; please see the documentation for formulaToL3StringWithSettings() for more information about which ones).
SId
) from the model in preference to predefined MathML symbols More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "pi
", and the formula to be parsed is "3*pi
", the MathML produced by the parser will contain the construct <ci> pi </ci>
instead of the construct <pi/>
. Another example, if the passedin Model contains a FunctionDefinition with the identifier "sin
", that function will be used instead of the predefined MathML function <sin/>
. log
with a single argument ("log(x)
") can be parsed as log10(x)
, ln(x)
, or treated as an error, as desired.  3
") from the input and incorporate single unary minuses into the number node, or (2) preserve all minuses in the AST node structure, turning them into ASTNode objects of type AST_MINUS. number id
" can be interpreted as a numerical value number
followed by units of measurement indicated by id
, or it can be treated as a syntax error. (In Level 3, MathML <cn>
elements can have an attribute named units
placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The textstring infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object.) avogadro
can be parsed either as a MathML csymbol or as a identifier. More specifically, "avogadro
" can be treated as an ASTNode of type AST_NAME_AVOGADRO or of type AST_NAME. To obtain the default configuration values, callers can use the function getDefaultL3ParserSettings(). To change the configuration, callers can create an L3ParserSettings object, set the desired characteristics using the methods provided, and pass that object to parseL3FormulaWithSettings().
Public Member Functions  
def  __init__ (self, args) 
This method has multiple variants; they differ in the arguments they accept. More...  
def  getComparisonCaseSensitivity (self) 
Returns True if the parser is configured to match builtin symbols in a caseinsensitive way. More...  
def  getModel (self) 
Returns the Model object referenced by this L3ParserSettings object. More...  
def  getParseAvogadroCsymbol (self) 
Indicates the current behavior set for handling avogadro for SBML Level 3. More...  
def  getParseCollapseMinus (self) 
Indicates the current behavior set for handling multiple unary minuses in formulas. More...  
def  getParseL3v2Functions (self) 
Indicates the current behavior set for handling whether to parse the functions added in L3v2 as that MathML or not. More...  
def  getParseLog (self) 
Indicates the current behavior set for handling the function log with one argument. More...  
def  getParseModuloL3v2 (self) 
Indicates the current behavior set for handling the '' sumbol in mathematical formulas. More...  
def  getParsePackageMath (self, package) 
Indicates the current behavior set for handling whether to parse the functions added in the given package as that MathML or not. More...  
def  getParseUnits (self) 
Indicates the current behavior set for handling units in textstring mathematical formulas. More...  
def  setComparisonCaseSensitivity (self, strcmp) 
Sets the parser's behavior with respect to case sensitivity for recognizing predefined symbols. More...  
def  setModel (self, model) 
Sets the model reference in this L3ParserSettings object. More...  
def  setParseAvogadroCsymbol (self, l2only) 
Sets the parser's behavior in handling the symbol avogadro in mathematical formulas. More...  
def  setParseCollapseMinus (self, collapseminus) 
Sets the behavior for handling unary minuses appearing in mathematical formulas. More...  
def  setParseL3v2Functions (self, l3v2functions) 
Sets the behavior for handling functions added in SBML L3v2. More...  
def  setParseLog (self, type) 
Sets the behavior for handling log in mathematical formulas. More...  
def  setParseModuloL3v2 (self, modulol3v2) 
Sets the behavior for handling the '' sumbol in mathematical formulas. More...  
def  setParsePackageMath (self, package, parsepackage) 
Sets the behavior for handling functions added in SBML packages. More...  
def  setParseUnits (self, units) 
Sets the parser's behavior in handling units associated with numbers in a mathematical formula. More...  
def  unsetModel (self) 
Unsets the Model reference in this L3ParserSettings object. More...  
def libsbml.L3ParserSettings.__init__  (  self,  
args  
) 
This method has multiple variants; they differ in the arguments they accept.
__init__() L3ParserSettings __init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive, SBMLNamespaces sbmlns, bool moduloL3v2, bool l3v2functions) L3ParserSettings __init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive, SBMLNamespaces sbmlns, bool moduloL3v2) L3ParserSettings __init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive, SBMLNamespaces sbmlns) L3ParserSettings __init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive) L3ParserSettings __init__(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol) L3ParserSettings __init__(L3ParserSettings source) L3ParserSettings
Each variant is described separately below.
L3ParserSettings()
Creates a new L3ParserSettings object with default values.
This is the default constructor for the L3ParserSettings object. It sets the stored Model object to None
and sets the following field values in the L3ParserSettings object:
None
(which indicates that no syntax extensions due to SBML Level 3 packages will be assumed—the formula parser will only understand the core syntax described in the documentation for parseL3Formula()).L3ParserSettings(L3ParserSettings source)
Copy constructor.
source  the instance to copy. 
L3ParserSettings(Model model, long parselog, bool collapseminus, bool parseunits, bool avocsymbol, bool caseSensitive = false, SBMLNamespaces sbmlns = None, bool moduloL3v2 = false, bool l3v2functions = false)
Creates a new L3ParserSettings object with specific values for all possible settings.
model  a Model object to be used for disambiguating identifiers encountered by parseL3FormulaWithSettings() in mathematical formulas. 
parselog  ('parse log') a flag that controls how the parser will handle the symbol log in mathematical formulas. The function log with a single argument ("log(x) ") can be parsed as log10(x) , ln(x) , or treated as an error, as desired, by using the parameter values L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, or L3P_PARSE_LOG_AS_ERROR, respectively. 
collapseminus  ('collapse minus') a flag that controls how the parser will handle minus signs in formulas. Unary minus signs can be collapsed or preserved; that is, sequential pairs of unary minuses (e.g., " 3 ") can be removed from the input entirely and single unary minuses can be incorporated into the number node, or all minuses can be preserved in the AST node structure. The possible values of this field are L3P_COLLAPSE_UNARY_MINUS (to collapse unary minuses) and L3P_EXPAND_UNARY_MINUS (to expand unary minuses). 
parseunits  ('parse units') a flag that controls how the parser will handle apparent references to units of measurement associated with raw numbers in a formula. If set to the value L3P_PARSE_UNITS, units are parsed; if set to the value L3P_NO_UNITS, units are not parsed. 
avocsymbol  ('Avogadro csymbol') a flag that controls how the parser will handle the appearance of the symbol avogadro in a formula. If set to the value L3P_AVOGADRO_IS_CSYMBOL, the symbol is interpreted as the SBML/MathML csymbol avogadro ; if set to the value L3P_AVOGADRO_IS_NAME, the symbol is interpreted as a plain symbol name. 
caseSensitive  ('case sensitive') a flag that controls how the cases of alphabetical characters are treated when symbols are compared. If the flag is set to the value L3P_COMPARE_BUILTINS_CASE_INSENSITIVE, symbols are compared in a caseinsensitive manner, which means that mathematical functions such as 'sin' will be matched no matter what their case is: 'Sin' , 'SIN' , etc. If the flag is set to the value L3P_COMPARE_BUILTINS_CASE_SENSITIVE, symbols are interpreted in a casesensitive manner. 
moduloL3v2  ('modulo l3v2') a flag that controls how the parser will handle the '' ('modulo') symbol in formulas. By default, the parser will convert 'a % b' to a piecewise function that properly calculates the remainder of a with respect to be, but the parser can also be set to produce the MathML rem function, should the target of the produced ASTNode be an SBML Level 3 Version 2 document, where the rem function is legal. The possible values of this field are L3P_MODULO_IS_PIECEWISE (to parse '' as a piecewise function) and L3P_MODULO_IS_REM (to parse '' as rem ). 
sbmlns  ('SBML namespaces') an SBML namespaces object. The namespaces identify the SBML Level 3 packages that can extend the syntax understood by the formula parser. When nonNone , the parser will interpret additional syntax defined by the packages; for example, it may understand vector/array extensions introduced by the SBML Level 3 Arrays package. 
l3v2functions  a Boolean 
parameter
= value
. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense. def libsbml.L3ParserSettings.getComparisonCaseSensitivity  (  self  ) 
Returns True
if the parser is configured to match builtin symbols in a caseinsensitive way.
getComparisonCaseSensitivity() bool
'sin'
and 'piecewise'
, and for constants such as 'True'
and 'avogadro'
. Setting this option to L3P_COMPARE_BUILTINS_CASE_SENSITIVE causes the parser to become case sensitive. In that mode, for example, the symbols 'sin'
and 'True'
will match the builtin values, but the symbols 'SIN'
, 'Sin'
, 'True'
, 'TRUE'
, and so on, will not.True
if matches are done in a casesensitive manner, and False
if the parser will recognize builtin functions and constants regardless of case,.def libsbml.L3ParserSettings.getModel  (  self  ) 
Returns the Model object referenced by this L3ParserSettings object.
getModel() Model
SId
) from that model are used in preference to predefined MathML symbol definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "pi
", and the formula to be parsed is "3*pi
", the MathML produced will contain the construct <ci> pi </ci>
instead of the construct <pi/>
. Similarly, when a Model object is provided, SId
values of userdefined functions present in the Model will be used preferentially over predefined MathML functions. For example, if the passedin Model contains a FunctionDefinition with the identifier "sin
", that function will be used instead of the predefined MathML function <sin/>
.def libsbml.L3ParserSettings.getParseAvogadroCsymbol  (  self  ) 
Indicates the current behavior set for handling avogadro
for SBML Level 3.
getParseAvogadroCsymbol() bool
avogadro
in the input as a reference to the MathML csymbol for Avogadro's constant defined in the SBML Level 3 specification. For Level 2, it must treat avogadro
as just another plain symbol.This method returns the current setting of the avogadro
handling behavior in this L3ParserSettings object. The possible values are as follows:
True
): tells the parser to translate the string avogadro
(in any capitalization) into an AST node of type AST_NAME_AVOGADRO. False
): tells the parser to translate the string avogadro
into an AST of type AST_NAME. def libsbml.L3ParserSettings.getParseCollapseMinus  (  self  ) 
Indicates the current behavior set for handling multiple unary minuses in formulas.
getParseCollapseMinus() bool
 3
") can be collapsed and ignored in the input, or the multiple minuses can be preserved in the AST node tree that is generated by the parser. Second, minus signs in front of numbers can be collapsed into the number node itself; for example, a " 4.1
" can be turned into a single ASTNode of type AST_REAL with a value of 4.1
, or it can be turned into a node of type AST_MINUS having a child node of type AST_REAL.True
): collapse unary minuses where possible. False
): do not collapse unary minuses, and instead translate each one into an AST node of type AST_MINUS. def libsbml.L3ParserSettings.getParseL3v2Functions  (  self  ) 
Indicates the current behavior set for handling whether to parse the functions added in L3v2 as that MathML or not.
getParseL3v2Functions() bool
True
): parse the strings 'rateOf', 'implies', 'max', 'min', 'quotient', and 'rem' as AST_FUNCTION_RATE_OF, AST_LOGICAL_IMPLIES, AST_FUNCTION_MAX, AST_FUNCTION_MIN, AST_FUNCTION_QUOTIENT, and AST_FUNCTION_REM, respectively. False
): parse the strings 'rateOf', 'implies', 'max', 'min', 'quotient', and 'rem' all as AST_FUNCTION with the appropriate name set. def libsbml.L3ParserSettings.getParseLog  (  self  ) 
Indicates the current behavior set for handling the function log
with one argument.
getParseLog() long
The function log
with a single argument ("log(x)
") can be parsed as log10(x)
, ln(x)
, or treated as an error, as desired. These three possible behaviors are indicated, respectively, by the values L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, and L3P_PARSE_LOG_AS_ERROR.
def libsbml.L3ParserSettings.getParseModuloL3v2  (  self  ) 
Indicates the current behavior set for handling the '' sumbol in mathematical formulas.
getParseModuloL3v2() bool
True
): use the 'rem' MathML function (AST_FUNCTION_REM). False
): use a piecewise function (AST_FUNCTION_PIECEWISE) to encode the modulo rule explicitly. def libsbml.L3ParserSettings.getParsePackageMath  (  self,  
package  
) 
Indicates the current behavior set for handling whether to parse the functions added in the given package as that MathML or not.
getParsePackageMath(ExtendedMathType_t package) bool
True
): parse any string defined in a given SBML L3 package as its corresponding ASTType_t. False
): parse any string that would have been defined in the given SBML L3 package as AST_FUNCTION or AST_NAME with the appropriate name set. def libsbml.L3ParserSettings.getParseUnits  (  self  ) 
Indicates the current behavior set for handling units in textstring mathematical formulas.
getParseUnits() bool
<cn>
elements can have an attribute named units
placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The textstring infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object. Some examples include: "4 mL
", "2.01 Hz
", "3.1e6 M
", and "(5/8) inches
". To produce a valid SBML model, there must either exist a UnitDefinition corresponding to the identifier of the unit, or the unit must be defined in Table 2 of the SBML Level 3 specification.Since SBML Level 2 does not have the ability to associate units with pure numbers, the value should be expected to be False
(L3P_NO_UNITS) when parsing textstring formulas intended for use in SBML Level 2 documents.
True
): parse units in the textstring formula. False
): treat units in the textstring formula as errors. def libsbml.L3ParserSettings.setComparisonCaseSensitivity  (  self,  
strcmp  
) 
Sets the parser's behavior with respect to case sensitivity for recognizing predefined symbols.
setComparisonCaseSensitivity(bool strcmp)
'sin'
and 'piecewise'
, and for constants such as 'True'
and 'avogadro'
. Setting this option to L3P_COMPARE_BUILTINS_CASE_SENSITIVE causes the parser to become case sensitive. In that mode, for example, the symbols 'sin'
and 'True'
will match the builtin values, but the symbols 'SIN'
, 'Sin'
, 'True'
, 'TRUE'
, and so on, will not.strcmp  a boolean indicating whether to be case sensitive (if True ) or be case insensitive (if False ). 
def libsbml.L3ParserSettings.setModel  (  self,  
model  
) 
Sets the model reference in this L3ParserSettings object.
setModel(Model model)
SId
) from that model are used in preference to predefined MathML symbol definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "pi
", and the formula to be parsed is "3*pi
", the MathML produced will contain the construct <ci> pi </ci>
instead of the construct <pi/>
. Similarly, when a Model object is provided, SId
values of userdefined functions present in the Model will be used preferentially over predefined MathML functions. For example, if the passedin Model contains a FunctionDefinition with the identifier "sin
", that function will be used instead of the predefined MathML function <sin/>
.model  a Model object to be used for disambiguating identifiers. 
def libsbml.L3ParserSettings.setParseAvogadroCsymbol  (  self,  
l2only  
) 
Sets the parser's behavior in handling the symbol avogadro
in mathematical formulas.
setParseAvogadroCsymbol(bool l2only)
avogadro
in the input as a reference to the MathML csymbol for Avogadro's constant defined in the SBML Level 3 specification. For Level 2, it must treat avogadro
as just another plain symbol.This method allows callers to set the avogadro
handling behavior in this L3ParserSettings object. The possible values of l2only
are as follows:
True
): tells the parser to translate the string avogadro
(in any capitalization) into an AST node of type AST_NAME_AVOGADRO. False
): tells the parser to translate the string avogadro
into an AST of type AST_NAME. Since SBML Level 2 does not define a symbol for Avogadro's constant, the value should be set to L3P_AVOGADRO_IS_NAME when parsing textstring formulas intended for use in SBML Level 2 documents.
l2only  a boolean value indicating how the string avogadro should be treated when encountered in a formula. This will be one of the values L3P_AVOGADRO_IS_CSYMBOL or L3P_AVOGADRO_IS_NAME. 
def libsbml.L3ParserSettings.setParseCollapseMinus  (  self,  
collapseminus  
) 
Sets the behavior for handling unary minuses appearing in mathematical formulas.
setParseCollapseMinus(bool collapseminus)
 3
") can be collapsed and ignored in the input, or the multiple minuses can be preserved in the AST node tree that is generated by the parser. Second, minus signs in front of numbers can be collapsed into the number node itself; for example, a " 4.1
" can be turned into a single ASTNode of type AST_REAL with a value of 4.1
, or it can be turned into a node of type AST_MINUS having a child node of type AST_REAL.This method lets you tell the parser which behavior to use—either collapse minuses or always preserve them. The two possibilities are represented using the following constants:
True
): collapse unary minuses where possible. False
): do not collapse unary minuses, and instead translate each one into an AST node of type AST_MINUS. collapseminus  a boolean value (one of the constants L3P_COLLAPSE_UNARY_MINUS or L3P_EXPAND_UNARY_MINUS) indicating how unary minus signs in the input should be handled. 
def libsbml.L3ParserSettings.setParseL3v2Functions  (  self,  
l3v2functions  
) 
Sets the behavior for handling functions added in SBML L3v2.
setParseL3v2Functions(bool l3v2functions)
This method lets you tell the parser which behavior to use—either to parse the functions added in L3v2 as their builtin counterparts, or as generic functions with that name (to be defined by SBML as function definitions). The two possibilities are represented using the following constants:
True
): parse the strings 'rateOf', 'implies', 'max', 'min', 'quotient', and 'rem' as AST_FUNCTION_RATE_OF, AST_LOGICAL_IMPLIES, AST_FUNCTION_MAX, AST_FUNCTION_MIN, AST_FUNCTION_QUOTIENT, and AST_FUNCTION_REM, respectively. False
): parse the strings 'rateOf', 'implies', 'max', 'min', 'quotient', and 'rem' all as AST_FUNCTION with the appropriate name set. l3v2functions  a boolean value (one of the constants L3P_PARSE_L3V2_FUNCTIONS_DIRECTLY or L3P_PARSE_L3V2_FUNCTIONS_AS_GENERIC) indicating how to interpret those function names. 
def libsbml.L3ParserSettings.setParseLog  (  self,  
type  
) 
Sets the behavior for handling log
in mathematical formulas.
setParseLog(long type)
The function log
with a single argument ("log(x)
") can be parsed as log10(x)
, ln(x)
, or treated as an error. These three behaviors are set, respectively, by using the value L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, or L3P_PARSE_LOG_AS_ERROR for the type
parameter.
type  a constant, one of following three possibilities: 
def libsbml.L3ParserSettings.setParseModuloL3v2  (  self,  
modulol3v2  
) 
Sets the behavior for handling the '' sumbol in mathematical formulas.
setParseModuloL3v2(bool modulol3v2)
This method lets you tell the parser which behavior to use—either parse '' as the 'rem' function or as a piecewise function with the same interpretation. The two possibilities are represented using the following constants:
True
): use the 'rem' MathML function (AST_FUNCTION_REM). False
): use a piecewise function (AST_FUNCTION_PIECEWISE) to encode the modulo rule explicitly. modulol3v2  a boolean value (one of the constants L3P_MODULO_IS_PIECEWISE or L3P_MODULO_IS_REM) indicating how the '' symbol in the input should be handled. 
def libsbml.L3ParserSettings.setParsePackageMath  (  self,  
package,  
parsepackage  
) 
Sets the behavior for handling functions added in SBML packages.
setParsePackageMath(ExtendedMathType_t package, bool parsepackage)
This method lets you tell the parser which behavior to use—either to parse the functions added in a given package as their builtin counterparts, or as generic functions with that name (to be defined by SBML as function definitions). The two possibilities are represented using the following constants:
True
): parse any string defined in a given SBML L3 package as its corresponding ASTType_t. False
): parse any string that would have been defined in the given SBML L3 package as AST_FUNCTION or AST_NAME with the appropriate name set. package  a boolean value (one of the constants L3P_PARSE_L3V2_FUNCTIONS_DIRECTLY or L3P_PARSE_L3V2_FUNCTIONS_AS_GENERIC) indicating how to interpret those function names. 
parsepackage  a boolean 
def libsbml.L3ParserSettings.setParseUnits  (  self,  
units  
) 
Sets the parser's behavior in handling units associated with numbers in a mathematical formula.
setParseUnits(bool units)
<cn>
elements can have an attribute named units
placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The textstring infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object. Some examples include: "4 mL
", "2.01 Hz
", "3.1e6 M
", and "(5/8) inches
". To produce a valid SBML model, there must either exist a UnitDefinition corresponding to the identifier of the unit, or the unit must be defined in Table 2 of the SBML Level 3 specification.This method sets the formula parser's behavior with respect to units.
units  a boolean indicating whether to parse units. The possible values are as follows:

def libsbml.L3ParserSettings.unsetModel  (  self  ) 
Unsets the Model reference in this L3ParserSettings object.
unsetModel()
The effect of calling this method is to set the stored model value to None
.