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