001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 3.0.10
004 *
005 * Do not make changes to this file unless you know what you are doing--modify
006 * the SWIG interface file instead.
007 * ----------------------------------------------------------------------------- */
008
009package org.sbml.libsbml;
010
011
012/**
013  * Wrapper class for global methods and constants defined by libSBML.
014  * <p>
015  * <em style='color: #555'>
016  * This class of objects is defined by libSBML only and has no direct
017  * equivalent in terms of SBML components.  This class is not prescribed by
018  * the SBML specifications, although it is used to implement features
019  * defined in SBML.
020  * </em>
021  * <p>
022  * In the C++ and C versions of libSBML, there exists a small number of
023  * methods that are global in scope; in addition, libSBML uses a number
024  * of enum's to define such things as error codes in a way that can be
025  * used by both C++ and C.  This poses a problem in languages such as
026  * Java, where there is no concept of global method or global constant.
027  * SWIG wraps these global identifiers in the class whose documentation
028  * you see before you.
029  */
030public class libsbml implements libsbmlConstants {
031
032    
033  /**
034   * Downcast a package extension object to its specific package class.
035   *
036   * This method is used in the implementation of libSBML extensions to
037   * support SBML Level&nbsp;3 packages.  It allows an object to be
038   * downcast to the actual {@link SBMLExtension} object it is.
039   *
040   * @param cPtr the the pointer to the object
041   * @param owner if <code>true</code>, it indicates the caller will "own"
042   * the memory associated with the object and will be responsible for
043   * freeing it.
044   *
045   * @return the {@link SBMLExtension} for the package
046   *
047   * @internal
048   */
049  public static SBMLExtension DowncastExtension(long cPtr, boolean owner)
050  {     
051    if (cPtr == 0) return null;
052        
053    SBMLExtension ext = new SBMLExtension(cPtr, false);
054    String pkgName = ext.getName();
055
056
057    if (pkgName.equals("comp"))
058        return new CompExtension(cPtr, owner);
059    
060
061  if (pkgName.equals("fbc"))
062  {
063    return new FbcExtension(cPtr, owner);
064  }
065
066
067    if (pkgName.equals("groups"))
068        return new GroupsExtension(cPtr, owner);
069    
070
071    if (pkgName.equals("layout"))
072        return new LayoutExtension(cPtr, owner);
073    
074
075    if (pkgName.equals("qual"))
076        return new QualExtension(cPtr, owner);
077    
078
079    if (pkgName.equals("render"))
080        return new RenderExtension(cPtr, owner);
081    
082
083    return new SBMLExtension(cPtr,owner);
084  }     
085        
086  /**
087   * SBMLExtension derived classes must override this method
088   * @internal
089   */
090  public static SBasePlugin DowncastSBasePlugin(long cPtr, boolean owner)
091  {
092    if (cPtr == 0) return null;
093
094    SBasePlugin sbp = new SBasePlugin(cPtr,false);
095    String pkgName = sbp.getPackageName();
096
097    SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName);
098    if (sbmlext != null)
099    {
100      return sbmlext.DowncastSBasePlugin(cPtr,owner);
101    }
102    return new SBasePlugin(cPtr,owner);
103  }
104
105  /**
106   * @internal
107   */
108  public static SBMLConverter DowncastSBMLConverter(long cPtr, boolean owner)
109  {
110    if (cPtr == 0) return null;
111                
112    SBMLConverter con = new SBMLConverter(cPtr, false);
113    String conName = con.getName();
114    
115    if (conName.equals("SBML Units Converter"))
116      return new SBMLUnitsConverter(cPtr,owner);
117    else if (conName.equals("SBML Strip Package Converter"))
118      return new SBMLStripPackageConverter(cPtr,owner);
119    else if (conName.equals("SBML Rule Converter"))
120      return new SBMLRuleConverter(cPtr,owner);
121    else if (conName.equals("SBML Reaction Converter"))
122      return new SBMLReactionConverter(cPtr,owner);
123    else if (conName.equals("SBML Local Parameter Converter"))
124      return new SBMLLocalParameterConverter(cPtr,owner);
125    else if (conName.equals("SBML Level Version Converter"))
126      return new SBMLLevelVersionConverter(cPtr,owner);
127    else if (conName.equals("SBML Initial Assignment Converter"))
128      return new SBMLInitialAssignmentConverter(cPtr,owner);
129    else if (conName.equals("SBML Infer Units Converter"))
130      return new SBMLInferUnitsConverter(cPtr,owner);
131    else if (conName.equals("SBML Id Converter"))
132      return new SBMLIdConverter(cPtr,owner);
133    else if (conName.equals("SBML Function Definition Converter"))
134      return new SBMLFunctionDefinitionConverter(cPtr,owner);
135
136
137    if (conName.equals("SBML Comp Flattening Converter"))
138        return new CompFlatteningConverter(cPtr, owner);
139
140
141    if (conName.equals("SBML FBC to COBRA Converter"))
142        return new FbcToCobraConverter(cPtr, owner);
143    if (conName.equals("SBML COBRA to FBC Converter"))
144        return new CobraToFbcConverter(cPtr, owner);
145
146
147    // layout converters here
148
149
150    // qual converters here
151
152        
153    return new SBMLConverter(cPtr,owner);
154  }
155  
156  /**
157   * @internal
158   */
159  public static SBMLNamespaces DowncastSBMLNamespaces(long cPtr, boolean owner)
160  {
161    if (cPtr == 0) return null;
162                
163    SBMLNamespaces sbn = new SBMLNamespaces(cPtr, false);
164    if (sbn != null)
165    {
166      XMLNamespaces ns = sbn.getNamespaces();
167
168
169    
170    if (ns.hasURI(CompExtension.getXmlnsL3V1V1()))
171    {
172        return new CompPkgNamespaces(cPtr, owner);
173    }
174    
175
176  if (ns.hasURI(FbcExtension.getXmlnsL3V1V1()))
177  {
178    return new FbcPkgNamespaces(cPtr, owner);
179  }
180
181
182    
183    if (ns.hasURI(GroupsExtension.getXmlnsL3V1V1()))
184    {
185        return new GroupsPkgNamespaces(cPtr, owner);
186    }
187    
188
189    
190    if (ns.hasURI(LayoutExtension.getXmlnsL3V1V1()) || ns.hasURI(LayoutExtension.getXmlnsL2()))
191    {
192        return new LayoutPkgNamespaces(cPtr, owner);
193    }
194    
195
196    
197    if (ns.hasURI(QualExtension.getXmlnsL3V1V1()))
198    {
199        return new QualPkgNamespaces(cPtr, owner);
200    }
201    
202
203    
204    if (ns.hasURI(RenderExtension.getXmlnsL3V1V1()) || ns.hasURI(RenderExtension.getXmlnsL2()))
205    {
206        return new RenderPkgNamespaces(cPtr, owner);
207    }
208    
209                              
210    }
211    return new SBMLNamespaces(cPtr, owner);
212  }     
213  
214  /**
215   * Internal method.
216   *
217   * @internal
218   */
219  public static SBase DowncastSBase(long cPtr, boolean owner)
220  {
221    if (cPtr == 0) return null;
222
223    SBase sb = new SBase(cPtr,false);
224    String pkgName = sb.getPackageName();
225    if (pkgName.equals("core"))
226    {
227      switch( sb.getTypeCode() )
228      {
229        case libsbmlConstants.SBML_COMPARTMENT:
230          return new Compartment(cPtr, owner);
231  
232        case libsbmlConstants.SBML_COMPARTMENT_TYPE:
233          return new CompartmentType(cPtr, owner);
234  
235        case libsbmlConstants.SBML_CONSTRAINT:
236          return new Constraint(cPtr, owner);
237  
238        case libsbmlConstants.SBML_DOCUMENT:
239          return new SBMLDocument(cPtr, owner);
240  
241        case libsbmlConstants.SBML_DELAY:
242          return new Delay(cPtr, owner);
243  
244        case libsbmlConstants.SBML_EVENT:
245          return new Event(cPtr, owner);
246
247        case libsbmlConstants.SBML_EVENT_ASSIGNMENT:
248          return new EventAssignment(cPtr, owner);
249
250        case libsbmlConstants.SBML_FUNCTION_DEFINITION:
251          return new FunctionDefinition(cPtr, owner);
252  
253        case libsbmlConstants.SBML_INITIAL_ASSIGNMENT:
254          return new InitialAssignment(cPtr, owner);
255
256        case libsbmlConstants.SBML_KINETIC_LAW:
257          return new KineticLaw(cPtr, owner);
258
259        case libsbmlConstants.SBML_LIST_OF:
260          String name = sb.getElementName();
261          if(name.equals("listOf")){
262            return new ListOf(cPtr, owner);
263          }
264          else if(name.equals("listOfCompartments")){
265            return new ListOfCompartments(cPtr, owner);
266          }
267          else if(name.equals("listOfCompartmentTypes")){
268            return new ListOfCompartmentTypes(cPtr, owner);
269          }
270          else if(name.equals("listOfConstraints")){
271            return new ListOfConstraints(cPtr, owner);
272          }
273          else if(name.equals("listOfEvents")){
274            return new ListOfEvents(cPtr, owner);
275          }
276          else if(name.equals("listOfEventAssignments")){
277            return new ListOfEventAssignments(cPtr, owner);
278          }
279          else if(name.equals("listOfFunctionDefinitions")){
280            return new ListOfFunctionDefinitions(cPtr, owner);
281          }
282          else if(name.equals("listOfInitialAssignments")){
283            return new ListOfInitialAssignments(cPtr, owner);
284          }
285          else if(name.equals("listOfParameters")){
286            return new ListOfParameters(cPtr, owner);
287          }
288          else if(name.equals("listOfLocalParameters")){
289            return new ListOfLocalParameters(cPtr, owner);
290          }
291          else if(name.equals("listOfReactions")){
292            return new ListOfReactions(cPtr, owner);
293          }
294          else if(name.equals("listOfRules")){
295            return new ListOfRules(cPtr, owner);
296          }
297          else if(name.equals("listOfSpecies")){
298            return new ListOfSpecies(cPtr, owner);
299          }
300          else if(name.equals("listOfUnknowns")){
301            return new ListOfSpeciesReferences(cPtr, owner);
302          }
303          else if(name.equals("listOfReactants")){
304            return new ListOfSpeciesReferences(cPtr, owner);
305          }
306          else if(name.equals("listOfProducts")){
307            return new ListOfSpeciesReferences(cPtr, owner);
308          }
309          else if(name.equals("listOfModifiers")){
310            return new ListOfSpeciesReferences(cPtr, owner);
311          }
312          else if(name.equals("listOfSpeciesTypes")){
313            return new ListOfSpeciesTypes(cPtr, owner);
314          }
315          else if(name.equals("listOfUnits")){
316            return new ListOfUnits(cPtr, owner);
317          }
318          else if(name.equals("listOfUnitDefinitions")){
319            return new ListOfUnitDefinitions(cPtr, owner);
320          }
321          return new ListOf(cPtr, owner);
322
323        case libsbmlConstants.SBML_MODEL:
324          return new Model(cPtr, owner);
325
326        case libsbmlConstants.SBML_PARAMETER:
327          return new Parameter(cPtr, owner);
328
329      case libsbmlConstants.SBML_PRIORITY:
330        return new Priority(cPtr, owner);
331
332      case libsbmlConstants.SBML_LOCAL_PARAMETER:
333        return new LocalParameter(cPtr, owner);
334
335        case libsbmlConstants.SBML_REACTION:
336          return new Reaction(cPtr, owner);
337
338        case libsbmlConstants.SBML_SPECIES:
339          return new Species(cPtr, owner);
340
341        case libsbmlConstants.SBML_SPECIES_REFERENCE:
342          return new SpeciesReference(cPtr, owner);
343
344        case libsbmlConstants.SBML_MODIFIER_SPECIES_REFERENCE:
345          return new ModifierSpeciesReference(cPtr, owner);
346
347        case libsbmlConstants.SBML_SPECIES_TYPE:
348          return new SpeciesType(cPtr, owner);
349
350        case libsbmlConstants.SBML_TRIGGER:
351          return new Trigger(cPtr, owner);
352
353        case libsbmlConstants.SBML_UNIT_DEFINITION:
354          return new UnitDefinition(cPtr, owner);
355
356        case libsbmlConstants.SBML_UNIT:
357          return new Unit(cPtr, owner);
358
359        case libsbmlConstants.SBML_ALGEBRAIC_RULE:
360          return new AlgebraicRule(cPtr, owner);
361
362        case libsbmlConstants.SBML_ASSIGNMENT_RULE:
363          return new AssignmentRule(cPtr, owner);
364
365        case libsbmlConstants.SBML_RATE_RULE:
366          return new RateRule(cPtr, owner);
367
368        case libsbmlConstants.SBML_STOICHIOMETRY_MATH:
369          return new StoichiometryMath(cPtr, owner);
370
371        default:
372          return new SBase(cPtr, owner);
373      }
374    }
375    else
376    {
377      SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName);
378      if (sbmlext != null)
379      {
380        return sbmlext.DowncastSBase(cPtr,owner);
381      }
382    }
383    return new SBase(cPtr, owner);
384  }
385  
386
387 
388  /**
389   * @internal
390   */
391  public static ASTBase DowncastASTBase(long cPtr, boolean owner)
392  {
393    if (cPtr == 0) return null;
394
395    ASTBase ab = new ASTBase(cPtr,false);
396    switch( ab.getTypeCode() )
397    {
398        default:
399        case libsbmlConstants.AST_TYPECODE_BASE:
400          return new ASTBase(cPtr, owner);
401          /*
402        case libsbmlConstants.AST_TYPECODE_CN_BASE:
403          return new ASTCnBase(cPtr, owner);
404        case libsbmlConstants.AST_TYPECODE_FUNCTION_BASE:
405          return new ASTFunctionBase(cPtr, owner);
406        case libsbmlConstants.AST_TYPECODE_NUMBER:
407          return new ASTNumber(cPtr, owner);
408        case libsbmlConstants.AST_TYPECODE_CN_INTEGER:
409          return new ASTCnIntegerNode(cPtr, owner);
410        case libsbmlConstants.AST_TYPECODE_CN_EXPONENTIAL:
411          return new ASTCnExponentialNode(cPtr, owner);
412        case libsbmlConstants.AST_TYPECODE_CN_RATIONAL:
413          return new ASTCnRationalNode(cPtr, owner);
414        case libsbmlConstants.AST_TYPECODE_CN_REAL:
415          return new ASTCnRealNode(cPtr, owner);
416        case libsbmlConstants.AST_TYPECODE_CSYMBOL:
417          return new ASTCSymbol(cPtr, owner);
418        case libsbmlConstants.AST_TYPECODE_CSYMBOL_AVOGADRO:
419          return new ASTCSymbolAvogadroNode(cPtr, owner);
420        case libsbmlConstants.AST_TYPECODE_CSYMBOL_DELAY:
421          return new ASTCSymbolDelayNode(cPtr, owner);
422        case libsbmlConstants.AST_TYPECODE_CSYMBOL_TIME:
423          return new ASTCSymbolTimeNode(cPtr, owner);
424        case libsbmlConstants.AST_TYPECODE_FUNCTION:
425          return new ASTFunction(cPtr, owner);
426        case libsbmlConstants.AST_TYPECODE_FUNCTION_UNARY:
427          return new ASTUnaryFunctionNode(cPtr, owner);
428        case libsbmlConstants.AST_TYPECODE_FUNCTION_BINARY:
429          return new ASTBinaryFunctionNode(cPtr, owner);
430        case libsbmlConstants.AST_TYPECODE_FUNCTION_NARY:
431          return new ASTNaryFunctionNode(cPtr, owner);
432        case libsbmlConstants.AST_TYPECODE_FUNCTION_PIECEWISE:
433          return new ASTPiecewiseFunctionNode(cPtr, owner);
434        case libsbmlConstants.AST_TYPECODE_FUNCTION_LAMBDA:
435          return new ASTLambdaFunctionNode(cPtr, owner);
436        case libsbmlConstants.AST_TYPECODE_FUNCTION_CI:
437          return new ASTCiFunctionNode(cPtr, owner);
438        case libsbmlConstants.AST_TYPECODE_FUNCTION_SEMANTIC:
439          return new ASTSemanticsNode(cPtr, owner);
440        case libsbmlConstants.AST_TYPECODE_FUNCTION_QUALIFIER:
441          return new ASTQualifierNode(cPtr, owner);*/
442        case libsbmlConstants.AST_TYPECODE_ASTNODE:
443          return new ASTNode(cPtr, owner);
444
445    }   
446    //return new ASTBase(cPtr, owner);
447  }
448  
449
450
451   static String getAbsolutePath(String filename)
452   {
453     java.io.File file = new java.io.File(filename);
454     return file.getAbsolutePath();
455   }
456
457
458  /**
459    * Stream handle for low-level C++ standard output stream.
460    * <p>
461    * A few libSBML methods accept an argument for indicating where to send
462    * text string output.  An example is the {@link
463    * SBMLDocument#printErrors} method.  However, the methods use C++ style
464    * streams and not Java stream objects.  The OStream object class in the
465    * libSBML Java interface provides a wrapper for the underlying C++
466    * streams.  The present object (cout) is a static final variable that
467    * can be used directly from your code.  An example use might be
468    * something like this:
469    * <p>
470    * <div class="fragment"><pre class="fragment">
471    * SBMLDocument document = libsbml.readSBML("somefile.xml");
472    * if (document.getNumErrors() > 0)
473    * {
474    *     document.printErrors(libsbml.cout);
475    *     println("Please correct the above problems first.");
476    *     System.exit(1);
477    * }</div>
478    *
479    * @see #cerr
480    * @see #clog
481    */
482  public final static OStream cout;
483
484
485  /**
486    * Stream handle for low-level C++ standard error stream.
487    * <p>
488    * A few libSBML methods accept an argument for indicating where to send
489    * text string output.  An example is the {@link
490    * SBMLDocument#printErrors} method.  However, the methods use C++ style
491    * streams and not Java stream objects.  The OStream object class in the
492    * libSBML Java interface provides a wrapper for the underlying C++
493    * streams.  The present object (cerr) is a static final variable that
494    * can be used directly from your code.  An example use might be
495    * something like this:
496    * <p>
497    * <div class="fragment"><pre class="fragment">
498    * SBMLDocument document = libsbml.readSBML("somefile.xml");
499    * if (document.getNumErrors() > 0)
500    * {
501    *     document.printErrors(libsbml.cerr);
502    *     println("Please correct the above problems first.");
503    *     System.exit(1);
504    * }</div>
505    * <p>
506    * By default, most operating systems have have their standard error and
507    * logging output streams directed to the console/terminal, and this is
508    * where text messages will be shown.  This can usually be redirected
509    * elsewhere, although how to do this depends on the specific environment
510    * where the program is running.
511    *
512    * @see #cout
513    * @see #clog
514    */
515  public final static OStream cerr;
516
517
518  /**
519    * Stream handle for low-level C++ standard logging stream.
520    * <p>
521    * A few libSBML methods accept an argument for indicating where to send
522    * text string output.  An example is the {@link
523    * SBMLDocument#printErrors} method.  However, the methods use C++ style
524    * streams and not Java stream objects.  The OStream object class in the
525    * libSBML Java interface provides a wrapper for the underlying C++
526    * streams.  The present object (clog) is a static final variable that
527    * can be used directly from your code.  An example use might be
528    * something like this:
529    * <p>
530    * <div class="fragment"><pre class="fragment">
531    * SBMLDocument document = libsbml.readSBML("somefile.xml");
532    * if (document.getNumErrors() > 0)
533    * {
534    *     document.printErrors(libsbml.clog);
535    *     println("Please correct the above problems first.");
536    *     System.exit(1);
537    * }</div>
538    * <p>
539    * By default, most operating systems have have their standard error and
540    * logging output streams directed to the console/terminal, and this is
541    * where text messages will be shown.  This can usually be redirected
542    * elsewhere, although how to do this depends on the specific environment
543    * where the program is running.
544    *
545    * @see #cout
546    * @see #cerr
547    */
548  public final static OStream clog;
549
550  static {
551    cout = new OStream(OStream.COUT); 
552    cerr = new OStream(OStream.CERR); 
553    clog = new OStream(OStream.CLOG); 
554  }
555
556  /**
557   * This private constructor does nothing and never invoked.
558   * The purpose of this constuctor is to hide a default constructor of this 
559   * class in javadoc documentation.
560   */
561  private libsbml() {}
562
563
564  
565/**
566 * Returns the version number of this copy of libSBML as an integer.
567 <p>
568 * @return the libSBML version as an integer; version 1.2.3 becomes 10203.
569 */ public
570 static int getLibSBMLVersion() {
571    return libsbmlJNI.getLibSBMLVersion();
572  }
573
574  
575/**
576 * Returns the version number of this copy of libSBML as a string.
577 <p>
578 * @return the libSBML version as a string; version 1.2.3 becomes
579 * '1.2.3'.
580 <p>
581 * @see #getLibSBMLVersionString()
582 */ public
583 static String getLibSBMLDottedVersion() {
584    return libsbmlJNI.getLibSBMLDottedVersion();
585  }
586
587  
588/**
589 * Returns the version number of this copy of libSBML as a string without
590 * periods.
591 <p>
592 * @return the libSBML version as a string: version 1.2.3 becomes '10203'.
593 <p>
594 * @see #getLibSBMLDottedVersion()
595 */ public
596 static String getLibSBMLVersionString() {
597    return libsbmlJNI.getLibSBMLVersionString();
598  }
599
600  
601/**
602 * Returns an indication whether libSBML has been compiled with
603 * against a specific library. 
604 <p>
605 * @param option the library to test against, this can be one of
606 *        'expat', 'libxml', 'xerces-c', 'bzip2', 'zip'
607 <p>
608 * @return 0 in case the libSBML has not been compiled against 
609 *         that library and non-zero otherwise (for libraries 
610 *         that define an integer version number that number will 
611 *         be returned).
612 <p>
613 * @see #getLibSBMLDependencyVersionOf(String option)
614 */ public
615 static int isLibSBMLCompiledWith(String option) {
616    return libsbmlJNI.isLibSBMLCompiledWith(option);
617  }
618
619  
620/**
621 * Returns the version string for the dependency library used. 
622 <p>
623 * @param option the library for which the version
624 *        should be retrieved, this can be one of
625 *        'expat', 'libxml', 'xerces-c', 'bzip2', 'zip'
626 <p>
627 * @return null in case libSBML has not been compiled against 
628 *         that library and a version string otherwise.
629 <p>
630 * @see #isLibSBMLCompiledWith(String option)
631 */ public
632 static String getLibSBMLDependencyVersionOf(String option) {
633    return libsbmlJNI.getLibSBMLDependencyVersionOf(option);
634  }
635
636  
637/**
638 * This method takes an SBML operation return value and returns a string representing
639 * the code.
640 <p>
641 * @param returnValue the operation return value to convert to a string
642 <p>
643 * @return a human readable name for the given
644 * operation return value .
645 <p>
646 * @note The caller does not own the returned string and is therefore not
647 * allowed to modify it.
648 */ public
649 static String OperationReturnValue_toString(int returnValue) {
650    return libsbmlJNI.OperationReturnValue_toString(returnValue);
651  }
652
653  
654/**
655 * <p>
656 * Reads an SBML document from the given file.
657 <p>
658 * If the file named <code>filename</code> does not exist or its content is not
659 * valid SBML, one or more errors will be logged with the
660 * {@link SBMLDocument}
661 * object returned by this method.  Callers can use the methods on
662 * {@link SBMLDocument} such as
663 * {@link SBMLDocument#getNumErrors()}
664 * and
665 * {@link SBMLDocument#getError(long)}
666 * to get the errors.  The object returned by
667 * {@link SBMLDocument#getError(long)}
668 * is an {@link SBMLError} object, and it has methods to get the error code,
669 * category, and severity level of the problem, as well as a textual
670 * description of the problem.  The possible severity levels range from
671 * informational messages to fatal errors; see the documentation for
672 * {@link SBMLError}
673 * for more information.
674 <p>
675 * If the file <code>filename</code> could not be read, the file-reading error will
676 * appear first.  The error code  can provide a clue about what
677 * happened.  For example, a file might be unreadable (either because it does
678 * not actually exist or because the user does not have the necessary access
679 * privileges to read it) or some sort of file operation error may have been
680 * reported by the underlying operating system.  Callers can check for these
681 * situations using a program fragment such as the following:
682 <p>
683<pre class='fragment'>
684{@link SBMLReader} reader = new {@link SBMLReader}();
685{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
686
687if (doc.getNumErrors() &gt; 0)
688{
689    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
690    {
691        // Handle case of unreadable file here.
692    }
693    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
694    {
695        // Handle case of other file operation error here.
696    }
697    else
698    {
699        // Handle other error cases.
700    }
701}
702</pre>
703<p>
704 * <p>
705 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 
706 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
707 * format and will be automatically decompressed upon reading.
708 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
709 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
710 * (respectively).  Files whose names lack these suffixes will be read
711 * uncompressed.  Note that if the file is in <em>zip</em> format but the
712 * archive contains more than one file, only the first file in the
713 * archive will be read and the rest ignored.
714 <p>
715 * <p>
716 * To read a gzip/zip file, libSBML needs to be configured and linked with the
717 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
718 * time.  It also needs to be linked with the <a target='_blank'
719 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
720 * these are the default configurations for libSBML.)  Errors about unreadable
721 * files will be logged if a compressed filename is given and libSBML was
722 * <em>not</em> linked with the corresponding required library.
723 */ public
724 static SBMLDocument readSBML(String filename) {
725    long cPtr = libsbmlJNI.readSBML(libsbml.getAbsolutePath(filename));
726    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
727  }
728
729  
730/**
731 * <p>
732 * Reads an SBML document from the given file.
733 <p>
734 * If the file named <code>filename</code> does not exist or its content is not
735 * valid SBML, one or more errors will be logged with the
736 * {@link SBMLDocument}
737 * object returned by this method.  Callers can use the methods on
738 * {@link SBMLDocument} such as
739 * {@link SBMLDocument#getNumErrors()}
740 * and
741 * {@link SBMLDocument#getError(long)}
742 * to get the errors.  The object returned by
743 * {@link SBMLDocument#getError(long)}
744 * is an {@link SBMLError} object, and it has methods to get the error code,
745 * category, and severity level of the problem, as well as a textual
746 * description of the problem.  The possible severity levels range from
747 * informational messages to fatal errors; see the documentation for
748 * {@link SBMLError}
749 * for more information.
750 <p>
751 * If the file <code>filename</code> could not be read, the file-reading error will
752 * appear first.  The error code  can provide a clue about what
753 * happened.  For example, a file might be unreadable (either because it does
754 * not actually exist or because the user does not have the necessary access
755 * privileges to read it) or some sort of file operation error may have been
756 * reported by the underlying operating system.  Callers can check for these
757 * situations using a program fragment such as the following:
758 <p>
759<pre class='fragment'>
760{@link SBMLReader} reader = new {@link SBMLReader}();
761{@link SBMLDocument} doc  = reader.readSBMLFromFile(filename);
762
763if (doc.getNumErrors() &gt; 0)
764{
765    if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileUnreadable)
766    {
767        // Handle case of unreadable file here.
768    }
769    else if (doc.getError(0).getErrorId() == libsbmlConstants.XMLFileOperationError)
770    {
771        // Handle case of other file operation error here.
772    }
773    else
774    {
775        // Handle other error cases.
776    }
777}
778</pre>
779<p>
780 * <p>
781 * If the given filename ends with the suffix <code>'.gz'</code> (for example, 
782 * <code>'myfile.xml.gz'</code>), the file is assumed to be compressed in <em>gzip</em>
783 * format and will be automatically decompressed upon reading.
784 * Similarly, if the given filename ends with <code>'.zip'</code> or <code>'.bz2'</code>, the
785 * file is assumed to be compressed in <em>zip</em> or <em>bzip2</em> format
786 * (respectively).  Files whose names lack these suffixes will be read
787 * uncompressed.  Note that if the file is in <em>zip</em> format but the
788 * archive contains more than one file, only the first file in the
789 * archive will be read and the rest ignored.
790 <p>
791 * <p>
792 * To read a gzip/zip file, libSBML needs to be configured and linked with the
793 * <a target='_blank' href='http://www.zlib.net/'>zlib</a> library at compile
794 * time.  It also needs to be linked with the <a target='_blank'
795 * href=''>bzip2</a> library to read files in <em>bzip2</em> format.  (Both of
796 * these are the default configurations for libSBML.)  Errors about unreadable
797 * files will be logged if a compressed filename is given and libSBML was
798 * <em>not</em> linked with the corresponding required library.
799 <p>
800 * @param filename the name or full pathname of the file to be read.
801 <p>
802 * @return a pointer to the {@link SBMLDocument} structure created from the SBML
803 * content in <code>filename</code>.
804 */ public
805 static SBMLDocument readSBMLFromFile(String filename) {
806    long cPtr = libsbmlJNI.readSBMLFromFile(libsbml.getAbsolutePath(filename));
807    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
808  }
809
810  
811/**
812 * <p>
813 * Reads an SBML document from a text string.
814 <p>
815 * This method is flexible with respect to the presence of an XML
816 * declaration at the beginning of the string.  In particular, if the
817 * string in <code>xml</code> does not begin with the XML declaration
818 * <pre class='fragment'>
819&lt;?xml version='1.0' encoding='UTF-8'?&gt;
820</pre>
821 * then this method will automatically prepend the declaration
822 * to <code>xml</code>.
823 <p>
824 * This method will log a fatal error if the content given in the parameter
825 * <code>xml</code> is not in SBML format.  See the method documentation for
826 * {@link SBMLReader#readSBML(String)} for an example of code for
827 * testing the returned error code.
828 <p>
829 * @param xml a string containing a full SBML model
830 <p>
831 * @return a pointer to the {@link SBMLDocument} structure created from the SBML
832 * content in <code>xml</code>.
833 <p>
834 * <p>
835 * @note When using this method to read an {@link SBMLDocument} that uses the SBML
836 * Level&nbsp;3 Hierarchical Model Composition package (comp) the document
837 * location cannot be set automatically. Thus, if the model contains
838 * references to {@link ExternalModelDefinition} objects, it will be necessary to
839 * manually set the document URI location
840 * ({@link SBMLDocument#setLocationURI(String)} in order to facilitate
841 * resolving these models.
842 */ public
843 static SBMLDocument readSBMLFromString(String xml) {
844    long cPtr = libsbmlJNI.readSBMLFromString(xml);
845    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
846  }
847
848  
849/**
850 * Writes the given SBML document <code>d</code> to the file named by <code>filename</code>.
851 * This convenience function is functionally equivalent to:
852 <p>
853 *   SBMLWriter_writeSBML(SBMLWriter_create(), d, filename);
854 <p>
855 * If the given filename ends with the suffix <code>&quot;.gz&quot;</code>
856(for example, <code>&quot;myfile.xml.gz&quot;</code>), libSBML assumes the
857caller wants the file to be written compressed in <em>gzip</em> format.
858Similarly, if the given filename ends with <code>&quot;.zip&quot;</code> or
859<code>&quot;.bz2&quot;</code>, libSBML assumes the caller wants the file to
860be compressed in <em>zip</em> or <em>bzip2</em> format (respectively).
861Files whose names lack these suffixes will be written uncompressed.
862<em>Special considerations for the zip format</em>: If the given filename
863ends with <code>&quot;.zip&quot;</code>, the file placed in the zip archive
864will have the suffix <code>&quot;.xml&quot;</code> or
865<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
866will be named <code>&quot;test.xml&quot;</code> if the given filename is
867<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
868Similarly, the filename in the archive will be
869<code>&quot;test.sbml&quot;</code> if the given filename is
870<code>&quot;test.sbml.zip&quot;</code>.
871
872 <p>
873 * @param d the {@link SBMLDocument} object to be written out in XML format
874 <p>
875 * @param filename a string giving the path to a file where the XML
876 * content is to be written.
877 <p>
878 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be
879 * written.  Some possible reasons for failure include (a) being unable to
880 * open the file, and (b) using a filename that indicates a compressed SBML
881 * file (i.e., a filename ending in <code>&quot;.zip&quot;</code> or
882 * similar) when the compression functionality has not been enabled in
883 * the underlying copy of libSBML.
884 <p>
885 * @see SBMLWriter#hasZlib()
886 * @see SBMLWriter#hasBzip2()
887 */ public
888 static int writeSBML(SBMLDocument d, String filename) {
889    return libsbmlJNI.writeSBML(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename));
890  }
891
892  
893/**
894 * Writes the given SBML document <code>d</code> to an in-memory string and returns a
895 * pointer to it.  The string is owned by the caller and should be freed
896 * (with free()) when no longer needed.  This convenience function is
897 * functionally equivalent to:
898 <p>
899 *   SBMLWriter_writeSBMLToString(SBMLWriter_create(), d);
900 <p>
901 * but does not require the caller to create an {@link SBMLWriter} object first.
902 <p>
903 * @param d an {@link SBMLDocument} object to be written out in XML format
904 <p>
905 * @return the string on success and <code>null</code> if one of the underlying parser
906 * components fail.
907 */ public
908 static String writeSBMLToString(SBMLDocument d) {
909    return libsbmlJNI.writeSBMLToString(SBMLDocument.getCPtr(d), d);
910  }
911
912  
913/**
914 * Writes the given SBML document <code>d</code> to the file <code>filename</code>.
915 * This convenience function is functionally equivalent to:
916 <p>
917 *   SBMLWriter_writeSBMLToFile(SBMLWriter_create(), d, filename);
918 <p>
919 * but that does not require the caller to create an {@link SBMLWriter} object first.
920 <p>
921 * If the given filename ends with the suffix <code>&quot;.gz&quot;</code>
922(for example, <code>&quot;myfile.xml.gz&quot;</code>), libSBML assumes the
923caller wants the file to be written compressed in <em>gzip</em> format.
924Similarly, if the given filename ends with <code>&quot;.zip&quot;</code> or
925<code>&quot;.bz2&quot;</code>, libSBML assumes the caller wants the file to
926be compressed in <em>zip</em> or <em>bzip2</em> format (respectively).
927Files whose names lack these suffixes will be written uncompressed.
928<em>Special considerations for the zip format</em>: If the given filename
929ends with <code>&quot;.zip&quot;</code>, the file placed in the zip archive
930will have the suffix <code>&quot;.xml&quot;</code> or
931<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
932will be named <code>&quot;test.xml&quot;</code> if the given filename is
933<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
934Similarly, the filename in the archive will be
935<code>&quot;test.sbml&quot;</code> if the given filename is
936<code>&quot;test.sbml.zip&quot;</code>.
937
938 <p>
939 * @param d an {@link SBMLDocument} object to be written out in XML format
940 <p>
941 * @param filename a string giving the path to a file where the XML
942 * content is to be written.
943 <p>
944 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be
945 * written.  Some possible reasons for failure include (a) being unable to
946 * open the file, and (b) using a filename that indicates a compressed SBML
947 * file (i.e., a filename ending in <code>&quot;.zip&quot;</code> or
948 * similar) when the compression functionality has not been enabled in
949 * the underlying copy of libSBML.
950 <p>
951 * @see SBMLWriter#hasZlib()
952 * @see SBMLWriter#hasBzip2()
953 */ public
954 static int writeSBMLToFile(SBMLDocument d, String filename) {
955    return libsbmlJNI.writeSBMLToFile(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename));
956  }
957
958  
959/**
960 * This method takes an SBML type code and returns a string representing
961 * the code.
962 <p>
963 * LibSBML attaches an identifying code to every
964 * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
965 * other languages, the set of type codes is stored in an enumeration; in
966 * the Java language interface for libSBML, the type codes are defined as
967 * static integer constants in the interface class {@link
968 * libsbmlConstants}.  The names of the type codes all begin with the
969 * characters <code>SBML_.</code> 
970 <p>
971 * @return a human readable name for the given
972 * SBML type code.
973 <p>
974 * @note The caller does not own the returned string and is therefore not
975 * allowed to modify it.
976 */ public
977 static String SBMLTypeCode_toString(int tc, String pkgName) {
978    return libsbmlJNI.SBMLTypeCode_toString(tc, pkgName);
979  }
980
981  
982/**
983 * Tests for logical equality between two given <code>UNIT_KIND_</code>
984 * code values.
985 <p>
986 * This function behaves exactly like C's <code>==</code> operator, except
987 * for the following two cases:
988 * <ul>
989  * <li>{@link libsbmlConstants#UNIT_KIND_LITER UNIT_KIND_LITER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_LITRE UNIT_KIND_LITRE}
990 * <li>{@link libsbmlConstants#UNIT_KIND_METER UNIT_KIND_METER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_METRE UNIT_KIND_METRE}
991 * </ul>
992 <p>
993 * In the two cases above, C equality comparison would yield <code>false</code>
994 * (because each of the above is a distinct enumeration value), but
995 * this function returns <code>true.</code>
996 <p>
997 * @param uk1 a <code>UNIT_KIND_</code> value 
998 * @param uk2 a second <code>UNIT_KIND_</code> value to compare to <code>uk1</code>
999 <p>
1000 * @return nonzero (for <code>true</code>) if <code>uk1</code> is logically equivalent to 
1001 * <code>uk2</code>, zero (for <code>false</code>) otherwise.
1002 <p>
1003 * @note For more information about the libSBML unit codes, please refer to
1004 * the class documentation for {@link Unit}.
1005 */ public
1006 static int UnitKind_equals(int uk1, int uk2) {
1007    return libsbmlJNI.UnitKind_equals(uk1, uk2);
1008  }
1009
1010  
1011/**
1012 * Converts a text string naming a kind of unit to its corresponding
1013 * libSBML <code>UNIT_KIND_</code> constant/enumeration value.
1014 <p>
1015 * @param name a string, the name of a predefined base unit in SBML
1016 <p>
1017 * @return a value the set of <code>UNIT_KIND_</code> codes
1018 * defined in class {@link libsbmlConstants}, corresponding to the string
1019 * <code>name</code> (determined in a case-insensitive manner).
1020 <p>
1021 * @note For more information about the libSBML unit codes, please refer to
1022 * the class documentation for {@link Unit}.
1023 */ public
1024 static int UnitKind_forName(String name) {
1025    return libsbmlJNI.UnitKind_forName(name);
1026  }
1027
1028  
1029/**
1030 * Converts a unit code to a text string equivalent.
1031 <p>
1032 * @param uk a value from the set of <code>UNIT_KIND_</code> codes
1033 * defined in the class {@link libsbmlConstants}
1034 <p>
1035 * @return the name corresponding to the given unit code.
1036 <p>
1037 * @note For more information about the libSBML unit codes, please refer to
1038 * the class documentation for {@link Unit}.
1039 <p>
1040 * @warning The string returned is a static data value.  The caller does not
1041 * own the returned string and is therefore not allowed to modify it.
1042 */ public
1043 static String UnitKind_toString(int uk) {
1044    return libsbmlJNI.UnitKind_toString(uk);
1045  }
1046
1047  
1048/**
1049 * Predicate for testing whether a given string corresponds to a
1050 * predefined libSBML unit code.
1051 <p>
1052 * @param str a text string naming a base unit defined by SBML
1053 * @param level the Level of SBML
1054 * @param version the Version within the Level of SBML
1055 <p>
1056 * @return nonzero (for <code>true</code>) if string is the name of a valid
1057 * <code>UNIT_KIND_</code> value, zero (for <code>false</code>) otherwise.
1058 <p>
1059 * @note For more information about the libSBML unit codes, please refer to
1060 * the class documentation for {@link Unit}.
1061 */ public
1062 static int UnitKind_isValidUnitKindString(String str, long level, long version) {
1063    return libsbmlJNI.UnitKind_isValidUnitKindString(str, level, version);
1064  }
1065
1066  
1067/**
1068 * This method takes a model qualifier type code and returns a string
1069 * representing the code.
1070 <p>
1071 * This method takes a model qualifier type as argument
1072 * and returns a string name corresponding to that code.  For example,
1073 * passing it the qualifier <code>BQM_IS_DESCRIBED_BY</code> will return
1074 * the string <code>'isDescribedBy'</code>.
1075 <p>
1076 * @param type The  value to
1077 * translate. The value should be a libSBML constant whose
1078 * name begins with <code>BQM_</code>, such as (for example)
1079 * {@link libsbmlConstants#BQM_IS BQM_IS}.
1080 <p>
1081 * @return a human readable qualifier name for the given qualifier type.
1082 <p>
1083 * @note The caller does not own the returned string and is therefore not
1084 * allowed to modify it.
1085 */ public
1086 static String ModelQualifierType_toString(int type) {
1087    return libsbmlJNI.ModelQualifierType_toString(type);
1088  }
1089
1090  
1091/**
1092 * This method takes a biol qualifier type code and returns a string
1093 * representing the code.
1094 <p>
1095 * This method takes a biol qualifier type as argument
1096 * and returns a string name corresponding to that code.  For example,
1097 * passing it the qualifier <code>BQB_HAS_VERSION</code> will return
1098 * the string <code>'hasVersion'</code>.
1099 <p>
1100 * @param type The  value to
1101 * translate. The value should be a constant whose name
1102 * begins with <code>BQB_</code>, such as (for example)
1103 * {@link libsbmlConstants#BQB_IS BQB_IS}.
1104 <p>
1105 * @return a human readable qualifier name for the given type.
1106 <p>
1107 * @note The caller does not own the returned string and is therefore not
1108 * allowed to modify it.
1109 */ public
1110 static String BiolQualifierType_toString(int type) {
1111    return libsbmlJNI.BiolQualifierType_toString(type);
1112  }
1113
1114  
1115/**
1116 * This method takes a a string and returns a model qualifier
1117 * representing the string.
1118 <p>
1119 * This method takes a string as argument and returns a model qualifier type
1120 * corresponding to that string.  For example, passing it the string
1121 * <code>'isDescribedBy'</code> will return the qualifier
1122 * <code>BQM_IS_DESCRIBED_BY</code>.
1123 <p>
1124 * @param s The string to translate to a libSBML constant value representing a model qualifier.
1125 <p>
1126 * @return a libSBML qualifier enumeration value for the given human readable
1127 * qualifier name.
1128 */ public
1129 static int ModelQualifierType_fromString(String s) {
1130    return libsbmlJNI.ModelQualifierType_fromString(s);
1131  }
1132
1133  
1134/**
1135 * This method takes a a string and returns a biol qualifier
1136 * representing the string.
1137 <p>
1138 * This method takes a string as argument and returns a biol qualifier type
1139 * corresponding to that string.  For example, passing it the string
1140 * <code>'hasVersion'</code> will return the qualifier
1141 * <code>BQB_HAS_VERSION</code>.
1142 <p>
1143 * @param s The string to translate to a libSBML constant value representing a biological qualifier.
1144 <p>
1145 * @return a libSBML qualifier enumeration value for the given human readable
1146 * qualifier name.
1147 */ public
1148 static int BiolQualifierType_fromString(String s) {
1149    return libsbmlJNI.BiolQualifierType_fromString(s);
1150  }
1151
1152  
1153/** * @internal */ public
1154 static boolean representsNumber(int type) {
1155    return libsbmlJNI.representsNumber(type);
1156  }
1157
1158  
1159/** * @internal */ public
1160 static boolean representsFunction(int type, ASTBasePlugin plugin) {
1161    return libsbmlJNI.representsFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
1162  }
1163
1164  
1165/** * @internal */ public
1166 static boolean representsFunction(int type) {
1167    return libsbmlJNI.representsFunction__SWIG_1(type);
1168  }
1169
1170  
1171/** * @internal */ public
1172 static boolean representsUnaryFunction(int type, ASTBasePlugin plugin) {
1173    return libsbmlJNI.representsUnaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
1174  }
1175
1176  
1177/** * @internal */ public
1178 static boolean representsUnaryFunction(int type) {
1179    return libsbmlJNI.representsUnaryFunction__SWIG_1(type);
1180  }
1181
1182  
1183/** * @internal */ public
1184 static boolean representsBinaryFunction(int type, ASTBasePlugin plugin) {
1185    return libsbmlJNI.representsBinaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
1186  }
1187
1188  
1189/** * @internal */ public
1190 static boolean representsBinaryFunction(int type) {
1191    return libsbmlJNI.representsBinaryFunction__SWIG_1(type);
1192  }
1193
1194  
1195/** * @internal */ public
1196 static boolean representsNaryFunction(int type, ASTBasePlugin plugin) {
1197    return libsbmlJNI.representsNaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
1198  }
1199
1200  
1201/** * @internal */ public
1202 static boolean representsNaryFunction(int type) {
1203    return libsbmlJNI.representsNaryFunction__SWIG_1(type);
1204  }
1205
1206  
1207/** * @internal */ public
1208 static boolean representsQualifier(int type, ASTBasePlugin plugin) {
1209    return libsbmlJNI.representsQualifier__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
1210  }
1211
1212  
1213/** * @internal */ public
1214 static boolean representsQualifier(int type) {
1215    return libsbmlJNI.representsQualifier__SWIG_1(type);
1216  }
1217
1218  
1219/** * @internal */ public
1220 static boolean representsFunctionRequiringAtLeastTwoArguments(int type) {
1221    return libsbmlJNI.representsFunctionRequiringAtLeastTwoArguments(type);
1222  }
1223
1224  
1225/** * @internal */ public
1226 static int getCoreTypeFromName(String name) {
1227    return libsbmlJNI.getCoreTypeFromName(name);
1228  }
1229
1230  
1231/** * @internal */ public
1232 static String getNameFromCoreType(int type) {
1233    return libsbmlJNI.getNameFromCoreType(type);
1234  }
1235
1236  
1237/** * @internal */ public
1238 static boolean isCoreTopLevelMathMLFunctionNodeTag(String name) {
1239    return libsbmlJNI.isCoreTopLevelMathMLFunctionNodeTag(name);
1240  }
1241
1242  
1243/** * @internal */ public
1244 static boolean isCoreTopLevelMathMLNumberNodeTag(String name) {
1245    return libsbmlJNI.isCoreTopLevelMathMLNumberNodeTag(name);
1246  }
1247
1248  
1249/**
1250 * Reads the MathML from the given XML string, constructs a corresponding
1251 * abstract syntax tree, and returns a pointer to the root of the tree.
1252 <p>
1253 * @param xml a string containing a full MathML expression
1254 <p>
1255 * @return the root of an AST corresponding to the given mathematical
1256 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code>
1257 * or invalid.
1258 */ public
1259 static ASTNode readMathMLFromString(String xml) {
1260    long cPtr = libsbmlJNI.readMathMLFromString(xml);
1261    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
1262  }
1263
1264  
1265/**
1266 * Reads the MathML from the given XML string, constructs a corresponding
1267 * abstract syntax tree, and returns a pointer to the root of the tree.
1268 <p>
1269 * @param xml a string containing a full MathML expression
1270 * @param xmlns an {@link XMLNamespaces}
1271 * object containing namespaces that are considered active during the
1272 * read. (For example, an SBML Level&nbsp;3 package namespace.)
1273 <p>
1274 * @return the root of an AST corresponding to the given mathematical
1275 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code>
1276 * or invalid.
1277 */ public
1278 static ASTNode readMathMLFromStringWithNamespaces(String xml, XMLNamespaces xmlns) {
1279    long cPtr = libsbmlJNI.readMathMLFromStringWithNamespaces(xml, XMLNamespaces.getCPtr(xmlns), xmlns);
1280    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
1281  }
1282
1283  
1284/**
1285 * Writes the given AST node (and its children) to a string as MathML, and
1286 * returns the string.
1287 <p>
1288 * @param node the root of an AST to write out to the stream.
1289 <p>
1290 * @return a string containing the written-out MathML representation
1291 * of the given AST.
1292 <p>
1293 * @note The string is owned by the caller and should be freed (with
1294 * free()) when no longer needed.  <code>null</code> is returned if the given
1295 * argument is <code>null.</code>
1296 */ public
1297 static String writeMathMLToString(ASTNode node) {
1298    return libsbmlJNI.writeMathMLToString(ASTNode.getCPtr(node), node);
1299  }
1300
1301  
1302/**
1303 * Parses a text string as a mathematical formula and returns an AST
1304 * representation of it.
1305 <p>
1306 * <p>
1307 * The text-string form of mathematical formulas produced by
1308 * <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a> and read by
1309 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> use a simple C-inspired infix
1310 * notation taken from SBML Level&nbsp;1.  A formula in this text-string form
1311 * therefore can be handed to a program that understands SBML Level&nbsp;1
1312 * mathematical expressions, or used as part of a formula translation system.
1313 * The syntax is described in detail in the documentation for {@link ASTNode}.  The
1314 * following are illustrative examples of formulas expressed using this syntax:
1315 * <pre class='fragment'>
13160.10 * k4^2
1317</pre>
1318<pre class='fragment'>
1319(vm * s1)/(km + s1)
1320</pre>
1321 <p>
1322 * Note that this facility is provided as a convenience by libSBML&mdash;the
1323 * MathML standard does not actually define a 'string-form' equivalent to
1324 * MathML expression trees, so the choice of formula syntax is somewhat
1325 * arbitrary.  The approach taken by libSBML is to use the syntax defined by
1326 * SBML Level&nbsp;1 (which in fact used a text-string representation of
1327 * formulas and not MathML).  This formula syntax is based mostly on C
1328 * programming syntax, and may contain operators, function calls, symbols,
1329 * and white space characters.  The following table provides the precedence
1330 * rules for the different entities that may appear in formula strings.
1331 <p>
1332 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em">
1333 <tr style="background: lightgray; font-size: 14px;">
1334     <th align="left">Token</th>
1335     <th align="left">Operation</th>
1336     <th align="left">Class</th>
1337     <th>Precedence</th>
1338     <th align="left">Associates</th>
1339 </tr>
1340<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
1341<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
1342<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">6</td><td>left</td></tr>
1343<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr>
1344<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr>
1345<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1346<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1347<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1348<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1349<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
1350<caption class="top-caption">A table of the expression operators and their precedence in the
1351text-string format for mathematical expressions used by SBML_parseFormula().
1352</caption>
1353</table>
1354
1355
1356 <p>
1357 * In the table above, <em>operand</em> implies the construct is an operand, 
1358 * <em>prefix</em> implies the operation is applied to the following arguments, 
1359 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
1360 * two arguments.  The values in the <b>Precedence</b> column show how the
1361 * order of different types of operation are determined.  For example, the
1362 * expression <code>a * b + c</code> is evaluated as <code>(a * b) +
1363 * c</code> because the @c * operator has higher precedence.  The
1364 * <b>Associates</b> column shows how the order of similar precedence
1365 * operations is determined; for example, <code>a - b + c</code> is
1366 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code>
1367 * operators are left-associative.
1368 <p>
1369 * The function call syntax consists of a function name, followed by optional
1370 * white space, followed by an opening parenthesis token, followed by a
1371 * sequence of zero or more arguments separated by commas (with each comma
1372 * optionally preceded and/or followed by zero or more white space
1373 * characters, followed by a closing parenthesis token.  The function name
1374 * must be chosen from one of the pre-defined functions in SBML or a
1375 * user-defined function in the model.  The following table lists the names
1376 * of certain common mathematical functions; this table corresponds to
1377 * Table&nbsp;6 in the <a target='_blank' href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML Level&nbsp;1 Version&nbsp;2 specification</a>:
1378 <p>
1379 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
1380 <tr>
1381     <th align="left" width="60">Name</th>
1382     <th align="left" width="35">Args</th>
1383     <th align="left">Formula or meaning</th>
1384     <th align="left" width="90">Argument Constraints</th>
1385     <th align="left" width="90">Result constraints</th>
1386 </tr>
1387<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr>
1388<tr><td><code>acos</code></td><td><em>x</em></td><td>arc cosine of <em>x</em> in radians</td><td>-1.0 &le; <em>x</em> &le; 1.0</td><td>0 &le; <em>acos(x)</em> &le; &pi;</td></tr>
1389<tr><td><code>asin</code></td><td><em>x</em></td><td>arc sine of <em>x</em> in radians</td><td>-1.0 &le; <em>x</em> &le; 1.0</td><td>0 &le; <em>asin(x)</em> &le; &pi;</td></tr>
1390<tr><td><code>atan</code></td><td><em>x</em></td><td>arc tangent of <em>x</em> in radians</td><td></td><td>0 &le; <em>atan(x)</em> &le; &pi;</td></tr>
1391<tr><td><code>ceil</code></td><td><em>x</em></td><td>smallest number not less than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr>
1392<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr>
1393<tr><td><code>exp</code></td><td><em>x</em></td><td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm</td><td></td><td></td></tr>
1394<tr><td><code>floor</code></td><td><em>x</em></td><td>the largest number not greater than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr>
1395<tr><td><code>log</code></td><td><em>x</em></td><td>natural logarithm of <em>x</em></td><td><em>x</em> &gt; 0</td><td></td></tr>
1396<tr><td><code>log10</code></td><td><em>x</em></td><td>base 10 logarithm of <em>x</em></td><td><em>x</em> &gt; 0</td><td></td></tr>
1397<tr><td><code>pow</code></td><td><em>x, y</em></td><td><em>x</em><sup><em> y</em></sup></td><td></td><td></td></tr>
1398<tr><td><code>sqr</code></td><td><em>x</em></td><td><em>x</em><sup><em>2</em></sup></td><td></td><td></td></tr>
1399<tr><td><code>sqrt</code></td><td><em>x</em></td><td>&radic;<em>x</em></td><td><em>x</em> &gt; 0</td><td><em>sqrt(x)</em> &ge; 0</td></tr>
1400<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr>
1401<tr><td><code>tan</code></td><td><em>x</em></td><td>tangent of <em>x</em></td><td>x &ne; n*&pi;/2, for odd integer <em>n</em></td><td></td></tr>
1402<caption class="bottom-caption">The names of mathematical functions defined in the SBML
1403Level&nbsp;1 Version&nbsp;2 text-string formula syntax.</caption>
1404</table>
1405
1406
1407 <p>
1408 * @warning <span class='warning'>There are differences between the symbols
1409 * used to represent the common mathematical functions and the corresponding
1410 * MathML token names.  This is a potential source of incompatibilities.
1411 * Note in particular that in this text-string syntax, <code>log(x)</code>
1412 * represents the natural logarithm, whereas in MathML, the natural logarithm
1413 * is <code>&lt;ln/&gt;</code>.  Application writers are urged to be careful
1414 * when translating between text forms and MathML forms, especially if they
1415 * provide a direct text-string input facility to users of their software
1416 * systems.</span>
1417 <p>
1418 * @param formula the text-string formula expression to be parsed
1419 <p>
1420 * @return the root node of the AST corresponding to the <code>formula</code>, or 
1421 * <code>null</code> if an error occurred in parsing the formula
1422 <p>
1423 * 
1424 * <p>
1425 * @note
1426 * Callers using SBML Level&nbsp;3 are encouraged to use the facilities
1427 * provided by libSBML's newer and more powerful Level&nbsp;3-oriented
1428 * formula parser and formatter.  The entry points to this second system are
1429 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and
1430 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>.  The Level&nbsp;1-oriented
1431 * system (i.e., what is provided by <a href='libsbml.html#formulaToString(java.lang.String)'><code>libsbml.formulaToString(String)</code></a>
1432 * and <a href='libsbml.html#parseFormula(org.sbml.libsbml.ASTNode)'><code>libsbml.parseFormula(ASTNode)</code></a>) is provided
1433 * untouched for backwards compatibility.
1434 <p>
1435 * <p>
1436 * @note We urge developers to keep in mind that the text-string formula
1437 * syntax is specific to libSBML.  <em>Neither MathML nor SBML define a
1438 * text-string format for mathematical formulas.</em> LibSBML's particular
1439 * syntax should not be considered to be a canonical or standard
1440 * general-purpose mathematical expression syntax.  LibSBML provides methods
1441 * for parsing and transforming text-string math formulas back and forth from
1442 * AST structures for the convenience of calling applications, but it is
1443 * important to keep the system's limitations in mind.
1444 <p>
1445   * @see <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>
1446 * @see <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
1447 * @see <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>
1448 * @see <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
1449 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
1450 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
1451 * @see L3ParserSettings
1452 */ public
1453 static ASTNode parseFormula(String formula) {
1454    long cPtr = libsbmlJNI.parseFormula(formula);
1455    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
1456  }
1457
1458  
1459/**
1460 * Converts an AST to a text string representation of a formula using an
1461 * extended syntax.
1462 <p>
1463 * <p>
1464 * The text-string form of mathematical formulas read by the function
1465 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and written by the function
1466 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a> uses an expanded version of
1467 * the syntax read and written by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
1468 * and <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>, respectively.  The
1469 * latter two libSBML functions were originally developed to support
1470 * conversion between SBML Levels&nbsp;1 and&nbsp;2, and were focused on the
1471 * syntax of mathematical formulas used in SBML Level&nbsp;1.  With time, and
1472 * the use of MathML in SBML Levels&nbsp;2 and&nbsp;3, it became clear that
1473 * supporting Level&nbsp;2 and&nbsp;3's expanded mathematical syntax would be
1474 * useful for software developers.  To maintain backwards compatibility for
1475 * libSBML users, the original <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
1476 * and <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> have been left untouched,
1477 * and instead, the new functionality is provided in the form of
1478 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and
1479 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>.
1480 <p>
1481 * The following lists the main differences in the formula syntax supported by
1482 * the 'Level 3' or L3 versions of the formula parsers and formatters,
1483 * compared to what is supported by the Level&nbsp;1-oriented
1484 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> and
1485 * <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>:
1486 <p>
1487 * <ul>
1488 * <li> Units may be asociated with bare numbers, using the following syntax:
1489 * <div style='margin: 10px auto 10px 25px; display: block'>
1490 * <span class='code' style='background-color: #d0d0ee'>number</span>
1491 * <span class='code' style='background-color: #edd'>unit</span>
1492 * </div>
1493 * The <span class='code' style='background-color: #d0d0ee'>number</span>
1494 * may be in any form (an integer, real, or rational
1495 * number), and the
1496 * <span class='code' style='background-color: #edd'>unit</span>
1497 * must conform to the syntax of an SBML identifier (technically, the
1498 * type defined as <code>SId</code> in the SBML specifications).  The whitespace between
1499 * <span class='code' style='background-color: #d0d0ee'>number</span>
1500 * and <span class='code' style='background-color: #edd'>unit</span>
1501 * is optional.
1502 <p>
1503 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be
1504 * used.
1505 <p>
1506 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and will
1507 * produce a <code>&lt;piecewise&gt;</code> function in the corresponding
1508 * MathML output.
1509 <p>
1510 * <li> All inverse trigonometric functions may be defined in the infix either
1511 * using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both <code>arccsc</code>
1512 * and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> as defined in
1513 * MathML&nbsp;2.0.  (Many functions in the simpler SBML Level&nbsp;1
1514 * oriented parser implemented by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
1515 * are defined this way as well, but not all.)
1516 <p>
1517 * <li> The following expression is parsed as a rational number instead of
1518 * as a numerical division:
1519 * <pre style='display: block; margin-left: 25px'>
1520 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre>
1521 * <strong>Spaces are not allowed</strong> in this construct; in other words,
1522 * &quot;<code>(3 / 4)</code>&quot; (with whitespace between the numbers and
1523 * the operator) will be parsed into the MathML <code>&lt;divide&gt;</code>
1524 * construct rather than a rational number.  You can, however, assign units to a
1525 * rational number as a whole; here is an example: &quot;<code>(3/4) ml</code>&quot;.
1526 * (In the case of division rather than a rational number, units are not interpreted
1527 * in this way.)
1528 <p>
1529 * <li> Various parser and formatter behaviors may be altered through the use
1530 * of a {@link L3ParserSettings} object in conjunction with the functions
1531 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
1532 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
1533 * The settings available include the following:
1534 * <ul style='list-style-type: circle'>
1535 *
1536 * </ul> <p>
1537 * <li style='margin-bottom: 0.5em'> The function <code>log</code> with a single
1538 * argument (&quot;<code>log(x)</code>&quot;) can be parsed as
1539 * <code>log10(x)</code>, <code>ln(x)</code>, or treated as an error, as
1540 * desired.
1541 <p>
1542 * <li style='margin-bottom: 0.5em'> Unary minus signs can be collapsed or
1543 * preserved; that is, sequential pairs of unary minuses (e.g., &quot;<code>-
1544 * -3</code>&quot;) can be removed from the input entirely and single unary
1545 * minuses can be incorporated into the number node, or all minuses can be
1546 * preserved in the AST node structure.
1547 <p>
1548 * <li style='margin-bottom: 0.5em'> Parsing of units embedded in the input
1549 * string can be turned on and off.
1550 <p>
1551 * <li style='margin-bottom: 0.5em'> The string <code>avogadro</code> can be parsed as
1552 * a MathML <em>csymbol</em> or as an identifier.
1553 <p>
1554 * <li style='margin-bottom: 0.5em'> A {@link Model} object may optionally be
1555 * provided to the parser using the variant function call
1556 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
1557 * stored in a {@link L3ParserSettings} object passed to the variant function
1558 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  When a {@link Model} object is provided, identifiers
1559 * (values of type <code>SId</code>) from that model are used in preference to
1560 * pre-defined MathML definitions for both symbols and functions.
1561 * More precisely:
1562 * <ul style='list-style-type: square'>
1563 <p>
1564 * <li style='margin-bottom: 0.5em'> <em>In the case of symbols</em>: the
1565 * {@link Model} entities whose identifiers will shadow identical symbols in the
1566 * mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter}, {@link Reaction}, and
1567 * {@link SpeciesReference}.  For instance, if the parser is given a {@link Model} containing
1568 * a {@link Species} with the identifier &quot;<code>pi</code>&quot;, and the formula
1569 * to be parsed is &quot;<code>3*pi</code>&quot;, the MathML produced will
1570 * contain the construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of
1571 * the construct <code>&lt;pi/&gt;</code>.
1572 <p>
1573 * <li style='margin-bottom: 0.5em'> <em>In the case of user-defined
1574 * functions</em>: when a {@link Model} object is provided, <code>SId</code> values of
1575 * user-defined functions present in the model will be used preferentially
1576 * over pre-defined MathML functions.  For example, if the passed-in {@link Model}
1577 * contains a {@link FunctionDefinition} object with the identifier
1578 * &quot;<code>sin</code>&quot;, that function will be used instead of the
1579 * predefined MathML function <code>&lt;sin/&gt;</code>.
1580 * </ul>
1581 <p>
1582 * <li style='margin-bottom: 0.5em'> An {@link SBMLNamespaces} object may optionally
1583 * be provided to identify SBML Level&nbsp;3 packages that extend the
1584 * syntax understood by the formula parser.  When the namespaces are provided,
1585 * the parser will interpret possible additional syntax defined by the libSBML
1586 * plug-ins implementing the SBML Level&nbsp;3 packages; for example, it may
1587 * understand vector/array extensions introduced by the SBML Level&nbsp;3 
1588 * <em>Arrays</em> package.
1589 * </ul>
1590 <p>
1591 * These configuration settings cannot be changed directly using the basic
1592 * parser and formatter functions, but <em>can</em> be changed on a per-call basis
1593 * by using the alternative functions <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
1594 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>.
1595 <p>
1596 * Neither SBML nor the MathML standard define a 'string-form' equivalent to
1597 * MathML expressions.  The approach taken by libSBML is to start with the
1598 * formula syntax defined by SBML Level&nbsp;1 (which in fact used a custom
1599 * text-string representation of formulas, and not MathML), and expand it to
1600 * include the functionality described above.  This formula syntax is based
1601 * mostly on C programming syntax, and may contain operators, function calls,
1602 * symbols, and white space characters.  The following table provides the
1603 * precedence rules for the different entities that may appear in formula
1604 * strings.
1605 <p>
1606 * <table border="0" width="95%"
1607       class="centered text-table normal-font alt-row-colors"
1608       style="padding-bottom: 0.5em">
1609 <tr style="background: lightgray; font-size: 14px;">
1610     <th align="left">Token</th>
1611     <th align="left">Operation</th>
1612     <th align="left">Class</th>
1613     <th>Precedence</th>
1614     <th align="left">Associates</th>
1615 </tr>
1616<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
1617<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
1618<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">8</td><td>left</td></tr>
1619<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">7</td><td>left</td></tr>
1620<tr><td><code>-, !</code></td><td>negation and boolean 'not'</td><td>unary</td><td align="center">6</td><td>right</td></tr>
1621<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align="center">5</td><td>left</td></tr>
1622<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align="center">4</td><td>left</td></tr>
1623<tr><td><code>==, &lt;, &gt;, &lt=, &gt=, !=</code></td><td>boolean equality, inequality, and comparison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1624<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1625<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
1626
1627<caption class="top-caption">Expression operators and their precedence in the
1628"Level&nbsp;3" text-string format for mathematical expressions.
1629</caption>
1630</table>
1631
1632
1633 <p>
1634 * In the table above, <em>operand</em> implies the construct is an operand, 
1635 * <em>prefix</em> implies the operation is applied to the following arguments, 
1636 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
1637 * two arguments.  The values in the <b>Precedence</b> column show how the
1638 * order of different types of operation are determined.  For example, the
1639 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code>
1640 * because the @c * operator has higher precedence.  The
1641 * <b>Associates</b> column shows how the order of similar precedence
1642 * operations is determined; for example, <code>a && b || c</code> is
1643 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code>
1644 * operators are left-associative and have the same precedence.
1645 <p>
1646 * The function call syntax consists of a function name, followed by optional
1647 * white space, followed by an opening parenthesis token, followed by a
1648 * sequence of zero or more arguments separated by commas (with each comma
1649 * optionally preceded and/or followed by zero or more white space
1650 * characters), followed by a closing parenthesis token.  The function name
1651 * must be chosen from one of the pre-defined functions in SBML or a
1652 * user-defined function in the model.  The following table lists the names
1653 * of certain common mathematical functions; this table corresponds to
1654 * Table&nbsp;6 in the <a target='_blank'
1655 * href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML
1656 * Level&nbsp;1 Version&nbsp;2 specification</a> with additions based on the
1657 * functions added in SBML Level 2 and Level 3:
1658 <p>
1659 * <table border="0" width="95%" 
1660       class="centered text-table normal-font alt-row-colors">
1661 <tr>
1662     <th align="left" width="60">Name</th>
1663     <th align="left" width="75">Argument(s)</th>
1664     <th align="left">Formula or meaning</th>
1665     <th align="left" width="90">Argument Constraints</th>
1666     <th align="left" width="90">Result constraints</th>
1667 </tr>
1668<tr><td><code>abs</code></td>   
1669    <td><em>x</em></td> 
1670    <td>Absolute value of <em>x</em>.</td>
1671    <td></td>
1672    <td></td>
1673</tr>
1674<tr><td><code>acos</code>, <code>arccos</code></td>
1675    <td><em>x</em></td>
1676    <td>Arccosine of <em>x</em> in radians.</td>
1677    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
1678    <td>0 &le; <em>acos(x)</em> &le; &pi;</td>
1679</tr>
1680<tr><td><code>acosh</code>, <code>arccosh</code></td>
1681    <td><em>x</em></td>
1682    <td>Hyperbolic arccosine of <em>x</em> in radians.</td>
1683    <td></td>
1684    <td></td>
1685</tr>
1686<tr><td><code>acot</code>, <code>arccot</code></td>
1687    <td><em>x</em></td>
1688    <td>Arccotangent of <em>x</em> in radians.</td>
1689    <td></td>
1690    <td></td>
1691</tr>
1692<tr><td><code>acoth</code>, <code>arccoth</code></td>
1693    <td><em>x</em></td>
1694    <td>Hyperbolic arccotangent of <em>x</em> in radians.</td>
1695    <td></td>
1696    <td></td>
1697</tr>
1698<tr><td><code>acsc</code>, <code>arccsc</code></td>
1699    <td><em>x</em></td>
1700    <td>Arccosecant of <em>x</em> in radians.</td>
1701    <td></td>
1702    <td></td>
1703</tr>
1704<tr><td><code>acsch</code>, <code>arccsch</code></td>
1705    <td><em>x</em></td>
1706    <td>Hyperbolic arccosecant of <em>x</em> in radians.</td>
1707    <td></td>
1708    <td></td>
1709</tr>
1710<tr><td><code>asec</code>, <code>arcsec</code></td>
1711    <td><em>x</em></td>
1712    <td>Arcsecant of <em>x</em> in radians.</td>
1713    <td></td>
1714    <td></td>
1715</tr>
1716<tr><td><code>asech</code>, <code>arcsech</code></td>
1717    <td><em>x</em></td>
1718    <td>Hyperbolic arcsecant of <em>x</em> in radians.</td>
1719    <td></td>
1720    <td></td>
1721</tr>
1722<tr><td><code>asin</code>, <code>arcsin</code></td>
1723    <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td>
1724    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
1725    <td>0 &le; <em>asin(x)</em> &le; &pi;</td>
1726</tr>
1727<tr><td><code>atan</code>, <code>arctan</code></td>
1728    <td><em>x</em></td>
1729    <td>Arctangent of <em>x</em> in radians.</td>
1730    <td></td>
1731    <td>0 &le; <em>atan(x)</em> &le; &pi;</td>
1732</tr>
1733<tr><td><code>atanh</code>, <code>arctanh</code></td>
1734    <td><em>x</em></td>
1735    <td>Hyperbolic arctangent of <em>x</em> in radians.</td>
1736    <td></td>
1737    <td></td>
1738</tr>
1739<tr><td><code>ceil</code>, <code>ceiling</code></td>
1740    <td><em>x</em></td>
1741    <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td>
1742    <td></td>
1743    <td></td>
1744</tr>
1745<tr><td><code>cos</code></td>
1746    <td><em>x</em></td>
1747    <td>Cosine of <em>x</em></td>
1748    <td></td>
1749    <td></td>
1750</tr>
1751<tr><td><code>cosh</code></td>
1752    <td><em>x</em></td>
1753    <td>Hyperbolic cosine of <em>x</em>.</td>
1754    <td></td>
1755    <td></td>
1756</tr>
1757<tr><td><code>cot</code></td>
1758    <td><em>x</em></td>
1759    <td>Cotangent of <em>x</em>.</td>
1760    <td></td>
1761    <td></td>
1762</tr>
1763<tr><td><code>coth</code></td>
1764    <td><em>x</em></td>
1765    <td>Hyperbolic cotangent of <em>x</em>.</td>
1766    <td></td>
1767    <td></td>
1768</tr>
1769<tr><td><code>csc</code></td>
1770    <td><em>x</em></td>
1771    <td>Cosecant of <em>x</em>.</td>
1772    <td></td>
1773    <td></td>
1774</tr>
1775<tr><td><code>csch</code></td>
1776    <td><em>x</em></td>
1777    <td>Hyperbolic cosecant of <em>x</em>.</td>
1778    <td></td>
1779    <td></td>
1780</tr>
1781<tr><td><code>delay</code></td>
1782    <td><em>x, y</em></td>
1783    <td>The value of <em>x</em> at <em>y</em> time units in the past.</td>
1784    <td></td>
1785    <td></td>
1786</tr>
1787<tr><td><code>factorial</code></td>
1788    <td><em>n</em></td>
1789    <td>The factorial of <em>n</em>. Factorials are defined by <em>n! = n*(n&ndash;1)* ... * 1</em>.</td>
1790    <td><em>n</em> must be an integer.</td>
1791    <td></td>
1792</tr>
1793<tr><td><code>exp</code></td>
1794    <td><em>x</em></td>
1795    <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td>
1796    <td></td>
1797    <td></td>
1798</tr>
1799<tr><td><code>floor</code></td>
1800    <td><em>x</em></td>
1801    <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td>
1802    <td></td>
1803    <td></td>
1804</tr>
1805<tr><td><code>ln</code></td>
1806    <td><em>x</em></td>
1807    <td>Natural logarithm of <em>x</em>.</td>
1808    <td><em>x</em> &gt; 0</td>
1809    <td></td>
1810</tr>
1811<tr><td><code>log</code></td>
1812    <td><em>x</em></td>
1813    <td>By default, the base 10 logarithm of <em>x</em>, but can be set to be the natural logarithm of <em>x</em>, or to be an illegal construct.</td>
1814    <td><em>x</em> &gt; 0</td>
1815    <td></td>
1816</tr>
1817<tr><td><code>log</code></td>
1818    <td><em>x, y</em></td>
1819    <td>The base <em>x</em> logarithm of <em>y</em>.</td>
1820    <td><em>y</em> &gt; 0</td>
1821    <td></td>
1822</tr>
1823<tr><td><code>log10</code></td>
1824    <td><em>x</em></td>
1825    <td>Base 10 logarithm of <em>x</em>.</td>
1826    <td><em>x</em> &gt; 0</td>
1827    <td></td>
1828</tr>
1829<tr><td><code>piecewise</code></td>
1830    <td><em>x1, y1, [x2, y2,] [...] [z]</em></td>
1831    <td>A piecewise function: if (<em>y1</em>), <em>x1</em>.  Otherwise, if (<em>y2</em>), <em>x2</em>, etc.  Otherwise, z. </td>
1832    <td><em>y1, y2, y3 [etc]</em> must be boolean</td>
1833    <td></td>
1834</tr>
1835<tr><td><code>pow</code>, <code>power</code> </td>
1836    <td><em>x, y</em></td>
1837    <td><em>x</em><sup><em> y</em></sup>.</td>
1838    <td></td>
1839    <td></td>
1840</tr>
1841<tr><td><code>root</code></td>
1842    <td><em>b, x</em></td>
1843    <td>The root base <em>b</em> of <em>x</em>.</td>
1844    <td></td>
1845    <td></td>
1846</tr>
1847<tr><td><code>sec</code></td>
1848    <td><em>x</em></td>
1849    <td>Secant of <em>x</em>.</td>
1850    <td></td>
1851    <td></td>
1852</tr>
1853<tr><td><code>sech</code></td>
1854    <td><em>x</em></td>
1855    <td>Hyperbolic secant of <em>x</em>.</td>
1856    <td></td>
1857    <td></td>
1858</tr>
1859<tr><td><code>sqr</code></td>
1860    <td><em>x</em></td>
1861    <td><em>x</em><sup><em>2</em></sup>.</td>
1862    <td></td>
1863    <td></td>
1864</tr>
1865<tr><td><code>sqrt</code></td>
1866    <td><em>x</em></td>
1867    <td>&radic;<em>x</em>.</td>
1868    <td><em>x</em> &gt; 0</td>
1869    <td><em>sqrt(x)</em> &ge; 0</td>
1870</tr>
1871<tr><td><code>sin</code></td>
1872    <td><em>x</em></td>
1873    <td>Sine of <em>x</em>.</td>
1874    <td></td>
1875    <td></td>
1876</tr>
1877<tr><td><code>sinh</code></td>
1878    <td><em>x</em></td>
1879    <td>Hyperbolic sine of <em>x</em>.</td>
1880    <td></td>
1881    <td></td>
1882</tr>
1883<tr><td><code>tan</code></td>
1884    <td><em>x</em></td>
1885    <td>Tangent of <em>x</em>.</td>
1886    <td>x &ne; n*&pi;/2, for odd integer <em>n</em></td>
1887    <td></td>
1888</tr>
1889<tr><td><code>tanh</code></td>
1890    <td><em>x</em></td>
1891    <td>Hyperbolic tangent of <em>x</em>.</td>
1892    <td></td>
1893    <td></td>
1894</tr>
1895<tr><td><code>and</code></td>
1896    <td><em>x, y, z...</em></td>
1897    <td>Boolean <em>and(x, y, z...)</em>: returns <code>true</code> if all of its arguments are true.  Note that <code>and</code> is an n-ary function, taking 0 or more arguments, and that <code>and()</code> returns <code>true</code>.</td>
1898    <td>All arguments must be boolean</td>
1899    <td></td>
1900</tr>
1901<tr><td><code>not</code></td>
1902    <td><em>x</em></td>
1903    <td>Boolean <em>not(x)</em></td>
1904    <td><em>x</em> must be boolean</td>
1905    <td></td>
1906</tr>
1907<tr><td><code>or</code></td>
1908    <td><em>x, y, z...</em></td>
1909    <td>Boolean <em>or(x, y, z...)</em>: returns <code>true</code> if at least one of its arguments is true.  Note that <code>or</code> is an n-ary function, taking 0 or more arguments, and that <code>or()</code> returns <code>false</code>.</td>
1910    <td>All arguments must be boolean</td>
1911    <td></td>
1912</tr>
1913<tr><td><code>xor</code></td>
1914    <td><em>x, y, z...</em></td>
1915    <td>Boolean <em>xor(x, y, z...)</em>: returns <code>true</code> if an odd number of its arguments is true.  Note that <code>xor</code> is an n-ary function, taking 0 or more arguments, and that <code>xor()</code> returns <code>false</code>.</td>
1916    <td>All arguments must be boolean</td>
1917    <td></td>
1918</tr>
1919<tr><td><code>eq</code></td>
1920    <td><em>x, y, z...</em></td>
1921    <td>Boolean <em>eq(x, y, z...)</em>: returns <code>true</code> if all arguments are equal.  Note that <code>eq</code> is an n-ary function, but must take 2 or more arguments.</td>
1922    <td></td>
1923    <td></td>
1924</tr>
1925<tr><td><code>geq</code></td>
1926    <td><em>x, y, z...</em></td>
1927    <td>Boolean <em>geq(x, y, z...)</em>: returns <code>true</code> if each argument is greater than or equal to the argument following it.  Note that <code>geq</code> is an n-ary function, but must take 2 or more arguments.</td>
1928    <td></td>
1929    <td></td>
1930</tr>
1931<tr><td><code>gt</code></td>
1932    <td><em>x, y, z...</em></td>
1933    <td>Boolean <em>gt(x, y, z...)</em>: returns <code>true</code> if each argument is greater than the argument following it.  Note that <code>gt</code> is an n-ary function, but must take 2 or more arguments.</td>
1934    <td></td>
1935    <td></td>
1936</tr>
1937<tr><td><code>leq</code></td>
1938    <td><em>x, y, z...</em></td>
1939    <td>Boolean <em>leq(x, y, z...)</em>: returns <code>true</code> if each argument is less than or equal to the argument following it.  Note that <code>leq</code> is an n-ary function, but must take 2 or more arguments.</td>
1940    <td></td>
1941    <td></td>
1942</tr>
1943<tr><td><code>lt</code></td>
1944    <td><em>x, y, z...</em></td>
1945    <td>Boolean <em>lt(x, y, z...)</em>: returns <code>true</code> if each argument is less than the argument following it.  Note that <code>lt</code> is an n-ary function, but must take 2 or more arguments.</td>
1946    <td></td>
1947    <td></td>
1948</tr>
1949<tr><td><code>neq</code></td>
1950    <td><em>x, y</em></td>
1951    <td>Boolean <em>x</em> != <em>y</em>: returns <code>true</code> unless x and y are equal.</td>
1952    <td></td>
1953    <td></td>
1954</tr>
1955<tr><td><code>plus</code></td>
1956    <td><em>x, y, z...</em></td>
1957    <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function.  Note that <code>plus</code> is an n-ary function taking 0 or more arguments, and that <code>plus()</code> returns <code>0</code>.</td>
1958    <td></td>
1959    <td></td>
1960</tr>
1961<tr><td><code>times</code></td>
1962    <td><em>x, y, z...</em></td>
1963    <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function.  Note that <code>times</code> is an n-ary function taking 0 or more arguments, and that <code>times()</code> returns <code>1</code>.</td>
1964    <td></td>
1965    <td></td>
1966</tr>
1967<tr><td><code>minus</code></td>
1968    <td><em>x, y</em></td>
1969    <td><em>x</em> &ndash; <em>y</em>.</td>
1970    <td></td>
1971    <td></td>
1972</tr>
1973<tr><td><code>divide</code></td>
1974    <td><em>x, y</em></td>
1975    <td><em>x</em> / <em>y</em>.</td>
1976    <td></td>
1977    <td></td>
1978</tr>
1979
1980<caption class="top-caption">Mathematical functions defined
1981in the "Level&nbsp;3" text-string formula syntax.</caption>
1982
1983</table>
1984
1985
1986 <p>
1987 * Parsing of the various MathML functions and constants are all
1988 * case-insensitive by default: function names such as <code>cos</code>,
1989 * <code>Cos</code> and <code>COS</code> are all parsed as the MathML cosine
1990 * operator, <code>&lt;cos&gt;</code>.  However, <em>when a {@link Model} object is
1991 * used</em> in conjunction with either
1992 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
1993 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>, any identifiers found in that model will be
1994 * parsed in a case-<em>sensitive</em> way.  For example, if a model contains
1995 * a {@link Species} having the identifier <code>Pi</code>, the parser will parse
1996 * &quot;<code>Pi</code>&quot; in the input as &quot;<code>&lt;ci&gt; Pi
1997 * &lt;/ci&gt;</code>&quot; but will continue to parse the symbols
1998 * &quot;<code>pi</code>&quot; and &quot;<code>PI</code>&quot; as
1999 * &quot;<code>&lt;pi&gt;</code>&quot;.
2000 <p>
2001 * As mentioned above, the manner in which the 'L3' versions of the formula
2002 * parser and formatter interpret the function &quot;<code>log</code>&quot;
2003 * can be changed.  To do so, callers should use the function
2004 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and pass it an appropriate {@link L3ParserSettings}
2005 * object.  By default, unlike the SBML Level&nbsp;1 parser implemented by
2006 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>, the string
2007 * &quot;<code>log</code>&quot; is interpreted as the base&nbsp;10 logarithm,
2008 * and <em>not</em> as the natural logarithm.  However, you can change the
2009 * interpretation to be base-10 log, natural log, or as an error; since the
2010 * name 'log' by itself is ambiguous, you require that the parser uses 
2011 * <code>log10</code> or <code>ln</code> instead, which are more clear.  Please refer to
2012 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.
2013 <p>
2014 * In addition, the following symbols will be translated to their MathML
2015 * equivalents, if no symbol with the same <code>SId</code> identifier string exists
2016 * in the {@link Model} object provided:
2017 <p>
2018 * <table border="0" width="95%"
2019       class="centered text-table normal-font alt-row-colors">
2020 <tr>
2021     <th align="left" width="60">Name</th>
2022     <th align="left" width="250">Meaning</th>
2023     <th align="left">MathML</th>
2024 </tr>
2025<tr><td><code>true</code></td>   
2026    <td>The boolean value <code>true</code></td>
2027    <td><code>&lt;true/&gt;</code></td>
2028</tr>
2029<tr><td><code>false</code></td>   
2030    <td>The boolean value <code>false</code></td>
2031    <td><code>&lt;false/&gt;</code></td>
2032</tr>
2033<tr><td><code>pi</code></td>   
2034    <td>The mathematical constant pi</td>
2035    <td><code>&lt;pi/&gt;</code></td>
2036</tr>
2037<tr><td><code>avogadro</code></td>   
2038    <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td>
2039    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"&gt; avogadro &lt;/csymbol/&gt;</code></td>
2040</tr>
2041<tr><td><code>time</code></td>   
2042    <td>Simulation time as defined in SBML</td>
2043    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"&gt; time &lt;/csymbol/&gt;</code></td>
2044</tr>
2045<tr><td><code>inf</code> or <code>infinity</code></td>   
2046    <td>The mathematical constant "infinity"</td>
2047    <td><code>&lt;infinity/&gt;</code></td>
2048</tr>
2049<tr><td><code>nan</code> or <code>notanumber</code></td>   
2050    <td>The mathematical concept "not a number"</td>
2051    <td><code>&lt;notanumber/&gt;</code></td>
2052</tr>
2053
2054<caption class="top-caption">Mathematical symbols defined
2055in the "Level&nbsp;3" text-string formula syntax.
2056</caption>
2057</table>
2058
2059 <p>
2060 * Again, as mentioned above, whether the string
2061 * &quot;<code>avogadro</code>&quot; is parsed as an AST node of type
2062 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or
2063 * {@link libsbmlConstants#AST_NAME AST_NAME} is configurable; use the version of
2064 * the parser function called <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  This Avogadro-related
2065 * functionality is provided because SBML Level&nbsp;2 models may not use
2066 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes.
2067 <p>
2068 * @param tree the AST to be converted.
2069 <p>
2070 * @return the formula from the given AST as text string, with a syntax
2071 * oriented towards the capabilities defined in SBML Level&nbsp;3.  The
2072 * caller owns the returned string and is responsible for freeing it when it
2073 * is no longer needed.  If <code>tree</code> is a null pointer, then a null pointer is
2074 * returned.
2075 <p>
2076 * @see <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
2077 * @see <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
2078 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
2079 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
2080 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2081 * @see L3ParserSettings
2082 * @see <a href='libsbml.html#getDefaultL3ParserSettings()'><code>libsbml.getDefaultL3ParserSettings()</code></a>
2083 * @see <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>
2084 */ public
2085 static String formulaToL3String(ASTNode tree) {
2086    return libsbmlJNI.formulaToL3String(ASTNode.getCPtr(tree), tree);
2087  }
2088
2089  
2090/**
2091 * Converts an AST to a text string representation of a formula, using
2092 * specific formatter settings.
2093 <p>
2094 * This function behaves identically to <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a> but its behavior is controlled by two fields in the 
2095 * <code>settings</code> object, namely:
2096 <p>
2097 * <ul>
2098 * <li> <em>parseunits</em> ('parse units'): If this field in the <code>settings</code>
2099 *     object is set to <code>true</code> (the default), the function will
2100 *     write out the units of any numerical ASTNodes that have them,
2101 *     producing (for example) &quot;<code>3 mL</code>&quot;,
2102 *     &quot;<code>(3/4) m</code>&quot;, or &quot;<code>5.5e-10
2103 *     M</code>&quot;.  If this is set to <code>false</code>, this function
2104 *     will only write out the number itself (&quot;<code>3</code>&quot;,
2105 *     &quot;<code>(3/4)</code>&quot;, and &quot;<code>5.5e-10</code>&quot;,
2106 *     in the previous examples).
2107 * <li> <em>collapseminus</em> ('collapse minus'): If this field in the 
2108 *     <code>settings</code> object is set to <code>false</code> (the default), the
2109 *     function will write out explicitly any doubly-nested unary minus
2110 *     ASTNodes, producing (for example) &quot;<code>- -x</code>&quot; or
2111 *     even &quot;<code>- - - - -3.1</code>&quot;.  If this is set to
2112 *     <code>true</code>, the function will collapse the nodes before
2113 *     producing the infix form, producing &quot;<code>x</code>&quot; and
2114 *     &quot;<code>-3.1</code>&quot; in the previous examples.
2115 *
2116 * </ul> <p>
2117 * All the other settings of the {@link L3ParserSettings} object passed in as 
2118 * <code>settings</code> will be ignored for the purposes of this function: the
2119 * <em>parselog</em> ('parse log') setting is ignored so that
2120 * &quot;<code>log10(x)</code>&quot;, &quot;<code>ln(x)</code>&quot;, and
2121 * &quot;<code>log(x, y)</code>&quot; are always produced; the
2122 * <em>avocsymbol</em> ('Avogadro csymbol') is irrelevant to the behavior
2123 * of this function; and nothing in the {@link Model} object set via the
2124 * <em>model</em> setting is used.
2125 <p>
2126 * @param tree the AST to be converted.
2127<p>
2128 * @param settings the {@link L3ParserSettings} object used to modify the behavior of
2129 * this function.
2130 <p>
2131 * @return the formula from the given AST as text string, with a syntax
2132 * oriented towards the capabilities defined in SBML Level&nbsp;3.  The
2133 * caller owns the returned string and is responsible for freeing it when it
2134 * is no longer needed.  If <code>tree</code> is a null pointer, then a null pointer is
2135 * returned.
2136 <p>
2137 * @see <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>
2138 * @see <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
2139 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
2140 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
2141 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2142 * @see L3ParserSettings
2143 * @see <a href='libsbml.html#getDefaultL3ParserSettings()'><code>libsbml.getDefaultL3ParserSettings()</code></a>
2144 * @see <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>
2145 */ public
2146 static String formulaToL3StringWithSettings(ASTNode tree, L3ParserSettings settings) {
2147    return libsbmlJNI.formulaToL3StringWithSettings(ASTNode.getCPtr(tree), tree, L3ParserSettings.getCPtr(settings), settings);
2148  }
2149
2150  
2151/**
2152 * Converts an AST to a text string representation of a formula using a
2153 * basic syntax derived from SBML Level&nbsp;1.
2154 <p>
2155 * <p>
2156 * The text-string form of mathematical formulas produced by
2157 * <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a> and read by
2158 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> use a simple C-inspired infix
2159 * notation taken from SBML Level&nbsp;1.  A formula in this text-string form
2160 * therefore can be handed to a program that understands SBML Level&nbsp;1
2161 * mathematical expressions, or used as part of a formula translation system.
2162 * The syntax is described in detail in the documentation for {@link ASTNode}.  The
2163 * following are illustrative examples of formulas expressed using this syntax:
2164 * <pre class='fragment'>
21650.10 * k4^2
2166</pre>
2167<pre class='fragment'>
2168(vm * s1)/(km + s1)
2169</pre>
2170 <p>
2171 * Note that this facility is provided as a convenience by libSBML&mdash;the
2172 * MathML standard does not actually define a 'string-form' equivalent to
2173 * MathML expression trees, so the choice of formula syntax is somewhat
2174 * arbitrary.  The approach taken by libSBML is to use the syntax defined by
2175 * SBML Level&nbsp;1 (which in fact used a text-string representation of
2176 * formulas and not MathML).  This formula syntax is based mostly on C
2177 * programming syntax, and may contain operators, function calls, symbols,
2178 * and white space characters.  The following table provides the precedence
2179 * rules for the different entities that may appear in formula strings.
2180 <p>
2181 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em">
2182 <tr style="background: lightgray; font-size: 14px;">
2183     <th align="left">Token</th>
2184     <th align="left">Operation</th>
2185     <th align="left">Class</th>
2186     <th>Precedence</th>
2187     <th align="left">Associates</th>
2188 </tr>
2189<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
2190<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
2191<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">6</td><td>left</td></tr>
2192<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr>
2193<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr>
2194<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr>
2195<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
2196<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr>
2197<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr>
2198<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
2199<caption class="top-caption">A table of the expression operators and their precedence in the
2200text-string format for mathematical expressions used by SBML_parseFormula().
2201</caption>
2202</table>
2203
2204
2205 <p>
2206 * In the table above, <em>operand</em> implies the construct is an operand, 
2207 * <em>prefix</em> implies the operation is applied to the following arguments, 
2208 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
2209 * two arguments.  The values in the <b>Precedence</b> column show how the
2210 * order of different types of operation are determined.  For example, the
2211 * expression <code>a * b + c</code> is evaluated as <code>(a * b) +
2212 * c</code> because the @c * operator has higher precedence.  The
2213 * <b>Associates</b> column shows how the order of similar precedence
2214 * operations is determined; for example, <code>a - b + c</code> is
2215 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code>
2216 * operators are left-associative.
2217 <p>
2218 * The function call syntax consists of a function name, followed by optional
2219 * white space, followed by an opening parenthesis token, followed by a
2220 * sequence of zero or more arguments separated by commas (with each comma
2221 * optionally preceded and/or followed by zero or more white space
2222 * characters, followed by a closing parenthesis token.  The function name
2223 * must be chosen from one of the pre-defined functions in SBML or a
2224 * user-defined function in the model.  The following table lists the names
2225 * of certain common mathematical functions; this table corresponds to
2226 * Table&nbsp;6 in the <a target='_blank' href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML Level&nbsp;1 Version&nbsp;2 specification</a>:
2227 <p>
2228 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
2229 <tr>
2230     <th align="left" width="60">Name</th>
2231     <th align="left" width="35">Args</th>
2232     <th align="left">Formula or meaning</th>
2233     <th align="left" width="90">Argument Constraints</th>
2234     <th align="left" width="90">Result constraints</th>
2235 </tr>
2236<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr>
2237<tr><td><code>acos</code></td><td><em>x</em></td><td>arc cosine of <em>x</em> in radians</td><td>-1.0 &le; <em>x</em> &le; 1.0</td><td>0 &le; <em>acos(x)</em> &le; &pi;</td></tr>
2238<tr><td><code>asin</code></td><td><em>x</em></td><td>arc sine of <em>x</em> in radians</td><td>-1.0 &le; <em>x</em> &le; 1.0</td><td>0 &le; <em>asin(x)</em> &le; &pi;</td></tr>
2239<tr><td><code>atan</code></td><td><em>x</em></td><td>arc tangent of <em>x</em> in radians</td><td></td><td>0 &le; <em>atan(x)</em> &le; &pi;</td></tr>
2240<tr><td><code>ceil</code></td><td><em>x</em></td><td>smallest number not less than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr>
2241<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr>
2242<tr><td><code>exp</code></td><td><em>x</em></td><td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm</td><td></td><td></td></tr>
2243<tr><td><code>floor</code></td><td><em>x</em></td><td>the largest number not greater than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr>
2244<tr><td><code>log</code></td><td><em>x</em></td><td>natural logarithm of <em>x</em></td><td><em>x</em> &gt; 0</td><td></td></tr>
2245<tr><td><code>log10</code></td><td><em>x</em></td><td>base 10 logarithm of <em>x</em></td><td><em>x</em> &gt; 0</td><td></td></tr>
2246<tr><td><code>pow</code></td><td><em>x, y</em></td><td><em>x</em><sup><em> y</em></sup></td><td></td><td></td></tr>
2247<tr><td><code>sqr</code></td><td><em>x</em></td><td><em>x</em><sup><em>2</em></sup></td><td></td><td></td></tr>
2248<tr><td><code>sqrt</code></td><td><em>x</em></td><td>&radic;<em>x</em></td><td><em>x</em> &gt; 0</td><td><em>sqrt(x)</em> &ge; 0</td></tr>
2249<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr>
2250<tr><td><code>tan</code></td><td><em>x</em></td><td>tangent of <em>x</em></td><td>x &ne; n*&pi;/2, for odd integer <em>n</em></td><td></td></tr>
2251<caption class="bottom-caption">The names of mathematical functions defined in the SBML
2252Level&nbsp;1 Version&nbsp;2 text-string formula syntax.</caption>
2253</table>
2254
2255
2256 <p>
2257 * @warning <span class='warning'>There are differences between the symbols
2258 * used to represent the common mathematical functions and the corresponding
2259 * MathML token names.  This is a potential source of incompatibilities.
2260 * Note in particular that in this text-string syntax, <code>log(x)</code>
2261 * represents the natural logarithm, whereas in MathML, the natural logarithm
2262 * is <code>&lt;ln/&gt;</code>.  Application writers are urged to be careful
2263 * when translating between text forms and MathML forms, especially if they
2264 * provide a direct text-string input facility to users of their software
2265 * systems.</span>
2266 <p>
2267 * @param tree the AST to be converted.
2268 <p>
2269 * @return the formula from the given AST as a text-string mathematical
2270 * formula oriented towards SBML Level&nbsp;1.  The caller owns the returned
2271 * string and is responsible for freeing it when it is no longer needed.
2272 <p>
2273 * 
2274 * <p>
2275 * @note
2276 * Callers using SBML Level&nbsp;3 are encouraged to use the facilities
2277 * provided by libSBML's newer and more powerful Level&nbsp;3-oriented
2278 * formula parser and formatter.  The entry points to this second system are
2279 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and
2280 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>.  The Level&nbsp;1-oriented
2281 * system (i.e., what is provided by <a href='libsbml.html#formulaToString(java.lang.String)'><code>libsbml.formulaToString(String)</code></a>
2282 * and <a href='libsbml.html#parseFormula(org.sbml.libsbml.ASTNode)'><code>libsbml.parseFormula(ASTNode)</code></a>) is provided
2283 * untouched for backwards compatibility.
2284 <p>
2285 * <p>
2286 * @note We urge developers to keep in mind that the text-string formula
2287 * syntax is specific to libSBML.  <em>Neither MathML nor SBML define a
2288 * text-string format for mathematical formulas.</em> LibSBML's particular
2289 * syntax should not be considered to be a canonical or standard
2290 * general-purpose mathematical expression syntax.  LibSBML provides methods
2291 * for parsing and transforming text-string math formulas back and forth from
2292 * AST structures for the convenience of calling applications, but it is
2293 * important to keep the system's limitations in mind.
2294 <p>
2295   * @see <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>
2296 * @see <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
2297 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
2298 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
2299 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2300 */ public
2301 static String formulaToString(ASTNode tree) {
2302    return libsbmlJNI.formulaToString(ASTNode.getCPtr(tree), tree);
2303  }
2304
2305  
2306/**
2307 * Parses a text string as a mathematical formula and returns an AST
2308 * representation of it.
2309 <p>
2310 * <p>
2311 * The text-string form of mathematical formulas read by the function
2312 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and written by the function
2313 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a> uses an expanded version of
2314 * the syntax read and written by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2315 * and <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>, respectively.  The
2316 * latter two libSBML functions were originally developed to support
2317 * conversion between SBML Levels&nbsp;1 and&nbsp;2, and were focused on the
2318 * syntax of mathematical formulas used in SBML Level&nbsp;1.  With time, and
2319 * the use of MathML in SBML Levels&nbsp;2 and&nbsp;3, it became clear that
2320 * supporting Level&nbsp;2 and&nbsp;3's expanded mathematical syntax would be
2321 * useful for software developers.  To maintain backwards compatibility for
2322 * libSBML users, the original <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
2323 * and <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> have been left untouched,
2324 * and instead, the new functionality is provided in the form of
2325 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and
2326 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>.
2327 <p>
2328 * The following lists the main differences in the formula syntax supported by
2329 * the 'Level 3' or L3 versions of the formula parsers and formatters,
2330 * compared to what is supported by the Level&nbsp;1-oriented
2331 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> and
2332 * <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>:
2333 <p>
2334 * <ul>
2335 * <li> Units may be asociated with bare numbers, using the following syntax:
2336 * <div style='margin: 10px auto 10px 25px; display: block'>
2337 * <span class='code' style='background-color: #d0d0ee'>number</span>
2338 * <span class='code' style='background-color: #edd'>unit</span>
2339 * </div>
2340 * The <span class='code' style='background-color: #d0d0ee'>number</span>
2341 * may be in any form (an integer, real, or rational
2342 * number), and the
2343 * <span class='code' style='background-color: #edd'>unit</span>
2344 * must conform to the syntax of an SBML identifier (technically, the
2345 * type defined as <code>SId</code> in the SBML specifications).  The whitespace between
2346 * <span class='code' style='background-color: #d0d0ee'>number</span>
2347 * and <span class='code' style='background-color: #edd'>unit</span>
2348 * is optional.
2349 <p>
2350 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be
2351 * used.
2352 <p>
2353 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and will
2354 * produce a <code>&lt;piecewise&gt;</code> function in the corresponding
2355 * MathML output.
2356 <p>
2357 * <li> All inverse trigonometric functions may be defined in the infix either
2358 * using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both <code>arccsc</code>
2359 * and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> as defined in
2360 * MathML&nbsp;2.0.  (Many functions in the simpler SBML Level&nbsp;1
2361 * oriented parser implemented by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2362 * are defined this way as well, but not all.)
2363 <p>
2364 * <li> The following expression is parsed as a rational number instead of
2365 * as a numerical division:
2366 * <pre style='display: block; margin-left: 25px'>
2367 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre>
2368 * <strong>Spaces are not allowed</strong> in this construct; in other words,
2369 * &quot;<code>(3 / 4)</code>&quot; (with whitespace between the numbers and
2370 * the operator) will be parsed into the MathML <code>&lt;divide&gt;</code>
2371 * construct rather than a rational number.  You can, however, assign units to a
2372 * rational number as a whole; here is an example: &quot;<code>(3/4) ml</code>&quot;.
2373 * (In the case of division rather than a rational number, units are not interpreted
2374 * in this way.)
2375 <p>
2376 * <li> Various parser and formatter behaviors may be altered through the use
2377 * of a {@link L3ParserSettings} object in conjunction with the functions
2378 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
2379 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
2380 * The settings available include the following:
2381 * <ul style='list-style-type: circle'>
2382 *
2383 * </ul> <p>
2384 * <li style='margin-bottom: 0.5em'> The function <code>log</code> with a single
2385 * argument (&quot;<code>log(x)</code>&quot;) can be parsed as
2386 * <code>log10(x)</code>, <code>ln(x)</code>, or treated as an error, as
2387 * desired.
2388 <p>
2389 * <li style='margin-bottom: 0.5em'> Unary minus signs can be collapsed or
2390 * preserved; that is, sequential pairs of unary minuses (e.g., &quot;<code>-
2391 * -3</code>&quot;) can be removed from the input entirely and single unary
2392 * minuses can be incorporated into the number node, or all minuses can be
2393 * preserved in the AST node structure.
2394 <p>
2395 * <li style='margin-bottom: 0.5em'> Parsing of units embedded in the input
2396 * string can be turned on and off.
2397 <p>
2398 * <li style='margin-bottom: 0.5em'> The string <code>avogadro</code> can be parsed as
2399 * a MathML <em>csymbol</em> or as an identifier.
2400 <p>
2401 * <li style='margin-bottom: 0.5em'> A {@link Model} object may optionally be
2402 * provided to the parser using the variant function call
2403 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
2404 * stored in a {@link L3ParserSettings} object passed to the variant function
2405 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  When a {@link Model} object is provided, identifiers
2406 * (values of type <code>SId</code>) from that model are used in preference to
2407 * pre-defined MathML definitions for both symbols and functions.
2408 * More precisely:
2409 * <ul style='list-style-type: square'>
2410 <p>
2411 * <li style='margin-bottom: 0.5em'> <em>In the case of symbols</em>: the
2412 * {@link Model} entities whose identifiers will shadow identical symbols in the
2413 * mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter}, {@link Reaction}, and
2414 * {@link SpeciesReference}.  For instance, if the parser is given a {@link Model} containing
2415 * a {@link Species} with the identifier &quot;<code>pi</code>&quot;, and the formula
2416 * to be parsed is &quot;<code>3*pi</code>&quot;, the MathML produced will
2417 * contain the construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of
2418 * the construct <code>&lt;pi/&gt;</code>.
2419 <p>
2420 * <li style='margin-bottom: 0.5em'> <em>In the case of user-defined
2421 * functions</em>: when a {@link Model} object is provided, <code>SId</code> values of
2422 * user-defined functions present in the model will be used preferentially
2423 * over pre-defined MathML functions.  For example, if the passed-in {@link Model}
2424 * contains a {@link FunctionDefinition} object with the identifier
2425 * &quot;<code>sin</code>&quot;, that function will be used instead of the
2426 * predefined MathML function <code>&lt;sin/&gt;</code>.
2427 * </ul>
2428 <p>
2429 * <li style='margin-bottom: 0.5em'> An {@link SBMLNamespaces} object may optionally
2430 * be provided to identify SBML Level&nbsp;3 packages that extend the
2431 * syntax understood by the formula parser.  When the namespaces are provided,
2432 * the parser will interpret possible additional syntax defined by the libSBML
2433 * plug-ins implementing the SBML Level&nbsp;3 packages; for example, it may
2434 * understand vector/array extensions introduced by the SBML Level&nbsp;3 
2435 * <em>Arrays</em> package.
2436 * </ul>
2437 <p>
2438 * These configuration settings cannot be changed directly using the basic
2439 * parser and formatter functions, but <em>can</em> be changed on a per-call basis
2440 * by using the alternative functions <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
2441 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>.
2442 <p>
2443 * Neither SBML nor the MathML standard define a 'string-form' equivalent to
2444 * MathML expressions.  The approach taken by libSBML is to start with the
2445 * formula syntax defined by SBML Level&nbsp;1 (which in fact used a custom
2446 * text-string representation of formulas, and not MathML), and expand it to
2447 * include the functionality described above.  This formula syntax is based
2448 * mostly on C programming syntax, and may contain operators, function calls,
2449 * symbols, and white space characters.  The following table provides the
2450 * precedence rules for the different entities that may appear in formula
2451 * strings.
2452 <p>
2453 * <table border="0" width="95%"
2454       class="centered text-table normal-font alt-row-colors"
2455       style="padding-bottom: 0.5em">
2456 <tr style="background: lightgray; font-size: 14px;">
2457     <th align="left">Token</th>
2458     <th align="left">Operation</th>
2459     <th align="left">Class</th>
2460     <th>Precedence</th>
2461     <th align="left">Associates</th>
2462 </tr>
2463<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
2464<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
2465<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">8</td><td>left</td></tr>
2466<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">7</td><td>left</td></tr>
2467<tr><td><code>-, !</code></td><td>negation and boolean 'not'</td><td>unary</td><td align="center">6</td><td>right</td></tr>
2468<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align="center">5</td><td>left</td></tr>
2469<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align="center">4</td><td>left</td></tr>
2470<tr><td><code>==, &lt;, &gt;, &lt=, &gt=, !=</code></td><td>boolean equality, inequality, and comparison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
2471<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align="center">2</td><td>left</td></tr>
2472<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
2473
2474<caption class="top-caption">Expression operators and their precedence in the
2475"Level&nbsp;3" text-string format for mathematical expressions.
2476</caption>
2477</table>
2478
2479
2480 <p>
2481 * In the table above, <em>operand</em> implies the construct is an operand, 
2482 * <em>prefix</em> implies the operation is applied to the following arguments, 
2483 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
2484 * two arguments.  The values in the <b>Precedence</b> column show how the
2485 * order of different types of operation are determined.  For example, the
2486 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code>
2487 * because the @c * operator has higher precedence.  The
2488 * <b>Associates</b> column shows how the order of similar precedence
2489 * operations is determined; for example, <code>a && b || c</code> is
2490 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code>
2491 * operators are left-associative and have the same precedence.
2492 <p>
2493 * The function call syntax consists of a function name, followed by optional
2494 * white space, followed by an opening parenthesis token, followed by a
2495 * sequence of zero or more arguments separated by commas (with each comma
2496 * optionally preceded and/or followed by zero or more white space
2497 * characters), followed by a closing parenthesis token.  The function name
2498 * must be chosen from one of the pre-defined functions in SBML or a
2499 * user-defined function in the model.  The following table lists the names
2500 * of certain common mathematical functions; this table corresponds to
2501 * Table&nbsp;6 in the <a target='_blank'
2502 * href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML
2503 * Level&nbsp;1 Version&nbsp;2 specification</a> with additions based on the
2504 * functions added in SBML Level 2 and Level 3:
2505 <p>
2506 * <table border="0" width="95%" 
2507       class="centered text-table normal-font alt-row-colors">
2508 <tr>
2509     <th align="left" width="60">Name</th>
2510     <th align="left" width="75">Argument(s)</th>
2511     <th align="left">Formula or meaning</th>
2512     <th align="left" width="90">Argument Constraints</th>
2513     <th align="left" width="90">Result constraints</th>
2514 </tr>
2515<tr><td><code>abs</code></td>   
2516    <td><em>x</em></td> 
2517    <td>Absolute value of <em>x</em>.</td>
2518    <td></td>
2519    <td></td>
2520</tr>
2521<tr><td><code>acos</code>, <code>arccos</code></td>
2522    <td><em>x</em></td>
2523    <td>Arccosine of <em>x</em> in radians.</td>
2524    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
2525    <td>0 &le; <em>acos(x)</em> &le; &pi;</td>
2526</tr>
2527<tr><td><code>acosh</code>, <code>arccosh</code></td>
2528    <td><em>x</em></td>
2529    <td>Hyperbolic arccosine of <em>x</em> in radians.</td>
2530    <td></td>
2531    <td></td>
2532</tr>
2533<tr><td><code>acot</code>, <code>arccot</code></td>
2534    <td><em>x</em></td>
2535    <td>Arccotangent of <em>x</em> in radians.</td>
2536    <td></td>
2537    <td></td>
2538</tr>
2539<tr><td><code>acoth</code>, <code>arccoth</code></td>
2540    <td><em>x</em></td>
2541    <td>Hyperbolic arccotangent of <em>x</em> in radians.</td>
2542    <td></td>
2543    <td></td>
2544</tr>
2545<tr><td><code>acsc</code>, <code>arccsc</code></td>
2546    <td><em>x</em></td>
2547    <td>Arccosecant of <em>x</em> in radians.</td>
2548    <td></td>
2549    <td></td>
2550</tr>
2551<tr><td><code>acsch</code>, <code>arccsch</code></td>
2552    <td><em>x</em></td>
2553    <td>Hyperbolic arccosecant of <em>x</em> in radians.</td>
2554    <td></td>
2555    <td></td>
2556</tr>
2557<tr><td><code>asec</code>, <code>arcsec</code></td>
2558    <td><em>x</em></td>
2559    <td>Arcsecant of <em>x</em> in radians.</td>
2560    <td></td>
2561    <td></td>
2562</tr>
2563<tr><td><code>asech</code>, <code>arcsech</code></td>
2564    <td><em>x</em></td>
2565    <td>Hyperbolic arcsecant of <em>x</em> in radians.</td>
2566    <td></td>
2567    <td></td>
2568</tr>
2569<tr><td><code>asin</code>, <code>arcsin</code></td>
2570    <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td>
2571    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
2572    <td>0 &le; <em>asin(x)</em> &le; &pi;</td>
2573</tr>
2574<tr><td><code>atan</code>, <code>arctan</code></td>
2575    <td><em>x</em></td>
2576    <td>Arctangent of <em>x</em> in radians.</td>
2577    <td></td>
2578    <td>0 &le; <em>atan(x)</em> &le; &pi;</td>
2579</tr>
2580<tr><td><code>atanh</code>, <code>arctanh</code></td>
2581    <td><em>x</em></td>
2582    <td>Hyperbolic arctangent of <em>x</em> in radians.</td>
2583    <td></td>
2584    <td></td>
2585</tr>
2586<tr><td><code>ceil</code>, <code>ceiling</code></td>
2587    <td><em>x</em></td>
2588    <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td>
2589    <td></td>
2590    <td></td>
2591</tr>
2592<tr><td><code>cos</code></td>
2593    <td><em>x</em></td>
2594    <td>Cosine of <em>x</em></td>
2595    <td></td>
2596    <td></td>
2597</tr>
2598<tr><td><code>cosh</code></td>
2599    <td><em>x</em></td>
2600    <td>Hyperbolic cosine of <em>x</em>.</td>
2601    <td></td>
2602    <td></td>
2603</tr>
2604<tr><td><code>cot</code></td>
2605    <td><em>x</em></td>
2606    <td>Cotangent of <em>x</em>.</td>
2607    <td></td>
2608    <td></td>
2609</tr>
2610<tr><td><code>coth</code></td>
2611    <td><em>x</em></td>
2612    <td>Hyperbolic cotangent of <em>x</em>.</td>
2613    <td></td>
2614    <td></td>
2615</tr>
2616<tr><td><code>csc</code></td>
2617    <td><em>x</em></td>
2618    <td>Cosecant of <em>x</em>.</td>
2619    <td></td>
2620    <td></td>
2621</tr>
2622<tr><td><code>csch</code></td>
2623    <td><em>x</em></td>
2624    <td>Hyperbolic cosecant of <em>x</em>.</td>
2625    <td></td>
2626    <td></td>
2627</tr>
2628<tr><td><code>delay</code></td>
2629    <td><em>x, y</em></td>
2630    <td>The value of <em>x</em> at <em>y</em> time units in the past.</td>
2631    <td></td>
2632    <td></td>
2633</tr>
2634<tr><td><code>factorial</code></td>
2635    <td><em>n</em></td>
2636    <td>The factorial of <em>n</em>. Factorials are defined by <em>n! = n*(n&ndash;1)* ... * 1</em>.</td>
2637    <td><em>n</em> must be an integer.</td>
2638    <td></td>
2639</tr>
2640<tr><td><code>exp</code></td>
2641    <td><em>x</em></td>
2642    <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td>
2643    <td></td>
2644    <td></td>
2645</tr>
2646<tr><td><code>floor</code></td>
2647    <td><em>x</em></td>
2648    <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td>
2649    <td></td>
2650    <td></td>
2651</tr>
2652<tr><td><code>ln</code></td>
2653    <td><em>x</em></td>
2654    <td>Natural logarithm of <em>x</em>.</td>
2655    <td><em>x</em> &gt; 0</td>
2656    <td></td>
2657</tr>
2658<tr><td><code>log</code></td>
2659    <td><em>x</em></td>
2660    <td>By default, the base 10 logarithm of <em>x</em>, but can be set to be the natural logarithm of <em>x</em>, or to be an illegal construct.</td>
2661    <td><em>x</em> &gt; 0</td>
2662    <td></td>
2663</tr>
2664<tr><td><code>log</code></td>
2665    <td><em>x, y</em></td>
2666    <td>The base <em>x</em> logarithm of <em>y</em>.</td>
2667    <td><em>y</em> &gt; 0</td>
2668    <td></td>
2669</tr>
2670<tr><td><code>log10</code></td>
2671    <td><em>x</em></td>
2672    <td>Base 10 logarithm of <em>x</em>.</td>
2673    <td><em>x</em> &gt; 0</td>
2674    <td></td>
2675</tr>
2676<tr><td><code>piecewise</code></td>
2677    <td><em>x1, y1, [x2, y2,] [...] [z]</em></td>
2678    <td>A piecewise function: if (<em>y1</em>), <em>x1</em>.  Otherwise, if (<em>y2</em>), <em>x2</em>, etc.  Otherwise, z. </td>
2679    <td><em>y1, y2, y3 [etc]</em> must be boolean</td>
2680    <td></td>
2681</tr>
2682<tr><td><code>pow</code>, <code>power</code> </td>
2683    <td><em>x, y</em></td>
2684    <td><em>x</em><sup><em> y</em></sup>.</td>
2685    <td></td>
2686    <td></td>
2687</tr>
2688<tr><td><code>root</code></td>
2689    <td><em>b, x</em></td>
2690    <td>The root base <em>b</em> of <em>x</em>.</td>
2691    <td></td>
2692    <td></td>
2693</tr>
2694<tr><td><code>sec</code></td>
2695    <td><em>x</em></td>
2696    <td>Secant of <em>x</em>.</td>
2697    <td></td>
2698    <td></td>
2699</tr>
2700<tr><td><code>sech</code></td>
2701    <td><em>x</em></td>
2702    <td>Hyperbolic secant of <em>x</em>.</td>
2703    <td></td>
2704    <td></td>
2705</tr>
2706<tr><td><code>sqr</code></td>
2707    <td><em>x</em></td>
2708    <td><em>x</em><sup><em>2</em></sup>.</td>
2709    <td></td>
2710    <td></td>
2711</tr>
2712<tr><td><code>sqrt</code></td>
2713    <td><em>x</em></td>
2714    <td>&radic;<em>x</em>.</td>
2715    <td><em>x</em> &gt; 0</td>
2716    <td><em>sqrt(x)</em> &ge; 0</td>
2717</tr>
2718<tr><td><code>sin</code></td>
2719    <td><em>x</em></td>
2720    <td>Sine of <em>x</em>.</td>
2721    <td></td>
2722    <td></td>
2723</tr>
2724<tr><td><code>sinh</code></td>
2725    <td><em>x</em></td>
2726    <td>Hyperbolic sine of <em>x</em>.</td>
2727    <td></td>
2728    <td></td>
2729</tr>
2730<tr><td><code>tan</code></td>
2731    <td><em>x</em></td>
2732    <td>Tangent of <em>x</em>.</td>
2733    <td>x &ne; n*&pi;/2, for odd integer <em>n</em></td>
2734    <td></td>
2735</tr>
2736<tr><td><code>tanh</code></td>
2737    <td><em>x</em></td>
2738    <td>Hyperbolic tangent of <em>x</em>.</td>
2739    <td></td>
2740    <td></td>
2741</tr>
2742<tr><td><code>and</code></td>
2743    <td><em>x, y, z...</em></td>
2744    <td>Boolean <em>and(x, y, z...)</em>: returns <code>true</code> if all of its arguments are true.  Note that <code>and</code> is an n-ary function, taking 0 or more arguments, and that <code>and()</code> returns <code>true</code>.</td>
2745    <td>All arguments must be boolean</td>
2746    <td></td>
2747</tr>
2748<tr><td><code>not</code></td>
2749    <td><em>x</em></td>
2750    <td>Boolean <em>not(x)</em></td>
2751    <td><em>x</em> must be boolean</td>
2752    <td></td>
2753</tr>
2754<tr><td><code>or</code></td>
2755    <td><em>x, y, z...</em></td>
2756    <td>Boolean <em>or(x, y, z...)</em>: returns <code>true</code> if at least one of its arguments is true.  Note that <code>or</code> is an n-ary function, taking 0 or more arguments, and that <code>or()</code> returns <code>false</code>.</td>
2757    <td>All arguments must be boolean</td>
2758    <td></td>
2759</tr>
2760<tr><td><code>xor</code></td>
2761    <td><em>x, y, z...</em></td>
2762    <td>Boolean <em>xor(x, y, z...)</em>: returns <code>true</code> if an odd number of its arguments is true.  Note that <code>xor</code> is an n-ary function, taking 0 or more arguments, and that <code>xor()</code> returns <code>false</code>.</td>
2763    <td>All arguments must be boolean</td>
2764    <td></td>
2765</tr>
2766<tr><td><code>eq</code></td>
2767    <td><em>x, y, z...</em></td>
2768    <td>Boolean <em>eq(x, y, z...)</em>: returns <code>true</code> if all arguments are equal.  Note that <code>eq</code> is an n-ary function, but must take 2 or more arguments.</td>
2769    <td></td>
2770    <td></td>
2771</tr>
2772<tr><td><code>geq</code></td>
2773    <td><em>x, y, z...</em></td>
2774    <td>Boolean <em>geq(x, y, z...)</em>: returns <code>true</code> if each argument is greater than or equal to the argument following it.  Note that <code>geq</code> is an n-ary function, but must take 2 or more arguments.</td>
2775    <td></td>
2776    <td></td>
2777</tr>
2778<tr><td><code>gt</code></td>
2779    <td><em>x, y, z...</em></td>
2780    <td>Boolean <em>gt(x, y, z...)</em>: returns <code>true</code> if each argument is greater than the argument following it.  Note that <code>gt</code> is an n-ary function, but must take 2 or more arguments.</td>
2781    <td></td>
2782    <td></td>
2783</tr>
2784<tr><td><code>leq</code></td>
2785    <td><em>x, y, z...</em></td>
2786    <td>Boolean <em>leq(x, y, z...)</em>: returns <code>true</code> if each argument is less than or equal to the argument following it.  Note that <code>leq</code> is an n-ary function, but must take 2 or more arguments.</td>
2787    <td></td>
2788    <td></td>
2789</tr>
2790<tr><td><code>lt</code></td>
2791    <td><em>x, y, z...</em></td>
2792    <td>Boolean <em>lt(x, y, z...)</em>: returns <code>true</code> if each argument is less than the argument following it.  Note that <code>lt</code> is an n-ary function, but must take 2 or more arguments.</td>
2793    <td></td>
2794    <td></td>
2795</tr>
2796<tr><td><code>neq</code></td>
2797    <td><em>x, y</em></td>
2798    <td>Boolean <em>x</em> != <em>y</em>: returns <code>true</code> unless x and y are equal.</td>
2799    <td></td>
2800    <td></td>
2801</tr>
2802<tr><td><code>plus</code></td>
2803    <td><em>x, y, z...</em></td>
2804    <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function.  Note that <code>plus</code> is an n-ary function taking 0 or more arguments, and that <code>plus()</code> returns <code>0</code>.</td>
2805    <td></td>
2806    <td></td>
2807</tr>
2808<tr><td><code>times</code></td>
2809    <td><em>x, y, z...</em></td>
2810    <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function.  Note that <code>times</code> is an n-ary function taking 0 or more arguments, and that <code>times()</code> returns <code>1</code>.</td>
2811    <td></td>
2812    <td></td>
2813</tr>
2814<tr><td><code>minus</code></td>
2815    <td><em>x, y</em></td>
2816    <td><em>x</em> &ndash; <em>y</em>.</td>
2817    <td></td>
2818    <td></td>
2819</tr>
2820<tr><td><code>divide</code></td>
2821    <td><em>x, y</em></td>
2822    <td><em>x</em> / <em>y</em>.</td>
2823    <td></td>
2824    <td></td>
2825</tr>
2826
2827<caption class="top-caption">Mathematical functions defined
2828in the "Level&nbsp;3" text-string formula syntax.</caption>
2829
2830</table>
2831
2832
2833 <p>
2834 * Parsing of the various MathML functions and constants are all
2835 * case-insensitive by default: function names such as <code>cos</code>,
2836 * <code>Cos</code> and <code>COS</code> are all parsed as the MathML cosine
2837 * operator, <code>&lt;cos&gt;</code>.  However, <em>when a {@link Model} object is
2838 * used</em> in conjunction with either
2839 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
2840 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>, any identifiers found in that model will be
2841 * parsed in a case-<em>sensitive</em> way.  For example, if a model contains
2842 * a {@link Species} having the identifier <code>Pi</code>, the parser will parse
2843 * &quot;<code>Pi</code>&quot; in the input as &quot;<code>&lt;ci&gt; Pi
2844 * &lt;/ci&gt;</code>&quot; but will continue to parse the symbols
2845 * &quot;<code>pi</code>&quot; and &quot;<code>PI</code>&quot; as
2846 * &quot;<code>&lt;pi&gt;</code>&quot;.
2847 <p>
2848 * As mentioned above, the manner in which the 'L3' versions of the formula
2849 * parser and formatter interpret the function &quot;<code>log</code>&quot;
2850 * can be changed.  To do so, callers should use the function
2851 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and pass it an appropriate {@link L3ParserSettings}
2852 * object.  By default, unlike the SBML Level&nbsp;1 parser implemented by
2853 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>, the string
2854 * &quot;<code>log</code>&quot; is interpreted as the base&nbsp;10 logarithm,
2855 * and <em>not</em> as the natural logarithm.  However, you can change the
2856 * interpretation to be base-10 log, natural log, or as an error; since the
2857 * name 'log' by itself is ambiguous, you require that the parser uses 
2858 * <code>log10</code> or <code>ln</code> instead, which are more clear.  Please refer to
2859 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.
2860 <p>
2861 * In addition, the following symbols will be translated to their MathML
2862 * equivalents, if no symbol with the same <code>SId</code> identifier string exists
2863 * in the {@link Model} object provided:
2864 <p>
2865 * <table border="0" width="95%"
2866       class="centered text-table normal-font alt-row-colors">
2867 <tr>
2868     <th align="left" width="60">Name</th>
2869     <th align="left" width="250">Meaning</th>
2870     <th align="left">MathML</th>
2871 </tr>
2872<tr><td><code>true</code></td>   
2873    <td>The boolean value <code>true</code></td>
2874    <td><code>&lt;true/&gt;</code></td>
2875</tr>
2876<tr><td><code>false</code></td>   
2877    <td>The boolean value <code>false</code></td>
2878    <td><code>&lt;false/&gt;</code></td>
2879</tr>
2880<tr><td><code>pi</code></td>   
2881    <td>The mathematical constant pi</td>
2882    <td><code>&lt;pi/&gt;</code></td>
2883</tr>
2884<tr><td><code>avogadro</code></td>   
2885    <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td>
2886    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"&gt; avogadro &lt;/csymbol/&gt;</code></td>
2887</tr>
2888<tr><td><code>time</code></td>   
2889    <td>Simulation time as defined in SBML</td>
2890    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"&gt; time &lt;/csymbol/&gt;</code></td>
2891</tr>
2892<tr><td><code>inf</code> or <code>infinity</code></td>   
2893    <td>The mathematical constant "infinity"</td>
2894    <td><code>&lt;infinity/&gt;</code></td>
2895</tr>
2896<tr><td><code>nan</code> or <code>notanumber</code></td>   
2897    <td>The mathematical concept "not a number"</td>
2898    <td><code>&lt;notanumber/&gt;</code></td>
2899</tr>
2900
2901<caption class="top-caption">Mathematical symbols defined
2902in the "Level&nbsp;3" text-string formula syntax.
2903</caption>
2904</table>
2905
2906 <p>
2907 * Again, as mentioned above, whether the string
2908 * &quot;<code>avogadro</code>&quot; is parsed as an AST node of type
2909 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or
2910 * {@link libsbmlConstants#AST_NAME AST_NAME} is configurable; use the version of
2911 * the parser function called <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  This Avogadro-related
2912 * functionality is provided because SBML Level&nbsp;2 models may not use
2913 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes.
2914 <p>
2915 * @param formula the text-string formula expression to be parsed
2916 <p>
2917 * @return the root node of an AST representing the mathematical formula, or
2918 * <code>null</code> if an error occurred while parsing the formula.  When <code>null</code> is
2919 * returned, an error is recorded internally; information about the error can
2920 * be retrieved using <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>.
2921 <p>
2922 * 
2923 * <p>
2924 * @note We urge developers to keep in mind that the text-string formula
2925 * syntax is specific to libSBML.  <em>Neither MathML nor SBML define a
2926 * text-string format for mathematical formulas.</em> LibSBML's particular
2927 * syntax should not be considered to be a canonical or standard
2928 * general-purpose mathematical expression syntax.  LibSBML provides methods
2929 * for parsing and transforming text-string math formulas back and forth from
2930 * AST structures for the convenience of calling applications, but it is
2931 * important to keep the system's limitations in mind.
2932 <p>
2933   * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
2934 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
2935 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2936 * @see <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
2937 * @see <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>
2938 * @see <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
2939 * @see L3ParserSettings
2940 * @see <a href='libsbml.html#getDefaultL3ParserSettings()'><code>libsbml.getDefaultL3ParserSettings()</code></a>
2941 * @see <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>
2942 */ public
2943 static ASTNode parseL3Formula(String formula) {
2944    long cPtr = libsbmlJNI.parseL3Formula(formula);
2945    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
2946  }
2947
2948  
2949/**
2950 * Parses a text string as a mathematical formula using a {@link Model} to resolve
2951 * symbols, and returns an AST representation of the result.
2952 <p>
2953 * This is identical to <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>, except
2954 * that this function uses the given model in the argument <code>model</code> to check
2955 * against identifiers that appear in the <code>formula</code>.  For more information
2956 * about the parser, please see the definition of {@link L3ParserSettings} and
2957 * the function <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>.
2958 <p>
2959 * @param formula the mathematical formula expression to be parsed
2960 <p>
2961 * @param model the {@link Model} object to use for checking identifiers
2962 <p>
2963 * @return the root node of an AST representing the mathematical formula,
2964 * or <code>null</code> if an error occurred while parsing the formula.  When <code>null</code>
2965 * is returned, an error is recorded internally; information about the
2966 * error can be retrieved using <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>.
2967 <p>
2968 * @see <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>
2969 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
2970 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
2971 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
2972 * @see <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>
2973 * @see L3ParserSettings
2974 */ public
2975 static ASTNode parseL3FormulaWithModel(String formula, Model model) {
2976    long cPtr = libsbmlJNI.parseL3FormulaWithModel(formula, Model.getCPtr(model), model);
2977    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
2978  }
2979
2980  
2981/**
2982 * Parses a text string as a mathematical formula using specific parser
2983 * settings and returns an AST representation of the result.
2984 <p>
2985 * This is identical to <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>, except
2986 * that this function uses the parser settings given in the argument 
2987 * <code>settings</code>.  The settings override the default parsing behavior.  The
2988 * following parsing behaviors can be configured:
2989 <p>
2990 * <p>
2991 * <ul>
2992 * <li> A {@link Model} object may optionally be provided to use identifiers (values
2993 * of type <code>SId</code>) from the model in preference to pre-defined MathML symbols
2994 * More precisely, the {@link Model} entities whose identifiers will shadow identical
2995 * symbols in the mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter},
2996 * {@link Reaction}, and {@link SpeciesReference}.  For instance, if the parser is given a
2997 * {@link Model} containing a {@link Species} with the identifier
2998 * &quot;<code>pi</code>&quot;, and the formula to be parsed is
2999 * &quot;<code>3*pi</code>&quot;, the MathML produced by the parser will
3000 * contain the construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of
3001 * the construct <code>&lt;pi/&gt;</code>.  Another example, if the passed-in
3002 * {@link Model} contains a {@link FunctionDefinition} with the identifier
3003 * &quot;<code>sin</code>&quot;, that function will be used instead of the
3004 * predefined MathML function <code>&lt;sin/&gt;</code>.
3005 * <li> The function <code>log</code> with a single argument
3006 * (&quot;<code>log(x)</code>&quot;) can be parsed as <code>log10(x)</code>,
3007 * <code>ln(x)</code>, or treated as an error, as desired.
3008 * <li> Unary minus signs can be either collapsed or preserved; that is, the
3009 * parser can either (1) remove sequential pairs of unary minuses (e.g.,
3010 * &quot;<code>- -3</code>&quot;) from the input and incorporate single unary
3011 * minuses into the number node, or (2) preserve all minuses in the AST node
3012 * structure, turning them into {@link ASTNode} objects of type
3013 * {@link libsbmlConstants#AST_MINUS AST_MINUS}.
3014 * <li> The character sequence &quot;<code>number id</code>&quot; can be
3015 * interpreted as a numerical value <code>number</code> followed by units of measurement
3016 * indicated by <code>id</code>, or it can be treated as a syntax error.  (In
3017 * Level&nbsp;3, MathML <code>&lt;cn&gt;</code> elements can have an
3018 * attribute named <code>units</code> placed in the SBML namespace, which can be used
3019 * to indicate the units to be associated with the number.  The text-string
3020 * infix formula parser allows units to be placed after raw numbers; they are
3021 * interpreted as unit identifiers for units defined by the SBML
3022 * specification or in the containing {@link Model} object.)
3023 * <li> The symbol <code>avogadro</code> can be parsed either as a MathML <em>csymbol</em> or
3024 * as a identifier.  More specifically, &quot;<code>avogadro</code>&quot; can
3025 * be treated as an {@link ASTNode} of type
3026 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or of type
3027 * {@link libsbmlConstants#AST_NAME AST_NAME}.
3028 * <li> Strings that match built-in functions and constants can either be parsed
3029 * as a match regardless of capitalization, or may be required to be
3030 * all-lower-case to be considered a match.
3031 * <li> LibSBML plug-ins implementing support for SBML Level&nbsp;3 packages
3032 * may introduce extensions to the syntax understood by the parser.  The
3033 * precise nature of the extensions will be documented by the individual
3034 * package plug-ins.  An example of a possible extension is a notation for
3035 * vectors and arrays, introduced by the SBML Level&nbsp;3 <em>Arrays</em>
3036 * package.
3037 *
3038 * </ul>
3039 <p>
3040 * For more details about the parser, please see the definition of
3041 * {@link L3ParserSettings} and <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.
3042 <p>
3043 * @param formula the mathematical formula expression to be parsed
3044 <p>
3045 * @param settings the settings to be used for this parser invocation
3046 <p>
3047 * @return the root node of an AST representing the mathematical formula,
3048 * or <code>null</code> if an error occurred while parsing the formula.  When <code>null</code>
3049 * is returned, an error is recorded internally; information about the
3050 * error can be retrieved using <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>.
3051 <p>
3052 * @see <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>
3053 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
3054 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
3055 * @see <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
3056 * @see <a href='libsbml.html#getLastParseL3Error()'><code>libsbml.getLastParseL3Error()</code></a>
3057 * @see L3ParserSettings
3058 */ public
3059 static ASTNode parseL3FormulaWithSettings(String formula, L3ParserSettings settings) {
3060    long cPtr = libsbmlJNI.parseL3FormulaWithSettings(formula, L3ParserSettings.getCPtr(settings), settings);
3061    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
3062  }
3063
3064  
3065/**
3066 * Returns a copy of the default Level&nbsp;3 ('L3') formula parser settings.
3067 <p>
3068 * The data structure storing the settings allows callers to change the
3069 * following parsing behaviors:
3070 <p>
3071 * <p>
3072 * The text-string form of mathematical formulas read by the function
3073 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and written by the function
3074 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a> uses an expanded version of
3075 * the syntax read and written by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
3076 * and <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>, respectively.  The
3077 * latter two libSBML functions were originally developed to support
3078 * conversion between SBML Levels&nbsp;1 and&nbsp;2, and were focused on the
3079 * syntax of mathematical formulas used in SBML Level&nbsp;1.  With time, and
3080 * the use of MathML in SBML Levels&nbsp;2 and&nbsp;3, it became clear that
3081 * supporting Level&nbsp;2 and&nbsp;3's expanded mathematical syntax would be
3082 * useful for software developers.  To maintain backwards compatibility for
3083 * libSBML users, the original <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>
3084 * and <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> have been left untouched,
3085 * and instead, the new functionality is provided in the form of
3086 * <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a> and
3087 * <a href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToL3String(ASTNode)</code></a>.
3088 <p>
3089 * The following lists the main differences in the formula syntax supported by
3090 * the 'Level 3' or L3 versions of the formula parsers and formatters,
3091 * compared to what is supported by the Level&nbsp;1-oriented
3092 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a> and
3093 * <a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'><code>libsbml.formulaToString(ASTNode)</code></a>:
3094 <p>
3095 * <ul>
3096 * <li> Units may be asociated with bare numbers, using the following syntax:
3097 * <div style='margin: 10px auto 10px 25px; display: block'>
3098 * <span class='code' style='background-color: #d0d0ee'>number</span>
3099 * <span class='code' style='background-color: #edd'>unit</span>
3100 * </div>
3101 * The <span class='code' style='background-color: #d0d0ee'>number</span>
3102 * may be in any form (an integer, real, or rational
3103 * number), and the
3104 * <span class='code' style='background-color: #edd'>unit</span>
3105 * must conform to the syntax of an SBML identifier (technically, the
3106 * type defined as <code>SId</code> in the SBML specifications).  The whitespace between
3107 * <span class='code' style='background-color: #d0d0ee'>number</span>
3108 * and <span class='code' style='background-color: #edd'>unit</span>
3109 * is optional.
3110 <p>
3111 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be
3112 * used.
3113 <p>
3114 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and will
3115 * produce a <code>&lt;piecewise&gt;</code> function in the corresponding
3116 * MathML output.
3117 <p>
3118 * <li> All inverse trigonometric functions may be defined in the infix either
3119 * using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both <code>arccsc</code>
3120 * and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> as defined in
3121 * MathML&nbsp;2.0.  (Many functions in the simpler SBML Level&nbsp;1
3122 * oriented parser implemented by <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>
3123 * are defined this way as well, but not all.)
3124 <p>
3125 * <li> The following expression is parsed as a rational number instead of
3126 * as a numerical division:
3127 * <pre style='display: block; margin-left: 25px'>
3128 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre>
3129 * <strong>Spaces are not allowed</strong> in this construct; in other words,
3130 * &quot;<code>(3 / 4)</code>&quot; (with whitespace between the numbers and
3131 * the operator) will be parsed into the MathML <code>&lt;divide&gt;</code>
3132 * construct rather than a rational number.  You can, however, assign units to a
3133 * rational number as a whole; here is an example: &quot;<code>(3/4) ml</code>&quot;.
3134 * (In the case of division rather than a rational number, units are not interpreted
3135 * in this way.)
3136 <p>
3137 * <li> Various parser and formatter behaviors may be altered through the use
3138 * of a {@link L3ParserSettings} object in conjunction with the functions
3139 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
3140 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
3141 * The settings available include the following:
3142 * <ul style='list-style-type: circle'>
3143 *
3144 * </ul> <p>
3145 * <li style='margin-bottom: 0.5em'> The function <code>log</code> with a single
3146 * argument (&quot;<code>log(x)</code>&quot;) can be parsed as
3147 * <code>log10(x)</code>, <code>ln(x)</code>, or treated as an error, as
3148 * desired.
3149 <p>
3150 * <li style='margin-bottom: 0.5em'> Unary minus signs can be collapsed or
3151 * preserved; that is, sequential pairs of unary minuses (e.g., &quot;<code>-
3152 * -3</code>&quot;) can be removed from the input entirely and single unary
3153 * minuses can be incorporated into the number node, or all minuses can be
3154 * preserved in the AST node structure.
3155 <p>
3156 * <li style='margin-bottom: 0.5em'> Parsing of units embedded in the input
3157 * string can be turned on and off.
3158 <p>
3159 * <li style='margin-bottom: 0.5em'> The string <code>avogadro</code> can be parsed as
3160 * a MathML <em>csymbol</em> or as an identifier.
3161 <p>
3162 * <li style='margin-bottom: 0.5em'> A {@link Model} object may optionally be
3163 * provided to the parser using the variant function call
3164 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
3165 * stored in a {@link L3ParserSettings} object passed to the variant function
3166 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  When a {@link Model} object is provided, identifiers
3167 * (values of type <code>SId</code>) from that model are used in preference to
3168 * pre-defined MathML definitions for both symbols and functions.
3169 * More precisely:
3170 * <ul style='list-style-type: square'>
3171 <p>
3172 * <li style='margin-bottom: 0.5em'> <em>In the case of symbols</em>: the
3173 * {@link Model} entities whose identifiers will shadow identical symbols in the
3174 * mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter}, {@link Reaction}, and
3175 * {@link SpeciesReference}.  For instance, if the parser is given a {@link Model} containing
3176 * a {@link Species} with the identifier &quot;<code>pi</code>&quot;, and the formula
3177 * to be parsed is &quot;<code>3*pi</code>&quot;, the MathML produced will
3178 * contain the construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of
3179 * the construct <code>&lt;pi/&gt;</code>.
3180 <p>
3181 * <li style='margin-bottom: 0.5em'> <em>In the case of user-defined
3182 * functions</em>: when a {@link Model} object is provided, <code>SId</code> values of
3183 * user-defined functions present in the model will be used preferentially
3184 * over pre-defined MathML functions.  For example, if the passed-in {@link Model}
3185 * contains a {@link FunctionDefinition} object with the identifier
3186 * &quot;<code>sin</code>&quot;, that function will be used instead of the
3187 * predefined MathML function <code>&lt;sin/&gt;</code>.
3188 * </ul>
3189 <p>
3190 * <li style='margin-bottom: 0.5em'> An {@link SBMLNamespaces} object may optionally
3191 * be provided to identify SBML Level&nbsp;3 packages that extend the
3192 * syntax understood by the formula parser.  When the namespaces are provided,
3193 * the parser will interpret possible additional syntax defined by the libSBML
3194 * plug-ins implementing the SBML Level&nbsp;3 packages; for example, it may
3195 * understand vector/array extensions introduced by the SBML Level&nbsp;3 
3196 * <em>Arrays</em> package.
3197 * </ul>
3198 <p>
3199 * These configuration settings cannot be changed directly using the basic
3200 * parser and formatter functions, but <em>can</em> be changed on a per-call basis
3201 * by using the alternative functions <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and
3202 * <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>.
3203 <p>
3204 * Neither SBML nor the MathML standard define a 'string-form' equivalent to
3205 * MathML expressions.  The approach taken by libSBML is to start with the
3206 * formula syntax defined by SBML Level&nbsp;1 (which in fact used a custom
3207 * text-string representation of formulas, and not MathML), and expand it to
3208 * include the functionality described above.  This formula syntax is based
3209 * mostly on C programming syntax, and may contain operators, function calls,
3210 * symbols, and white space characters.  The following table provides the
3211 * precedence rules for the different entities that may appear in formula
3212 * strings.
3213 <p>
3214 * <table border="0" width="95%"
3215       class="centered text-table normal-font alt-row-colors"
3216       style="padding-bottom: 0.5em">
3217 <tr style="background: lightgray; font-size: 14px;">
3218     <th align="left">Token</th>
3219     <th align="left">Operation</th>
3220     <th align="left">Class</th>
3221     <th>Precedence</th>
3222     <th align="left">Associates</th>
3223 </tr>
3224<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
3225<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
3226<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">8</td><td>left</td></tr>
3227<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">7</td><td>left</td></tr>
3228<tr><td><code>-, !</code></td><td>negation and boolean 'not'</td><td>unary</td><td align="center">6</td><td>right</td></tr>
3229<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align="center">5</td><td>left</td></tr>
3230<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align="center">4</td><td>left</td></tr>
3231<tr><td><code>==, &lt;, &gt;, &lt=, &gt=, !=</code></td><td>boolean equality, inequality, and comparison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
3232<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align="center">2</td><td>left</td></tr>
3233<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
3234
3235<caption class="top-caption">Expression operators and their precedence in the
3236"Level&nbsp;3" text-string format for mathematical expressions.
3237</caption>
3238</table>
3239
3240
3241 <p>
3242 * In the table above, <em>operand</em> implies the construct is an operand, 
3243 * <em>prefix</em> implies the operation is applied to the following arguments, 
3244 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
3245 * two arguments.  The values in the <b>Precedence</b> column show how the
3246 * order of different types of operation are determined.  For example, the
3247 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code>
3248 * because the @c * operator has higher precedence.  The
3249 * <b>Associates</b> column shows how the order of similar precedence
3250 * operations is determined; for example, <code>a && b || c</code> is
3251 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code>
3252 * operators are left-associative and have the same precedence.
3253 <p>
3254 * The function call syntax consists of a function name, followed by optional
3255 * white space, followed by an opening parenthesis token, followed by a
3256 * sequence of zero or more arguments separated by commas (with each comma
3257 * optionally preceded and/or followed by zero or more white space
3258 * characters), followed by a closing parenthesis token.  The function name
3259 * must be chosen from one of the pre-defined functions in SBML or a
3260 * user-defined function in the model.  The following table lists the names
3261 * of certain common mathematical functions; this table corresponds to
3262 * Table&nbsp;6 in the <a target='_blank'
3263 * href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML
3264 * Level&nbsp;1 Version&nbsp;2 specification</a> with additions based on the
3265 * functions added in SBML Level 2 and Level 3:
3266 <p>
3267 * <table border="0" width="95%" 
3268       class="centered text-table normal-font alt-row-colors">
3269 <tr>
3270     <th align="left" width="60">Name</th>
3271     <th align="left" width="75">Argument(s)</th>
3272     <th align="left">Formula or meaning</th>
3273     <th align="left" width="90">Argument Constraints</th>
3274     <th align="left" width="90">Result constraints</th>
3275 </tr>
3276<tr><td><code>abs</code></td>   
3277    <td><em>x</em></td> 
3278    <td>Absolute value of <em>x</em>.</td>
3279    <td></td>
3280    <td></td>
3281</tr>
3282<tr><td><code>acos</code>, <code>arccos</code></td>
3283    <td><em>x</em></td>
3284    <td>Arccosine of <em>x</em> in radians.</td>
3285    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
3286    <td>0 &le; <em>acos(x)</em> &le; &pi;</td>
3287</tr>
3288<tr><td><code>acosh</code>, <code>arccosh</code></td>
3289    <td><em>x</em></td>
3290    <td>Hyperbolic arccosine of <em>x</em> in radians.</td>
3291    <td></td>
3292    <td></td>
3293</tr>
3294<tr><td><code>acot</code>, <code>arccot</code></td>
3295    <td><em>x</em></td>
3296    <td>Arccotangent of <em>x</em> in radians.</td>
3297    <td></td>
3298    <td></td>
3299</tr>
3300<tr><td><code>acoth</code>, <code>arccoth</code></td>
3301    <td><em>x</em></td>
3302    <td>Hyperbolic arccotangent of <em>x</em> in radians.</td>
3303    <td></td>
3304    <td></td>
3305</tr>
3306<tr><td><code>acsc</code>, <code>arccsc</code></td>
3307    <td><em>x</em></td>
3308    <td>Arccosecant of <em>x</em> in radians.</td>
3309    <td></td>
3310    <td></td>
3311</tr>
3312<tr><td><code>acsch</code>, <code>arccsch</code></td>
3313    <td><em>x</em></td>
3314    <td>Hyperbolic arccosecant of <em>x</em> in radians.</td>
3315    <td></td>
3316    <td></td>
3317</tr>
3318<tr><td><code>asec</code>, <code>arcsec</code></td>
3319    <td><em>x</em></td>
3320    <td>Arcsecant of <em>x</em> in radians.</td>
3321    <td></td>
3322    <td></td>
3323</tr>
3324<tr><td><code>asech</code>, <code>arcsech</code></td>
3325    <td><em>x</em></td>
3326    <td>Hyperbolic arcsecant of <em>x</em> in radians.</td>
3327    <td></td>
3328    <td></td>
3329</tr>
3330<tr><td><code>asin</code>, <code>arcsin</code></td>
3331    <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td>
3332    <td>&ndash;1.0 &le; <em>x</em> &le; 1.0</td>
3333    <td>0 &le; <em>asin(x)</em> &le; &pi;</td>
3334</tr>
3335<tr><td><code>atan</code>, <code>arctan</code></td>
3336    <td><em>x</em></td>
3337    <td>Arctangent of <em>x</em> in radians.</td>
3338    <td></td>
3339    <td>0 &le; <em>atan(x)</em> &le; &pi;</td>
3340</tr>
3341<tr><td><code>atanh</code>, <code>arctanh</code></td>
3342    <td><em>x</em></td>
3343    <td>Hyperbolic arctangent of <em>x</em> in radians.</td>
3344    <td></td>
3345    <td></td>
3346</tr>
3347<tr><td><code>ceil</code>, <code>ceiling</code></td>
3348    <td><em>x</em></td>
3349    <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td>
3350    <td></td>
3351    <td></td>
3352</tr>
3353<tr><td><code>cos</code></td>
3354    <td><em>x</em></td>
3355    <td>Cosine of <em>x</em></td>
3356    <td></td>
3357    <td></td>
3358</tr>
3359<tr><td><code>cosh</code></td>
3360    <td><em>x</em></td>
3361    <td>Hyperbolic cosine of <em>x</em>.</td>
3362    <td></td>
3363    <td></td>
3364</tr>
3365<tr><td><code>cot</code></td>
3366    <td><em>x</em></td>
3367    <td>Cotangent of <em>x</em>.</td>
3368    <td></td>
3369    <td></td>
3370</tr>
3371<tr><td><code>coth</code></td>
3372    <td><em>x</em></td>
3373    <td>Hyperbolic cotangent of <em>x</em>.</td>
3374    <td></td>
3375    <td></td>
3376</tr>
3377<tr><td><code>csc</code></td>
3378    <td><em>x</em></td>
3379    <td>Cosecant of <em>x</em>.</td>
3380    <td></td>
3381    <td></td>
3382</tr>
3383<tr><td><code>csch</code></td>
3384    <td><em>x</em></td>
3385    <td>Hyperbolic cosecant of <em>x</em>.</td>
3386    <td></td>
3387    <td></td>
3388</tr>
3389<tr><td><code>delay</code></td>
3390    <td><em>x, y</em></td>
3391    <td>The value of <em>x</em> at <em>y</em> time units in the past.</td>
3392    <td></td>
3393    <td></td>
3394</tr>
3395<tr><td><code>factorial</code></td>
3396    <td><em>n</em></td>
3397    <td>The factorial of <em>n</em>. Factorials are defined by <em>n! = n*(n&ndash;1)* ... * 1</em>.</td>
3398    <td><em>n</em> must be an integer.</td>
3399    <td></td>
3400</tr>
3401<tr><td><code>exp</code></td>
3402    <td><em>x</em></td>
3403    <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td>
3404    <td></td>
3405    <td></td>
3406</tr>
3407<tr><td><code>floor</code></td>
3408    <td><em>x</em></td>
3409    <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td>
3410    <td></td>
3411    <td></td>
3412</tr>
3413<tr><td><code>ln</code></td>
3414    <td><em>x</em></td>
3415    <td>Natural logarithm of <em>x</em>.</td>
3416    <td><em>x</em> &gt; 0</td>
3417    <td></td>
3418</tr>
3419<tr><td><code>log</code></td>
3420    <td><em>x</em></td>
3421    <td>By default, the base 10 logarithm of <em>x</em>, but can be set to be the natural logarithm of <em>x</em>, or to be an illegal construct.</td>
3422    <td><em>x</em> &gt; 0</td>
3423    <td></td>
3424</tr>
3425<tr><td><code>log</code></td>
3426    <td><em>x, y</em></td>
3427    <td>The base <em>x</em> logarithm of <em>y</em>.</td>
3428    <td><em>y</em> &gt; 0</td>
3429    <td></td>
3430</tr>
3431<tr><td><code>log10</code></td>
3432    <td><em>x</em></td>
3433    <td>Base 10 logarithm of <em>x</em>.</td>
3434    <td><em>x</em> &gt; 0</td>
3435    <td></td>
3436</tr>
3437<tr><td><code>piecewise</code></td>
3438    <td><em>x1, y1, [x2, y2,] [...] [z]</em></td>
3439    <td>A piecewise function: if (<em>y1</em>), <em>x1</em>.  Otherwise, if (<em>y2</em>), <em>x2</em>, etc.  Otherwise, z. </td>
3440    <td><em>y1, y2, y3 [etc]</em> must be boolean</td>
3441    <td></td>
3442</tr>
3443<tr><td><code>pow</code>, <code>power</code> </td>
3444    <td><em>x, y</em></td>
3445    <td><em>x</em><sup><em> y</em></sup>.</td>
3446    <td></td>
3447    <td></td>
3448</tr>
3449<tr><td><code>root</code></td>
3450    <td><em>b, x</em></td>
3451    <td>The root base <em>b</em> of <em>x</em>.</td>
3452    <td></td>
3453    <td></td>
3454</tr>
3455<tr><td><code>sec</code></td>
3456    <td><em>x</em></td>
3457    <td>Secant of <em>x</em>.</td>
3458    <td></td>
3459    <td></td>
3460</tr>
3461<tr><td><code>sech</code></td>
3462    <td><em>x</em></td>
3463    <td>Hyperbolic secant of <em>x</em>.</td>
3464    <td></td>
3465    <td></td>
3466</tr>
3467<tr><td><code>sqr</code></td>
3468    <td><em>x</em></td>
3469    <td><em>x</em><sup><em>2</em></sup>.</td>
3470    <td></td>
3471    <td></td>
3472</tr>
3473<tr><td><code>sqrt</code></td>
3474    <td><em>x</em></td>
3475    <td>&radic;<em>x</em>.</td>
3476    <td><em>x</em> &gt; 0</td>
3477    <td><em>sqrt(x)</em> &ge; 0</td>
3478</tr>
3479<tr><td><code>sin</code></td>
3480    <td><em>x</em></td>
3481    <td>Sine of <em>x</em>.</td>
3482    <td></td>
3483    <td></td>
3484</tr>
3485<tr><td><code>sinh</code></td>
3486    <td><em>x</em></td>
3487    <td>Hyperbolic sine of <em>x</em>.</td>
3488    <td></td>
3489    <td></td>
3490</tr>
3491<tr><td><code>tan</code></td>
3492    <td><em>x</em></td>
3493    <td>Tangent of <em>x</em>.</td>
3494    <td>x &ne; n*&pi;/2, for odd integer <em>n</em></td>
3495    <td></td>
3496</tr>
3497<tr><td><code>tanh</code></td>
3498    <td><em>x</em></td>
3499    <td>Hyperbolic tangent of <em>x</em>.</td>
3500    <td></td>
3501    <td></td>
3502</tr>
3503<tr><td><code>and</code></td>
3504    <td><em>x, y, z...</em></td>
3505    <td>Boolean <em>and(x, y, z...)</em>: returns <code>true</code> if all of its arguments are true.  Note that <code>and</code> is an n-ary function, taking 0 or more arguments, and that <code>and()</code> returns <code>true</code>.</td>
3506    <td>All arguments must be boolean</td>
3507    <td></td>
3508</tr>
3509<tr><td><code>not</code></td>
3510    <td><em>x</em></td>
3511    <td>Boolean <em>not(x)</em></td>
3512    <td><em>x</em> must be boolean</td>
3513    <td></td>
3514</tr>
3515<tr><td><code>or</code></td>
3516    <td><em>x, y, z...</em></td>
3517    <td>Boolean <em>or(x, y, z...)</em>: returns <code>true</code> if at least one of its arguments is true.  Note that <code>or</code> is an n-ary function, taking 0 or more arguments, and that <code>or()</code> returns <code>false</code>.</td>
3518    <td>All arguments must be boolean</td>
3519    <td></td>
3520</tr>
3521<tr><td><code>xor</code></td>
3522    <td><em>x, y, z...</em></td>
3523    <td>Boolean <em>xor(x, y, z...)</em>: returns <code>true</code> if an odd number of its arguments is true.  Note that <code>xor</code> is an n-ary function, taking 0 or more arguments, and that <code>xor()</code> returns <code>false</code>.</td>
3524    <td>All arguments must be boolean</td>
3525    <td></td>
3526</tr>
3527<tr><td><code>eq</code></td>
3528    <td><em>x, y, z...</em></td>
3529    <td>Boolean <em>eq(x, y, z...)</em>: returns <code>true</code> if all arguments are equal.  Note that <code>eq</code> is an n-ary function, but must take 2 or more arguments.</td>
3530    <td></td>
3531    <td></td>
3532</tr>
3533<tr><td><code>geq</code></td>
3534    <td><em>x, y, z...</em></td>
3535    <td>Boolean <em>geq(x, y, z...)</em>: returns <code>true</code> if each argument is greater than or equal to the argument following it.  Note that <code>geq</code> is an n-ary function, but must take 2 or more arguments.</td>
3536    <td></td>
3537    <td></td>
3538</tr>
3539<tr><td><code>gt</code></td>
3540    <td><em>x, y, z...</em></td>
3541    <td>Boolean <em>gt(x, y, z...)</em>: returns <code>true</code> if each argument is greater than the argument following it.  Note that <code>gt</code> is an n-ary function, but must take 2 or more arguments.</td>
3542    <td></td>
3543    <td></td>
3544</tr>
3545<tr><td><code>leq</code></td>
3546    <td><em>x, y, z...</em></td>
3547    <td>Boolean <em>leq(x, y, z...)</em>: returns <code>true</code> if each argument is less than or equal to the argument following it.  Note that <code>leq</code> is an n-ary function, but must take 2 or more arguments.</td>
3548    <td></td>
3549    <td></td>
3550</tr>
3551<tr><td><code>lt</code></td>
3552    <td><em>x, y, z...</em></td>
3553    <td>Boolean <em>lt(x, y, z...)</em>: returns <code>true</code> if each argument is less than the argument following it.  Note that <code>lt</code> is an n-ary function, but must take 2 or more arguments.</td>
3554    <td></td>
3555    <td></td>
3556</tr>
3557<tr><td><code>neq</code></td>
3558    <td><em>x, y</em></td>
3559    <td>Boolean <em>x</em> != <em>y</em>: returns <code>true</code> unless x and y are equal.</td>
3560    <td></td>
3561    <td></td>
3562</tr>
3563<tr><td><code>plus</code></td>
3564    <td><em>x, y, z...</em></td>
3565    <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function.  Note that <code>plus</code> is an n-ary function taking 0 or more arguments, and that <code>plus()</code> returns <code>0</code>.</td>
3566    <td></td>
3567    <td></td>
3568</tr>
3569<tr><td><code>times</code></td>
3570    <td><em>x, y, z...</em></td>
3571    <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function.  Note that <code>times</code> is an n-ary function taking 0 or more arguments, and that <code>times()</code> returns <code>1</code>.</td>
3572    <td></td>
3573    <td></td>
3574</tr>
3575<tr><td><code>minus</code></td>
3576    <td><em>x, y</em></td>
3577    <td><em>x</em> &ndash; <em>y</em>.</td>
3578    <td></td>
3579    <td></td>
3580</tr>
3581<tr><td><code>divide</code></td>
3582    <td><em>x, y</em></td>
3583    <td><em>x</em> / <em>y</em>.</td>
3584    <td></td>
3585    <td></td>
3586</tr>
3587
3588<caption class="top-caption">Mathematical functions defined
3589in the "Level&nbsp;3" text-string formula syntax.</caption>
3590
3591</table>
3592
3593
3594 <p>
3595 * Parsing of the various MathML functions and constants are all
3596 * case-insensitive by default: function names such as <code>cos</code>,
3597 * <code>Cos</code> and <code>COS</code> are all parsed as the MathML cosine
3598 * operator, <code>&lt;cos&gt;</code>.  However, <em>when a {@link Model} object is
3599 * used</em> in conjunction with either
3600 * <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> or
3601 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>, any identifiers found in that model will be
3602 * parsed in a case-<em>sensitive</em> way.  For example, if a model contains
3603 * a {@link Species} having the identifier <code>Pi</code>, the parser will parse
3604 * &quot;<code>Pi</code>&quot; in the input as &quot;<code>&lt;ci&gt; Pi
3605 * &lt;/ci&gt;</code>&quot; but will continue to parse the symbols
3606 * &quot;<code>pi</code>&quot; and &quot;<code>PI</code>&quot; as
3607 * &quot;<code>&lt;pi&gt;</code>&quot;.
3608 <p>
3609 * As mentioned above, the manner in which the 'L3' versions of the formula
3610 * parser and formatter interpret the function &quot;<code>log</code>&quot;
3611 * can be changed.  To do so, callers should use the function
3612 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a> and pass it an appropriate {@link L3ParserSettings}
3613 * object.  By default, unlike the SBML Level&nbsp;1 parser implemented by
3614 * <a href='libsbml.html#parseFormula(java.lang.String)'><code>libsbml.parseFormula(String)</code></a>, the string
3615 * &quot;<code>log</code>&quot; is interpreted as the base&nbsp;10 logarithm,
3616 * and <em>not</em> as the natural logarithm.  However, you can change the
3617 * interpretation to be base-10 log, natural log, or as an error; since the
3618 * name 'log' by itself is ambiguous, you require that the parser uses 
3619 * <code>log10</code> or <code>ln</code> instead, which are more clear.  Please refer to
3620 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.
3621 <p>
3622 * In addition, the following symbols will be translated to their MathML
3623 * equivalents, if no symbol with the same <code>SId</code> identifier string exists
3624 * in the {@link Model} object provided:
3625 <p>
3626 * <table border="0" width="95%"
3627       class="centered text-table normal-font alt-row-colors">
3628 <tr>
3629     <th align="left" width="60">Name</th>
3630     <th align="left" width="250">Meaning</th>
3631     <th align="left">MathML</th>
3632 </tr>
3633<tr><td><code>true</code></td>   
3634    <td>The boolean value <code>true</code></td>
3635    <td><code>&lt;true/&gt;</code></td>
3636</tr>
3637<tr><td><code>false</code></td>   
3638    <td>The boolean value <code>false</code></td>
3639    <td><code>&lt;false/&gt;</code></td>
3640</tr>
3641<tr><td><code>pi</code></td>   
3642    <td>The mathematical constant pi</td>
3643    <td><code>&lt;pi/&gt;</code></td>
3644</tr>
3645<tr><td><code>avogadro</code></td>   
3646    <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td>
3647    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"&gt; avogadro &lt;/csymbol/&gt;</code></td>
3648</tr>
3649<tr><td><code>time</code></td>   
3650    <td>Simulation time as defined in SBML</td>
3651    <td><code style="letter-spacing: -1px">&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"&gt; time &lt;/csymbol/&gt;</code></td>
3652</tr>
3653<tr><td><code>inf</code> or <code>infinity</code></td>   
3654    <td>The mathematical constant "infinity"</td>
3655    <td><code>&lt;infinity/&gt;</code></td>
3656</tr>
3657<tr><td><code>nan</code> or <code>notanumber</code></td>   
3658    <td>The mathematical concept "not a number"</td>
3659    <td><code>&lt;notanumber/&gt;</code></td>
3660</tr>
3661
3662<caption class="top-caption">Mathematical symbols defined
3663in the "Level&nbsp;3" text-string formula syntax.
3664</caption>
3665</table>
3666
3667 <p>
3668 * Again, as mentioned above, whether the string
3669 * &quot;<code>avogadro</code>&quot; is parsed as an AST node of type
3670 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or
3671 * {@link libsbmlConstants#AST_NAME AST_NAME} is configurable; use the version of
3672 * the parser function called <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>.  This Avogadro-related
3673 * functionality is provided because SBML Level&nbsp;2 models may not use
3674 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes.
3675 <p>
3676 * For more details about the parser, please see the definition of
3677 * {@link L3ParserSettings} and <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>.
3678 <p>
3679 * @see <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>
3680 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
3681 * @see <a href='libsbml.html#formulaToL3StringWithSettings(org.sbml.libsbml.ASTNode, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.formulaToL3StringWithSettings(ASTNode, L3ParserSettings)</code></a>
3682 * @see L3ParserSettings
3683 */ public
3684 static L3ParserSettings getDefaultL3ParserSettings() {
3685    long cPtr = libsbmlJNI.getDefaultL3ParserSettings();
3686    return (cPtr == 0) ? null : new L3ParserSettings(cPtr, true);
3687  }
3688
3689  
3690/**
3691 * Returns the last error reported by the 'L3' mathematical formula parser.
3692 <p>
3693 * If the functions <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>,
3694 * <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>, or <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a> return <code>null</code>, an error is set internally.
3695 * This function allows callers to retrieve information about the error.
3696 <p>
3697 * @return a string describing the error that occurred.  This will contain
3698 * the input string the parser was trying to parse, the character it had
3699 * parsed when it encountered the error, and a description of the error.
3700 <p>
3701 * @see <a href='libsbml.html#parseL3Formula(java.lang.String)'><code>libsbml.parseL3Formula(String)</code></a>
3702 * @see <a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'><code>libsbml.parseL3FormulaWithSettings(String, L3ParserSettings)</code></a>
3703 * @see <a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'><code>libsbml.parseL3FormulaWithModel(String, Model)</code></a>
3704 * @see <a href='libsbml.html#getDefaultL3ParserSettings()'><code>libsbml.getDefaultL3ParserSettings()</code></a>
3705 */ public
3706 static String getLastParseL3Error() {
3707    return libsbmlJNI.getLastParseL3Error();
3708  }
3709
3710  
3711/** * @internal */ public
3712 static void SBML_deleteL3Parser() {
3713    libsbmlJNI.SBML_deleteL3Parser();
3714  }
3715
3716  
3717/**
3718 */ public
3719 static String GroupKind_toString(int gk) {
3720    return libsbmlJNI.GroupKind_toString(gk);
3721  }
3722
3723  
3724/**
3725 */ public
3726 static int GroupKind_fromString(String code) {
3727    return libsbmlJNI.GroupKind_fromString(code);
3728  }
3729
3730  
3731/**
3732 */ public
3733 static int GroupKind_isValid(int gk) {
3734    return libsbmlJNI.GroupKind_isValid(gk);
3735  }
3736
3737  
3738/**
3739 */ public
3740 static int GroupKind_isValidString(String code) {
3741    return libsbmlJNI.GroupKind_isValidString(code);
3742  }
3743
3744  
3745/**
3746 * takes an annotation that has been read into the model
3747 * identifies the RDF elements
3748 * and creates a List of Layouts from the annotation
3749 */ public
3750 static void parseLayoutAnnotation(XMLNode annotation, ListOfLayouts layouts) {
3751    libsbmlJNI.parseLayoutAnnotation(XMLNode.getCPtr(annotation), annotation, ListOfLayouts.getCPtr(layouts), layouts);
3752  }
3753
3754  
3755/**
3756 * Takes an {@link XMLNode} and tries to find the layout annotation node and deletes it if it was found.
3757 */ public
3758 static XMLNode deleteLayoutAnnotation(XMLNode pAnnotation) {
3759    long cPtr = libsbmlJNI.deleteLayoutAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation);
3760    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
3761  }
3762
3763  
3764/**
3765 * Creates an {@link XMLNode} that represents the layouts of the model from the given {@link Model} object.
3766 */ public
3767 static XMLNode parseLayouts(Model pModel) {
3768    long cPtr = libsbmlJNI.parseLayouts(Model.getCPtr(pModel), pModel);
3769    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
3770  }
3771
3772  
3773/**
3774 * takes an annotation that has been read into the species reference
3775 * identifies the id elements and set the id of the species reference
3776 */ public
3777 static void parseSpeciesReferenceAnnotation(XMLNode annotation, SimpleSpeciesReference sr) {
3778    libsbmlJNI.parseSpeciesReferenceAnnotation(XMLNode.getCPtr(annotation), annotation, SimpleSpeciesReference.getCPtr(sr), sr);
3779  }
3780
3781  
3782/**
3783 * Takes an {@link XMLNode} and tries to find the layoutId annotation node and deletes it if it was found.
3784 */ public
3785 static XMLNode deleteLayoutIdAnnotation(XMLNode pAnnotation) {
3786    long cPtr = libsbmlJNI.deleteLayoutIdAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation);
3787    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
3788  }
3789
3790  
3791/**
3792 * Creates an {@link XMLNode} that represents the layoutId annotation of the species reference from the given {@link SpeciesReference} object.
3793 */ public
3794 static XMLNode parseLayoutId(SimpleSpeciesReference sr) {
3795    long cPtr = libsbmlJNI.parseLayoutId(SimpleSpeciesReference.getCPtr(sr), sr);
3796    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
3797  }
3798
3799}