001/* ----------------------------------------------------------------------------
002 * This file was automatically generated by SWIG (http://www.swig.org).
003 * Version 2.0.12
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("fbc"))
058        return new FbcExtension(cPtr, owner);
059    
060
061    if (pkgName.equals("layout"))
062        return new LayoutExtension(cPtr, owner);
063    
064
065    if (pkgName.equals("render"))
066        return new RenderExtension(cPtr, owner);
067    
068
069    if (pkgName.equals("groups"))
070        return new GroupsExtension(cPtr, owner);
071    
072
073    if (pkgName.equals("comp"))
074        return new CompExtension(cPtr, owner);
075    
076
077    if (pkgName.equals("qual"))
078        return new QualExtension(cPtr, owner);
079    
080
081    return new SBMLExtension(cPtr,owner);
082  }     
083        
084  /**
085   * SBMLExtension derived classes must override this method
086   * @internal
087   */
088  public static SBasePlugin DowncastSBasePlugin(long cPtr, boolean owner)
089  {
090    if (cPtr == 0) return null;
091
092    SBasePlugin sbp = new SBasePlugin(cPtr,false);
093    String pkgName = sbp.getPackageName();
094
095    SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName);
096    if (sbmlext != null)
097    {
098      return sbmlext.DowncastSBasePlugin(cPtr,owner);
099    }
100    return new SBasePlugin(cPtr,owner);
101  }
102
103  /**
104   * @internal
105   */
106  public static SBMLNamespaces DowncastSBMLNamespaces(long cPtr, boolean owner)
107  {
108    if (cPtr == 0) return null;
109                
110    SBMLNamespaces sbn = new SBMLNamespaces(cPtr, false);
111    if (sbn != null)
112    {
113      XMLNamespaces ns = sbn.getNamespaces();
114
115
116    
117    if (ns.hasURI(FbcExtension.getXmlnsL3V1V1()))
118    {
119        return new FbcPkgNamespaces(cPtr, owner);
120    }
121    
122
123    
124    if (ns.hasURI(QualExtension.getXmlnsL3V1V1()))
125    {
126        return new QualPkgNamespaces(cPtr, owner);
127    }
128    
129
130    
131    if (ns.hasURI(GroupsExtension.getXmlnsL3V1V1()))
132    {
133        return new GroupsPkgNamespaces(cPtr, owner);
134    }
135    
136
137    
138    if (ns.hasURI(CompExtension.getXmlnsL3V1V1()))
139    {
140        return new CompPkgNamespaces(cPtr, owner);
141    }
142    
143
144    
145    if (ns.hasURI(RenderExtension.getXmlnsL3V1V1()) || ns.hasURI(RenderExtension.getXmlnsL2()))
146    {
147        return new RenderPkgNamespaces(cPtr, owner);
148    }
149    
150
151    
152    if (ns.hasURI(LayoutExtension.getXmlnsL3V1V1()) || ns.hasURI(LayoutExtension.getXmlnsL2()))
153    {
154        return new LayoutPkgNamespaces(cPtr, owner);
155    }
156    
157                              
158    }
159    return new SBMLNamespaces(cPtr, owner);
160  }     
161  
162  /**
163   * Internal method.
164   *
165   * @internal
166   */
167  public static SBase DowncastSBase(long cPtr, boolean owner)
168  {
169    if (cPtr == 0) return null;
170
171    SBase sb = new SBase(cPtr,false);
172    String pkgName = sb.getPackageName();
173    if (pkgName.equals("core"))
174    {
175      switch( sb.getTypeCode() )
176      {
177        case libsbmlConstants.SBML_COMPARTMENT:
178          return new Compartment(cPtr, owner);
179  
180        case libsbmlConstants.SBML_COMPARTMENT_TYPE:
181          return new CompartmentType(cPtr, owner);
182  
183        case libsbmlConstants.SBML_CONSTRAINT:
184          return new Constraint(cPtr, owner);
185  
186        case libsbmlConstants.SBML_DOCUMENT:
187          return new SBMLDocument(cPtr, owner);
188  
189        case libsbmlConstants.SBML_DELAY:
190          return new Delay(cPtr, owner);
191  
192        case libsbmlConstants.SBML_EVENT:
193          return new Event(cPtr, owner);
194
195        case libsbmlConstants.SBML_EVENT_ASSIGNMENT:
196          return new EventAssignment(cPtr, owner);
197
198        case libsbmlConstants.SBML_FUNCTION_DEFINITION:
199          return new FunctionDefinition(cPtr, owner);
200  
201        case libsbmlConstants.SBML_INITIAL_ASSIGNMENT:
202          return new InitialAssignment(cPtr, owner);
203
204        case libsbmlConstants.SBML_KINETIC_LAW:
205          return new KineticLaw(cPtr, owner);
206
207        case libsbmlConstants.SBML_LIST_OF:
208          String name = sb.getElementName();
209          if(name.equals("listOf")){
210            return new ListOf(cPtr, owner);
211          }
212          else if(name.equals("listOfCompartments")){
213            return new ListOfCompartments(cPtr, owner);
214          }
215          else if(name.equals("listOfCompartmentTypes")){
216            return new ListOfCompartmentTypes(cPtr, owner);
217          }
218          else if(name.equals("listOfConstraints")){
219            return new ListOfConstraints(cPtr, owner);
220          }
221          else if(name.equals("listOfEvents")){
222            return new ListOfEvents(cPtr, owner);
223          }
224          else if(name.equals("listOfEventAssignments")){
225            return new ListOfEventAssignments(cPtr, owner);
226          }
227          else if(name.equals("listOfFunctionDefinitions")){
228            return new ListOfFunctionDefinitions(cPtr, owner);
229          }
230          else if(name.equals("listOfInitialAssignments")){
231            return new ListOfInitialAssignments(cPtr, owner);
232          }
233          else if(name.equals("listOfParameters")){
234            return new ListOfParameters(cPtr, owner);
235          }
236          else if(name.equals("listOfLocalParameters")){
237            return new ListOfLocalParameters(cPtr, owner);
238          }
239          else if(name.equals("listOfReactions")){
240            return new ListOfReactions(cPtr, owner);
241          }
242          else if(name.equals("listOfRules")){
243            return new ListOfRules(cPtr, owner);
244          }
245          else if(name.equals("listOfSpecies")){
246            return new ListOfSpecies(cPtr, owner);
247          }
248          else if(name.equals("listOfUnknowns")){
249            return new ListOfSpeciesReferences(cPtr, owner);
250          }
251          else if(name.equals("listOfReactants")){
252            return new ListOfSpeciesReferences(cPtr, owner);
253          }
254          else if(name.equals("listOfProducts")){
255            return new ListOfSpeciesReferences(cPtr, owner);
256          }
257          else if(name.equals("listOfModifiers")){
258            return new ListOfSpeciesReferences(cPtr, owner);
259          }
260          else if(name.equals("listOfSpeciesTypes")){
261            return new ListOfSpeciesTypes(cPtr, owner);
262          }
263          else if(name.equals("listOfUnits")){
264            return new ListOfUnits(cPtr, owner);
265          }
266          else if(name.equals("listOfUnitDefinitions")){
267            return new ListOfUnitDefinitions(cPtr, owner);
268          }
269          return new ListOf(cPtr, owner);
270
271        case libsbmlConstants.SBML_MODEL:
272          return new Model(cPtr, owner);
273
274        case libsbmlConstants.SBML_PARAMETER:
275          return new Parameter(cPtr, owner);
276
277      case libsbmlConstants.SBML_PRIORITY:
278        return new Priority(cPtr, owner);
279
280      case libsbmlConstants.SBML_LOCAL_PARAMETER:
281        return new LocalParameter(cPtr, owner);
282
283        case libsbmlConstants.SBML_REACTION:
284          return new Reaction(cPtr, owner);
285
286        case libsbmlConstants.SBML_SPECIES:
287          return new Species(cPtr, owner);
288
289        case libsbmlConstants.SBML_SPECIES_REFERENCE:
290          return new SpeciesReference(cPtr, owner);
291
292        case libsbmlConstants.SBML_MODIFIER_SPECIES_REFERENCE:
293          return new ModifierSpeciesReference(cPtr, owner);
294
295        case libsbmlConstants.SBML_SPECIES_TYPE:
296          return new SpeciesType(cPtr, owner);
297
298        case libsbmlConstants.SBML_TRIGGER:
299          return new Trigger(cPtr, owner);
300
301        case libsbmlConstants.SBML_UNIT_DEFINITION:
302          return new UnitDefinition(cPtr, owner);
303
304        case libsbmlConstants.SBML_UNIT:
305          return new Unit(cPtr, owner);
306
307        case libsbmlConstants.SBML_ALGEBRAIC_RULE:
308          return new AlgebraicRule(cPtr, owner);
309
310        case libsbmlConstants.SBML_ASSIGNMENT_RULE:
311          return new AssignmentRule(cPtr, owner);
312
313        case libsbmlConstants.SBML_RATE_RULE:
314          return new RateRule(cPtr, owner);
315
316        case libsbmlConstants.SBML_STOICHIOMETRY_MATH:
317          return new StoichiometryMath(cPtr, owner);
318
319        default:
320          return new SBase(cPtr, owner);
321      }
322    }
323    else
324    {
325      SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName);
326      if (sbmlext != null)
327      {
328        return sbmlext.DowncastSBase(cPtr,owner);
329      }
330    }
331    return new SBase(cPtr, owner);
332  }
333  
334
335 
336  public static ASTBase DowncastASTBase(long cPtr, boolean owner)
337  {
338    if (cPtr == 0) return null;
339
340    ASTBase ab = new ASTBase(cPtr,false);
341    switch( ab.getTypeCode() )
342    {
343        default:
344        case libsbmlConstants.AST_TYPECODE_BASE:
345          return new ASTBase(cPtr, owner);
346          /*
347        case libsbmlConstants.AST_TYPECODE_CN_BASE:
348          return new ASTCnBase(cPtr, owner);
349        case libsbmlConstants.AST_TYPECODE_FUNCTION_BASE:
350          return new ASTFunctionBase(cPtr, owner);
351        case libsbmlConstants.AST_TYPECODE_NUMBER:
352          return new ASTNumber(cPtr, owner);
353        case libsbmlConstants.AST_TYPECODE_CN_INTEGER:
354          return new ASTCnIntegerNode(cPtr, owner);
355        case libsbmlConstants.AST_TYPECODE_CN_EXPONENTIAL:
356          return new ASTCnExponentialNode(cPtr, owner);
357        case libsbmlConstants.AST_TYPECODE_CN_RATIONAL:
358          return new ASTCnRationalNode(cPtr, owner);
359        case libsbmlConstants.AST_TYPECODE_CN_REAL:
360          return new ASTCnRealNode(cPtr, owner);
361        case libsbmlConstants.AST_TYPECODE_CSYMBOL:
362          return new ASTCSymbol(cPtr, owner);
363        case libsbmlConstants.AST_TYPECODE_CSYMBOL_AVOGADRO:
364          return new ASTCSymbolAvogadroNode(cPtr, owner);
365        case libsbmlConstants.AST_TYPECODE_CSYMBOL_DELAY:
366          return new ASTCSymbolDelayNode(cPtr, owner);
367        case libsbmlConstants.AST_TYPECODE_CSYMBOL_TIME:
368          return new ASTCSymbolTimeNode(cPtr, owner);
369        case libsbmlConstants.AST_TYPECODE_FUNCTION:
370          return new ASTFunction(cPtr, owner);
371        case libsbmlConstants.AST_TYPECODE_FUNCTION_UNARY:
372          return new ASTUnaryFunctionNode(cPtr, owner);
373        case libsbmlConstants.AST_TYPECODE_FUNCTION_BINARY:
374          return new ASTBinaryFunctionNode(cPtr, owner);
375        case libsbmlConstants.AST_TYPECODE_FUNCTION_NARY:
376          return new ASTNaryFunctionNode(cPtr, owner);
377        case libsbmlConstants.AST_TYPECODE_FUNCTION_PIECEWISE:
378          return new ASTPiecewiseFunctionNode(cPtr, owner);
379        case libsbmlConstants.AST_TYPECODE_FUNCTION_LAMBDA:
380          return new ASTLambdaFunctionNode(cPtr, owner);
381        case libsbmlConstants.AST_TYPECODE_FUNCTION_CI:
382          return new ASTCiFunctionNode(cPtr, owner);
383        case libsbmlConstants.AST_TYPECODE_FUNCTION_SEMANTIC:
384          return new ASTSemanticsNode(cPtr, owner);
385        case libsbmlConstants.AST_TYPECODE_FUNCTION_QUALIFIER:
386          return new ASTQualifierNode(cPtr, owner);*/
387        case libsbmlConstants.AST_TYPECODE_ASTNODE:
388          return new ASTNode(cPtr, owner);
389
390    }   
391    //return new ASTBase(cPtr, owner);
392  }
393  
394
395
396   static String getAbsolutePath(String filename)
397   {
398     java.io.File file = new java.io.File(filename);
399     return file.getAbsolutePath();
400   }
401
402
403  /**
404    * Stream handle for low-level C++ standard output stream.
405    * <p>
406    * A few libSBML methods accept an argument for indicating where to send
407    * text string output.  An example is the {@link
408    * SBMLDocument#printErrors} method.  However, the methods use C++ style
409    * streams and not Java stream objects.  The OStream object class in the
410    * libSBML Java interface provides a wrapper for the underlying C++
411    * streams.  The present object (cout) is a static final variable that
412    * can be used directly from your code.  An example use might be
413    * something like this:
414    * <p>
415    * <div class="fragment"><pre class="fragment">
416    * SBMLDocument document = libsbml.readSBML("somefile.xml");
417    * if (document.getNumErrors() > 0)
418    * {
419    *     document.printErrors(libsbml.cout);
420    *     println("Please correct the above problems first.");
421    *     System.exit(1);
422    * }</div>
423    *
424    * @see #cerr
425    * @see #clog
426    */
427  public final static OStream cout;
428
429
430  /**
431    * Stream handle for low-level C++ standard error stream.
432    * <p>
433    * A few libSBML methods accept an argument for indicating where to send
434    * text string output.  An example is the {@link
435    * SBMLDocument#printErrors} method.  However, the methods use C++ style
436    * streams and not Java stream objects.  The OStream object class in the
437    * libSBML Java interface provides a wrapper for the underlying C++
438    * streams.  The present object (cerr) is a static final variable that
439    * can be used directly from your code.  An example use might be
440    * something like this:
441    * <p>
442    * <div class="fragment"><pre class="fragment">
443    * SBMLDocument document = libsbml.readSBML("somefile.xml");
444    * if (document.getNumErrors() > 0)
445    * {
446    *     document.printErrors(libsbml.cerr);
447    *     println("Please correct the above problems first.");
448    *     System.exit(1);
449    * }</div>
450    * <p>
451    * By default, most operating systems have have their standard error and
452    * logging output streams directed to the console/terminal, and this is
453    * where text messages will be shown.  This can usually be redirected
454    * elsewhere, although how to do this depends on the specific environment
455    * where the program is running.
456    *
457    * @see #cout
458    * @see #clog
459    */
460  public final static OStream cerr;
461
462
463  /**
464    * Stream handle for low-level C++ standard logging stream.
465    * <p>
466    * A few libSBML methods accept an argument for indicating where to send
467    * text string output.  An example is the {@link
468    * SBMLDocument#printErrors} method.  However, the methods use C++ style
469    * streams and not Java stream objects.  The OStream object class in the
470    * libSBML Java interface provides a wrapper for the underlying C++
471    * streams.  The present object (clog) is a static final variable that
472    * can be used directly from your code.  An example use might be
473    * something like this:
474    * <p>
475    * <div class="fragment"><pre class="fragment">
476    * SBMLDocument document = libsbml.readSBML("somefile.xml");
477    * if (document.getNumErrors() > 0)
478    * {
479    *     document.printErrors(libsbml.clog);
480    *     println("Please correct the above problems first.");
481    *     System.exit(1);
482    * }</div>
483    * <p>
484    * By default, most operating systems have have their standard error and
485    * logging output streams directed to the console/terminal, and this is
486    * where text messages will be shown.  This can usually be redirected
487    * elsewhere, although how to do this depends on the specific environment
488    * where the program is running.
489    *
490    * @see #cout
491    * @see #cerr
492    */
493  public final static OStream clog;
494
495  static {
496    cout = new OStream(OStream.COUT); 
497    cerr = new OStream(OStream.CERR); 
498    clog = new OStream(OStream.CLOG); 
499  }
500
501  /**
502   * This private constructor does nothing and never invoked.
503   * The purpose of this constuctor is to hide a default constructor of this 
504   * class in javadoc documentation.
505   */
506  private libsbml() {}
507
508
509  
510/**
511 * Returns the version number of this copy of libSBML as an integer.
512 <p>
513 * @return the libSBML version as an integer; version 1.2.3 becomes 10203.
514 */ public
515 static int getLibSBMLVersion() {
516    return libsbmlJNI.getLibSBMLVersion();
517  }
518
519  
520/**
521 * Returns the version number of this copy of libSBML as a string.
522 <p>
523 * @return the libSBML version as a string; version 1.2.3 becomes
524 * '1.2.3'.
525 <p>
526 * @see #getLibSBMLVersionString()
527 */ public
528 static String getLibSBMLDottedVersion() {
529    return libsbmlJNI.getLibSBMLDottedVersion();
530  }
531
532  
533/**
534 * Returns the version number of this copy of libSBML as a string without
535 * periods.
536 <p>
537 * @return the libSBML version as a string: version 1.2.3 becomes '10203'.
538 <p>
539 * @see #getLibSBMLDottedVersion()
540 */ public
541 static String getLibSBMLVersionString() {
542    return libsbmlJNI.getLibSBMLVersionString();
543  }
544
545  
546/**
547 * Returns an indication whether libSBML has been compiled with
548 * against a specific library. 
549 <p>
550 * @param option the library to test against, this can be one of
551 *        'expat', 'libxml', 'xerces-c', 'bzip2', 'zip'
552 <p>
553 * @return 0 in case the libSBML has not been compiled against 
554 *         that library and non-zero otherwise (for libraries 
555 *         that define an integer version number that number will 
556 *         be returned).
557 <p>
558 * @see #getLibSBMLDependencyVersionOf(String option)
559 */ public
560 static int isLibSBMLCompiledWith(String option) {
561    return libsbmlJNI.isLibSBMLCompiledWith(option);
562  }
563
564  
565/**
566 * Returns the version string for the dependency library used. 
567 <p>
568 * @param option the library for which the version
569 *        should be retrieved, this can be one of
570 *        'expat', 'libxml', 'xerces-c', 'bzip2', 'zip'
571 <p>
572 * @return null in case libSBML has not been compiled against 
573 *         that library and a version string otherwise.
574 <p>
575 * @see #isLibSBMLCompiledWith(String option)
576 */ public
577 static String getLibSBMLDependencyVersionOf(String option) {
578    return libsbmlJNI.getLibSBMLDependencyVersionOf(option);
579  }
580
581  
582/**
583 * This method takes an SBML operation return value and returns a string representing
584 * the code.
585 <p>
586 * @param returnValue the operation return value to convert to a string
587 <p>
588 * @return a human readable name for the given
589 * operation return value .
590 <p>
591 * @note The caller does not own the returned string and is therefore not
592 * allowed to modify it.
593 */ public
594 static String OperationReturnValue_toString(int returnValue) {
595    return libsbmlJNI.OperationReturnValue_toString(returnValue);
596  }
597
598  
599/**
600 * Reads an SBML document from the given file <code>filename</code>.
601 <p>
602 * If <code>filename</code> does not exist, or it is not an SBML file, an error will
603 * be logged in the error log of the {@link SBMLDocument} object returned by this
604 * method.  Calling programs can inspect this error log to determine
605 * the nature of the problem.  Please refer to the definition of
606 * SBMLDocument_t for more information about the error reporting mechanism.
607 <p>
608 * <code>
609 *   SBMLReader_t   *sr;
610
611 *   SBMLDocument_t *d;
612 <p>
613 *   sr = SBMLReader_create();
614 <p>
615 *   d = SBMLReader_readSBML(reader, filename);
616 <p>
617 *   if (SBMLDocument_getNumErrors(d) > 0)
618
619 *   {
620
621 *     if (XMLError_getId(SBMLDocument_getError(d, 0))
622 *                                           == SBML_READ_ERROR_FILE_NOT_FOUND)
623
624 *     if (XMLError_getId(SBMLDocument_getError(d, 0))
625 *                                           == SBML_READ_ERROR_NOT_SBML)
626
627 *   }
628
629 * </code>
630 <p>
631 * If the filename ends with @em .gz, the file will be read as a <em>gzip</em> file.
632 * Similary, if the filename ends with @em .zip or @em .bz2, the file will be
633 * read as a <em>zip</em> or <em>bzip2</em> file, respectively. Otherwise, the fill will be
634 * read as an uncompressed file.
635 * If the filename ends with @em .zip, only the first file in the archive will
636 * be read if the zip archive contains two or more files.
637 <p>
638 * To read a gzip/zip file, underlying libSBML needs to be linked with zlib
639 * at compile time. Also, underlying libSBML needs to be linked with bzip2 
640 * to read a bzip2 file. File unreadable error will be logged if a compressed 
641 * file name is given and underlying libSBML is not linked with the corresponding 
642 * required library.
643 * SBMLReader_hasZlib() and SBMLReader_hasBzip2() can be used to check 
644 * whether libSBML is linked with each library.
645 <p>
646 * @return a pointer to the {@link SBMLDocument} read.
647 */ public
648 static SBMLDocument readSBML(String filename) {
649    long cPtr = libsbmlJNI.readSBML(libsbml.getAbsolutePath(filename));
650    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
651  }
652
653  
654/**
655 * Reads an SBML document from the given file <code>filename</code>.
656 <p>
657 * If <code>filename</code> does not exist, or it is not an SBML file, an error will
658 * be logged in the error log of the {@link SBMLDocument} object returned by this
659 * method.  Calling programs can inspect this error log to determine
660 * the nature of the problem.  Please refer to the definition of
661 * SBMLDocument_t for more information about the error reporting mechanism.
662 <p>
663 <p>
664 * <code>
665 *   SBMLReader_t   *sr;
666
667 *   SBMLDocument_t *d;
668 <p>
669 *   sr = SBMLReader_create();
670 <p>
671 *   d = SBMLReader_readSBML(reader, filename);
672 <p>
673 *   if (SBMLDocument_getNumErrors(d) > 0)
674
675 *   {
676
677 *     if (XMLError_getId(SBMLDocument_getError(d, 0))
678 *                                           == SBML_READ_ERROR_FILE_NOT_FOUND)
679
680 *     if (XMLError_getId(SBMLDocument_getError(d, 0))
681 *                                           == SBML_READ_ERROR_NOT_SBML)
682
683 *   }
684
685 * </code>
686 <p>
687 * If the filename ends with @em .gz, the file will be read as a <em>gzip</em> file.
688 * Similary, if the filename ends with @em .zip or @em .bz2, the file will be
689 * read as a <em>zip</em> or <em>bzip2</em> file, respectively. Otherwise, the fill will be
690 * read as an uncompressed file.
691 * If the filename ends with @em .zip, only the first file in the archive will
692 * be read if the zip archive contains two or more files.
693 <p>
694 * To read a gzip/zip file, underlying libSBML needs to be linked with zlib
695 * at compile time. Also, underlying libSBML needs to be linked with bzip2 
696 * to read a bzip2 file. File unreadable error will be logged if a compressed 
697 * file name is given and underlying libSBML is not linked with the corresponding 
698 * required library.
699 * SBMLReader_hasZlib() and SBMLReader_hasBzip2() can be used to check 
700 * whether libSBML is linked with each library.
701 <p>
702 * @return a pointer to the {@link SBMLDocument} read.
703 */ public
704 static SBMLDocument readSBMLFromFile(String filename) {
705    long cPtr = libsbmlJNI.readSBMLFromFile(libsbml.getAbsolutePath(filename));
706    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
707  }
708
709  
710/**
711 * Reads an SBML document from the given XML string <code>xml</code>.
712 <p>
713 * If the string does not begin with XML declaration,
714 *<div class='fragment'><pre class='fragment'>
715&lt;?xml version='1.0' encoding='UTF-8'?&gt;
716</pre></div>
717 <p>
718 * an XML declaration string will be prepended.
719 <p>
720 * This method will report an error if the given string <code>xml</code> is not SBML.
721 * The error will be logged in the error log of the SBMLDocument_t structure
722 * returned by this method.  Calling programs can inspect this error log to
723 * determine the nature of the problem.  Please refer to the definition of
724 * {@link SBMLDocument} for more information about the error reporting mechanism.
725 <p>
726 * @return a pointer to the SBMLDocument_t read.
727 <p>
728 * @note When using this method to read an {@link SBMLDocument} that uses 
729 * the SBML L3 Hierarchical {@link Model} Composition package (comp) the
730 * document location cannot be set automatically. Thus, if the model
731 * contains references to ExternalModelDefinitions, it will be necessary
732 * to manually set the document URI location (setLocationURI) in order 
733 * to facilitate resolving these models.
734 */ public
735 static SBMLDocument readSBMLFromString(String xml) {
736    long cPtr = libsbmlJNI.readSBMLFromString(xml);
737    return (cPtr == 0) ? null : new SBMLDocument(cPtr, true);
738  }
739
740  
741/**
742 * Writes the given SBML document <code>d</code> to the file named by <code>filename</code>.
743 * This convenience function is functionally equivalent to:
744 <p>
745 *   SBMLWriter_writeSBML(SBMLWriter_create(), d, filename);
746 <p>
747 * If the given filename ends with the suffix <code>&quot;.gz&quot;</code>
748(for example, <code>&quot;myfile.xml.gz&quot;</code>), libSBML assumes the
749caller wants the file to be written compressed in <em>gzip</em> format.
750Similarly, if the given filename ends with <code>&quot;.zip&quot;</code> or
751<code>&quot;.bz2&quot;</code>, libSBML assumes the caller wants the file to
752be compressed in <em>zip</em> or <em>bzip2</em> format (respectively).
753Files whose names lack these suffixes will be written uncompressed.
754<em>Special considerations for the zip format</em>: If the given filename
755ends with <code>&quot;.zip&quot;</code>, the file placed in the zip archive
756will have the suffix <code>&quot;.xml&quot;</code> or
757<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
758will be named <code>&quot;test.xml&quot;</code> if the given filename is
759<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
760Similarly, the filename in the archive will be
761<code>&quot;test.sbml&quot;</code> if the given filename is
762<code>&quot;test.sbml.zip&quot;</code>.
763
764 <p>
765 * @param d the {@link SBMLDocument} object to be written out in XML format
766 <p>
767 * @param filename a string giving the path to a file where the XML
768 * content is to be written.
769 <p>
770 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be
771 * written.  Some possible reasons for failure include (a) being unable to
772 * open the file, and (b) using a filename that indicates a compressed SBML
773 * file (i.e., a filename ending in <code>&quot;.zip&quot;</code> or
774 * similar) when the compression functionality has not been enabled in
775 * the underlying copy of libSBML.
776 <p>
777 * @see SBMLWriter#hasZlib()
778 * @see SBMLWriter#hasBzip2()
779 */ public
780 static int writeSBML(SBMLDocument d, String filename) {
781    return libsbmlJNI.writeSBML(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename));
782  }
783
784  
785/**
786 * Writes the given SBML document <code>d</code> to an in-memory string and returns a
787 * pointer to it.  The string is owned by the caller and should be freed
788 * (with free()) when no longer needed.  This convenience function is
789 * functionally equivalent to:
790 <p>
791 *   SBMLWriter_writeSBMLToString(SBMLWriter_create(), d);
792 <p>
793 * but does not require the caller to create an {@link SBMLWriter} object first.
794 <p>
795 * @param d an {@link SBMLDocument} object to be written out in XML format
796 <p>
797 * @return the string on success and <code>null</code> if one of the underlying parser
798 * components fail.
799 */ public
800 static String writeSBMLToString(SBMLDocument d) {
801    return libsbmlJNI.writeSBMLToString(SBMLDocument.getCPtr(d), d);
802  }
803
804  
805/**
806 * Writes the given SBML document <code>d</code> to the file <code>filename</code>.
807 * This convenience function is functionally equivalent to:
808 <p>
809 *   SBMLWriter_writeSBMLToFile(SBMLWriter_create(), d, filename);
810 <p>
811 * but that does not require the caller to create an {@link SBMLWriter} object first.
812 <p>
813 * If the given filename ends with the suffix <code>&quot;.gz&quot;</code>
814(for example, <code>&quot;myfile.xml.gz&quot;</code>), libSBML assumes the
815caller wants the file to be written compressed in <em>gzip</em> format.
816Similarly, if the given filename ends with <code>&quot;.zip&quot;</code> or
817<code>&quot;.bz2&quot;</code>, libSBML assumes the caller wants the file to
818be compressed in <em>zip</em> or <em>bzip2</em> format (respectively).
819Files whose names lack these suffixes will be written uncompressed.
820<em>Special considerations for the zip format</em>: If the given filename
821ends with <code>&quot;.zip&quot;</code>, the file placed in the zip archive
822will have the suffix <code>&quot;.xml&quot;</code> or
823<code>&quot;.sbml&quot;</code>.  For example, the file in the zip archive
824will be named <code>&quot;test.xml&quot;</code> if the given filename is
825<code>&quot;test.xml.zip&quot;</code> or <code>&quot;test.zip&quot;</code>.
826Similarly, the filename in the archive will be
827<code>&quot;test.sbml&quot;</code> if the given filename is
828<code>&quot;test.sbml.zip&quot;</code>.
829
830 <p>
831 * @param d an {@link SBMLDocument} object to be written out in XML format
832 <p>
833 * @param filename a string giving the path to a file where the XML
834 * content is to be written.
835 <p>
836 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be
837 * written.  Some possible reasons for failure include (a) being unable to
838 * open the file, and (b) using a filename that indicates a compressed SBML
839 * file (i.e., a filename ending in <code>&quot;.zip&quot;</code> or
840 * similar) when the compression functionality has not been enabled in
841 * the underlying copy of libSBML.
842 <p>
843 <p>
844 <p>
845 * @see SBMLWriter#hasZlib()
846 * @see SBMLWriter#hasBzip2()
847 */ public
848 static int writeSBMLToFile(SBMLDocument d, String filename) {
849    return libsbmlJNI.writeSBMLToFile(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename));
850  }
851
852  
853/**
854 * This method takes an SBML type code and returns a string representing
855 * the code.
856 <p>
857 * LibSBML attaches an identifying code to every
858 * kind of SBML object.  These are known as <em>SBML type codes</em>.  In
859 * other languages, the set of type codes is stored in an enumeration; in
860 * the Java language interface for libSBML, the type codes are defined as
861 * static integer constants in the interface class {@link
862 * libsbmlConstants}.  The names of the type codes all begin with the
863 * characters <code>SBML_.</code> 
864 <p>
865 * @return a human readable name for the given
866 * SBML type code.
867 <p>
868 * @note The caller does not own the returned string and is therefore not
869 * allowed to modify it.
870 */ public
871 static String SBMLTypeCode_toString(int tc, String pkgName) {
872    return libsbmlJNI.SBMLTypeCode_toString(tc, pkgName);
873  }
874
875  
876/**
877 * Tests for logical equality between two given <code>UNIT_KIND_</code>
878 * code values.
879 <p>
880 * This function behaves exactly like C's <code>==</code> operator, except
881 * for the following two cases:
882 * <ul>
883 * <li>{@link  libsbmlConstants#UNIT_KIND_LITER UNIT_KIND_LITER} <code>==</code> {@link  libsbmlConstants#UNIT_KIND_LITRE UNIT_KIND_LITRE}
884 * <li>{@link  libsbmlConstants#UNIT_KIND_METER UNIT_KIND_METER} <code>==</code> {@link  libsbmlConstants#UNIT_KIND_METRE UNIT_KIND_METRE}
885 * </ul>
886 <p>
887 * In the two cases above, C equality comparison would yield <code>false</code>
888 * (because each of the above is a distinct enumeration value), but
889 * this function returns <code>true.</code>
890 <p>
891 * @param uk1 a <code>UNIT_KIND_</code> value 
892 * @param uk2 a second <code>UNIT_KIND_</code> value to compare to <code>uk1</code>
893 <p>
894 * @return nonzero (for <code>true</code>) if <code>uk1</code> is logically equivalent to 
895 * <code>uk2</code>, zero (for <code>false</code>) otherwise.
896 <p>
897 * @note For more information about the libSBML unit codes, please refer to
898 * the class documentation for {@link Unit}.
899 */ public
900 static int UnitKind_equals(int uk1, int uk2) {
901    return libsbmlJNI.UnitKind_equals(uk1, uk2);
902  }
903
904  
905/**
906 * Converts a text string naming a kind of unit to its corresponding
907 * libSBML <code>UNIT_KIND_</code> constant/enumeration value.
908 <p>
909 * @param name a string, the name of a predefined base unit in SBML
910 <p>
911 * @return a value the set of <code>UNIT_KIND_</code> codes
912 * defined in class {@link libsbmlConstants}, corresponding to the string
913 * <code>name</code> (determined in a case-insensitive manner).
914 <p>
915 * @note For more information about the libSBML unit codes, please refer to
916 * the class documentation for {@link Unit}.
917 */ public
918 static int UnitKind_forName(String name) {
919    return libsbmlJNI.UnitKind_forName(name);
920  }
921
922  
923/**
924 * Converts a unit code to a text string equivalent.
925 <p>
926 * @param uk a value from the set of <code>UNIT_KIND_</code> codes
927 * defined in the class {@link libsbmlConstants}
928 <p>
929 <p>
930 * @return the name corresponding to the given unit code.
931 <p>
932 * @note For more information about the libSBML unit codes, please refer to
933 * the class documentation for {@link Unit}.
934 <p>
935 * @warning The string returned is a static data value.  The caller does not
936 * own the returned string and is therefore not allowed to modify it.
937 */ public
938 static String UnitKind_toString(int uk) {
939    return libsbmlJNI.UnitKind_toString(uk);
940  }
941
942  
943/**
944 * Predicate for testing whether a given string corresponds to a
945 * predefined libSBML unit code.
946 <p>
947 * @param str a text string naming a base unit defined by SBML
948 * @param level the Level of SBML
949 * @param version the Version within the Level of SBML
950 <p>
951 * @return nonzero (for <code>true</code>) if string is the name of a valid
952 * <code>UNIT_KIND_</code> value, zero (for <code>false</code>) otherwise.
953 <p>
954 * @note For more information about the libSBML unit codes, please refer to
955 * the class documentation for {@link Unit}.
956 */ public
957 static int UnitKind_isValidUnitKindString(String str, long level, long version) {
958    return libsbmlJNI.UnitKind_isValidUnitKindString(str, level, version);
959  }
960
961  public static boolean representsNumber(int type) {
962    return libsbmlJNI.representsNumber(type);
963  }
964
965  public static boolean representsFunction(int type, ASTBasePlugin plugin) {
966    return libsbmlJNI.representsFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
967  }
968
969  public static boolean representsFunction(int type) {
970    return libsbmlJNI.representsFunction__SWIG_1(type);
971  }
972
973  public static boolean representsUnaryFunction(int type, ASTBasePlugin plugin) {
974    return libsbmlJNI.representsUnaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
975  }
976
977  public static boolean representsUnaryFunction(int type) {
978    return libsbmlJNI.representsUnaryFunction__SWIG_1(type);
979  }
980
981  public static boolean representsBinaryFunction(int type, ASTBasePlugin plugin) {
982    return libsbmlJNI.representsBinaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
983  }
984
985  public static boolean representsBinaryFunction(int type) {
986    return libsbmlJNI.representsBinaryFunction__SWIG_1(type);
987  }
988
989  public static boolean representsNaryFunction(int type, ASTBasePlugin plugin) {
990    return libsbmlJNI.representsNaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
991  }
992
993  public static boolean representsNaryFunction(int type) {
994    return libsbmlJNI.representsNaryFunction__SWIG_1(type);
995  }
996
997  public static boolean representsQualifier(int type, ASTBasePlugin plugin) {
998    return libsbmlJNI.representsQualifier__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin);
999  }
1000
1001  public static boolean representsQualifier(int type) {
1002    return libsbmlJNI.representsQualifier__SWIG_1(type);
1003  }
1004
1005  public static boolean representsFunctionRequiringAtLeastTwoArguments(int type) {
1006    return libsbmlJNI.representsFunctionRequiringAtLeastTwoArguments(type);
1007  }
1008
1009  public static int getCoreTypeFromName(String name) {
1010    return libsbmlJNI.getCoreTypeFromName(name);
1011  }
1012
1013  public static String getNameFromCoreType(int type) {
1014    return libsbmlJNI.getNameFromCoreType(type);
1015  }
1016
1017  public static boolean isCoreTopLevelMathMLFunctionNodeTag(String name) {
1018    return libsbmlJNI.isCoreTopLevelMathMLFunctionNodeTag(name);
1019  }
1020
1021  public static boolean isCoreTopLevelMathMLNumberNodeTag(String name) {
1022    return libsbmlJNI.isCoreTopLevelMathMLNumberNodeTag(name);
1023  }
1024
1025  
1026/**
1027 * Reads the MathML from the given XML string, constructs a corresponding
1028 * abstract syntax tree, and returns a pointer to the root of the tree.
1029 <p>
1030 * @param xml a string containing a full MathML expression
1031 <p>
1032 * @return the root of an AST corresponding to the given mathematical
1033 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code>
1034 * or invalid.
1035 */ public
1036 static ASTNode readMathMLFromString(String xml) {
1037    long cPtr = libsbmlJNI.readMathMLFromString(xml);
1038    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
1039  }
1040
1041  
1042/**
1043 * Reads the MathML from the given XML string, constructs a corresponding
1044 * abstract syntax tree, and returns a pointer to the root of the tree.
1045 <p>
1046 * @param xml a string containing a full MathML expression
1047 * @param xmlns a XMLNamespaces_t object containing namespaces that
1048 * are considered active during the read e.g. an L3 package namespace
1049 <p>
1050 * @return the root of an AST corresponding to the given mathematical
1051 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code>
1052 * or invalid.
1053 */ public
1054 static ASTNode readMathMLFromStringWithNamespaces(String xml, XMLNamespaces xmlns) {
1055    long cPtr = libsbmlJNI.readMathMLFromStringWithNamespaces(xml, XMLNamespaces.getCPtr(xmlns), xmlns);
1056    return (cPtr == 0) ? null : new ASTNode(cPtr, false);
1057  }
1058
1059  
1060/**
1061 * Writes the given ASTNode_t (and its children) to a string as MathML, and
1062 * returns the string.
1063 <p>
1064 * @param node the root of an AST to write out to the stream.
1065 <p>
1066 * @return a string containing the written-out MathML representation
1067 * of the given AST.
1068 <p>
1069 * @note The string is owned by the caller and should be freed (with
1070 * free()) when no longer needed.  <code>null</code> is returned if the given
1071 * argument is <code>null.</code>
1072 */ public
1073 static String writeMathMLToString(ASTNode node) {
1074    return libsbmlJNI.writeMathMLToString(ASTNode.getCPtr(node), node);
1075  }
1076
1077  
1078/**
1079 * Parses the given SBML formula and returns a representation of it as an
1080 * Abstract Syntax Tree (AST).
1081 <p>
1082 * <p>
1083 * The text-string form of mathematical formulas produced by
1084 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code>
1085 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>
1086 * use a simple C-inspired infix notation taken from SBML Level&nbsp;1.  A
1087 * formula in this text-string form therefore can be handed to a program
1088 * that understands SBML Level&nbsp;1 mathematical expressions, or used as
1089 * part of a formula translation system.  The syntax is described in detail
1090 * in the documentation for {@link ASTNode}. 
1091 <p>
1092 * Note that this facility is provided as a convenience by libSBML&mdash;the
1093 * MathML standard does not actually define a 'string-form' equivalent to
1094 * MathML expression trees, so the choice of formula syntax is somewhat
1095 * arbitrary.  The approach taken by libSBML is to use the syntax defined by
1096 * SBML Level&nbsp;1 (which in fact used a text-string representation of
1097 * formulas and not MathML).  This formula syntax is based mostly on C
1098 * programming syntax, and may contain operators, function calls, symbols,
1099 * and white space characters.  The following table provides the precedence
1100 * rules for the different entities that may appear in formula strings.
1101 <p>
1102 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em">
1103 <tr style="background: lightgray; font-size: 14px;">
1104     <th align="left">Token</th>
1105     <th align="left">Operation</th>
1106     <th align="left">Class</th>
1107     <th>Precedence</th>
1108     <th align="left">Associates</th>
1109 </tr>
1110<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
1111<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>
1112<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>
1113<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr>
1114<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr>
1115<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1116<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1117<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1118<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1119<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
1120<caption class="top-caption">A table of the expression operators and their precedence in the
1121text-string format for mathematical expressions used by SBML_parseFormula().
1122</caption>
1123</table>
1124
1125
1126 <p>
1127 * In the table above, <em>operand</em> implies the construct is an operand, 
1128 * <em>prefix</em> implies the operation is applied to the following arguments, 
1129 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
1130 * two arguments.  The values in the <b>Precedence</b> column show how the
1131 * order of different types of operation are determined.  For example, the
1132 * expression <code>a * b + c</code> is evaluated as <code>(a * b) +
1133 * c</code> because the @c * operator has higher precedence.  The
1134 * <b>Associates</b> column shows how the order of similar precedence
1135 * operations is determined; for example, <code>a - b + c</code> is
1136 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code>
1137 * operators are left-associative.
1138 <p>
1139 * The function call syntax consists of a function name, followed by optional
1140 * white space, followed by an opening parenthesis token, followed by a
1141 * sequence of zero or more arguments separated by commas (with each comma
1142 * optionally preceded and/or followed by zero or more white space
1143 * characters, followed by a closing parenthesis token.  The function name
1144 * must be chosen from one of the pre-defined functions in SBML or a
1145 * user-defined function in the model.  The following table lists the names
1146 * of certain common mathematical functions; this table corresponds to
1147 * 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>:
1148 <p>
1149 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
1150 <tr>
1151     <th align="left" width="60">Name</th>
1152     <th align="left" width="35">Args</th>
1153     <th align="left">Formula or meaning</th>
1154     <th align="left" width="110">Argument Constraints</th>
1155     <th align="left" width="100">Result constraints</th>
1156 </tr>
1157<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr>
1158<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>
1159<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>
1160<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>
1161<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>
1162<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr>
1163<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>
1164<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>
1165<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>
1166<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>
1167<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>
1168<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>
1169<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>
1170<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr>
1171<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>
1172<caption class="bottom-caption">The names of mathematical functions defined in the SBML
1173Level&nbsp;1 Version&nbsp;2 text-string formula syntax.</caption>
1174</table>
1175
1176
1177 <p>
1178 * @warning <span class='warning'>There are differences between the symbols
1179 * used to represent the common mathematical functions and the corresponding
1180 * MathML token names.  This is a potential source of incompatibilities.
1181 * Note in particular that in this text-string syntax, <code>log(x)</code>
1182 * represents the natural logarithm, whereas in MathML, the natural logarithm
1183 * is <code>&lt;ln/&gt;</code>.  Application writers are urged to be careful
1184 * when translating between text forms and MathML forms, especially if they
1185 * provide a direct text-string input facility to users of their software
1186 * systems.</span> 
1187 <p>
1188 * <p>
1189 * @warning <span class='warning'>We urge developers to keep in mind that
1190 * the text-string formula syntax is specific to SBML Level&nbsp;1's C-like
1191 * mathematical formula syntax.  In particular, it is <em>not a
1192 * general-purpose mathematical expression syntax</em>.  LibSBML provides
1193 * methods for parsing and transforming text-string math formulas back and
1194 * forth from AST structures, but it is important to keep the system's
1195 * limitations in mind.</span>
1196 <p>
1197 * @param formula the text-string formula expression to be parsed
1198 <p>
1199 * @return the root node of the AST corresponding to the <code>formula</code>, or 
1200 * <code>null</code> if an error occurred in parsing the formula
1201 <p>
1202 <p>
1203 <p>
1204 <p>
1205 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
1206 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
1207 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
1208 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
1209 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
1210 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
1211 */ public
1212 static ASTNode parseFormula(String formula) {
1213    long cPtr = libsbmlJNI.parseFormula(formula);
1214    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
1215  }
1216
1217  
1218/**
1219 * Converts an AST to a string representation of a formula using a syntax
1220 * basically derived from SBML Level&nbsp;1.
1221 <p>
1222 * <p>
1223 * The text-string form of mathematical formulas produced by
1224 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code>
1225 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>
1226 * use a simple C-inspired infix notation taken from SBML Level&nbsp;1.  A
1227 * formula in this text-string form therefore can be handed to a program
1228 * that understands SBML Level&nbsp;1 mathematical expressions, or used as
1229 * part of a formula translation system.  The syntax is described in detail
1230 * in the documentation for {@link ASTNode}. 
1231 <p>
1232 * Note that this facility is provided as a convenience by libSBML&mdash;the
1233 * MathML standard does not actually define a 'string-form' equivalent to
1234 * MathML expression trees, so the choice of formula syntax is somewhat
1235 * arbitrary.  The approach taken by libSBML is to use the syntax defined by
1236 * SBML Level&nbsp;1 (which in fact used a text-string representation of
1237 * formulas and not MathML).  This formula syntax is based mostly on C
1238 * programming syntax, and may contain operators, function calls, symbols,
1239 * and white space characters.  The following table provides the precedence
1240 * rules for the different entities that may appear in formula strings.
1241 <p>
1242 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em">
1243 <tr style="background: lightgray; font-size: 14px;">
1244     <th align="left">Token</th>
1245     <th align="left">Operation</th>
1246     <th align="left">Class</th>
1247     <th>Precedence</th>
1248     <th align="left">Associates</th>
1249 </tr>
1250<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr>
1251<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>
1252<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>
1253<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr>
1254<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr>
1255<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1256<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr>
1257<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1258<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1259<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
1260<caption class="top-caption">A table of the expression operators and their precedence in the
1261text-string format for mathematical expressions used by SBML_parseFormula().
1262</caption>
1263</table>
1264
1265
1266 <p>
1267 * In the table above, <em>operand</em> implies the construct is an operand, 
1268 * <em>prefix</em> implies the operation is applied to the following arguments, 
1269 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
1270 * two arguments.  The values in the <b>Precedence</b> column show how the
1271 * order of different types of operation are determined.  For example, the
1272 * expression <code>a * b + c</code> is evaluated as <code>(a * b) +
1273 * c</code> because the @c * operator has higher precedence.  The
1274 * <b>Associates</b> column shows how the order of similar precedence
1275 * operations is determined; for example, <code>a - b + c</code> is
1276 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code>
1277 * operators are left-associative.
1278 <p>
1279 * The function call syntax consists of a function name, followed by optional
1280 * white space, followed by an opening parenthesis token, followed by a
1281 * sequence of zero or more arguments separated by commas (with each comma
1282 * optionally preceded and/or followed by zero or more white space
1283 * characters, followed by a closing parenthesis token.  The function name
1284 * must be chosen from one of the pre-defined functions in SBML or a
1285 * user-defined function in the model.  The following table lists the names
1286 * of certain common mathematical functions; this table corresponds to
1287 * 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>:
1288 <p>
1289 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
1290 <tr>
1291     <th align="left" width="60">Name</th>
1292     <th align="left" width="35">Args</th>
1293     <th align="left">Formula or meaning</th>
1294     <th align="left" width="110">Argument Constraints</th>
1295     <th align="left" width="100">Result constraints</th>
1296 </tr>
1297<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr>
1298<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>
1299<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>
1300<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>
1301<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>
1302<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr>
1303<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>
1304<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>
1305<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>
1306<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>
1307<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>
1308<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>
1309<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>
1310<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr>
1311<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>
1312<caption class="bottom-caption">The names of mathematical functions defined in the SBML
1313Level&nbsp;1 Version&nbsp;2 text-string formula syntax.</caption>
1314</table>
1315
1316
1317 <p>
1318 * @warning <span class='warning'>There are differences between the symbols
1319 * used to represent the common mathematical functions and the corresponding
1320 * MathML token names.  This is a potential source of incompatibilities.
1321 * Note in particular that in this text-string syntax, <code>log(x)</code>
1322 * represents the natural logarithm, whereas in MathML, the natural logarithm
1323 * is <code>&lt;ln/&gt;</code>.  Application writers are urged to be careful
1324 * when translating between text forms and MathML forms, especially if they
1325 * provide a direct text-string input facility to users of their software
1326 * systems.</span> 
1327 <p>
1328 * <p>
1329 * @warning <span class='warning'>We urge developers to keep in mind that
1330 * the text-string formula syntax is specific to SBML Level&nbsp;1's C-like
1331 * mathematical formula syntax.  In particular, it is <em>not a
1332 * general-purpose mathematical expression syntax</em>.  LibSBML provides
1333 * methods for parsing and transforming text-string math formulas back and
1334 * forth from AST structures, but it is important to keep the system's
1335 * limitations in mind.</span> 
1336 <p>
1337 * @param tree the AST to be converted.
1338 <p>
1339 * @return the formula from the given AST as an SBML Level 1 text-string
1340 * mathematical formula.  The caller owns the returned string and is
1341 * responsible for freeing it when it is no longer needed.
1342 <p>
1343 <p>
1344 <p>
1345 <p>
1346 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
1347 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
1348 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
1349 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
1350 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
1351 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
1352 */ public
1353 static String formulaToString(ASTNode tree) {
1354    return libsbmlJNI.formulaToString(ASTNode.getCPtr(tree), tree);
1355  }
1356
1357  
1358/**
1359 * Parses the given mathematical formula and returns a representation of it
1360 * as an Abstract Syntax Tree (AST).
1361 <p>
1362 * <p>
1363 * The text-string form of mathematical formulas read by the functions
1364 * <code><a
1365 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode
1366 * tree)</a></code> and <code><a
1367 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1368 * formula)</a></code> are expanded versions of the formats produced
1369 * and read by <code><a
1370 * href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode
1371 * tree)</a></code> and * <code><a
1372 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1373 * formula)</a></code>, respectively.  The latter two libSBML
1374 * functions were originally developed to support conversion between SBML
1375 * Levels&nbsp;1 and&nbsp;2, and were focused on the syntax of mathematical
1376 * formulas used in SBML Level&nbsp;1.  With time, and the use of MathML in
1377 * SBML Levels&nbsp;2 and&nbsp;3, it became clear that supporting
1378 * Level&nbsp;2 and&nbsp;3's expanded mathematical syntax would be useful for
1379 * software developers.
1380 * To maintain backwards compatibility, the original
1381 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code>
1382 * and
1383 * <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>
1384 * have been left untouched, and instead, the new functionality is
1385 * provided in the form of
1386 * <cod
1387e><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
1388 * and <code><a
1389 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode
1390 * tree)</a></code>.
1391 <p>
1392 * The following are the differences in the formula syntax supported by the
1393 * 'L3' versions of the formula parsers and formatters, compared to what is
1394 * supported by * <code><a
1395 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1396 * formula)</a></code> and <code><a
1397 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode
1398 * tree)</a></code>:
1399 <p>
1400 * <ul>
1401 * <li> Units may be asociated with bare numbers, using the following syntax:
1402 * <div style='margin: 10px auto 10px 25px; display: block'>
1403 * <span class='code' style='background-color: #d0d0ee'>number</span>
1404 * <span class='code' style='background-color: #edd'>unit</span>
1405 * </div>
1406 * The <span class='code' style='background-color: #d0d0ee'>number</span>
1407 * may be in any form (an integer, real, or rational
1408 * number), and the 
1409 * <span class='code' style='background-color: #edd'>unit</span>
1410 * must conform to the syntax of an SBML identifier (technically, the
1411 * type defined as <code>SId</code> in the SBML specifications).  The whitespace between
1412 * <span class='code' style='background-color: #d0d0ee'>number</span>
1413 * and <span class='code' style='background-color: #edd'>unit</span>
1414 * is optional.
1415 <p>
1416 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be
1417 * used.
1418 <p>
1419 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and will
1420 * produce a piecewise function in the MathML.
1421 <p>
1422 * <li> All inverse trigonometric functions may be defined in the infix either
1423 * using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both <code>arccsc</code>
1424 * and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> defined in
1425 * MathML.  (Many functions in the SBML Level&nbsp;1 infix-notation parser
1426 * implemented by * <code><a
1427 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1428 * formula)</a></code> are defined this way as well, but not all.)
1429 <p>
1430 * <li> The following expression is parsed as a rational number instead of
1431 * as a numerical division:
1432 * <pre style='display: block; margin-left: 25px'>
1433 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre>
1434 * No spaces are allowed in this construct; in other words,
1435 * &quot;<code>(3 / 4)</code>&quot; will be parsed into the MathML
1436 * <code>&lt;divide&gt;</code> construct rather than a rational number.  The 
1437 * general number syntax allows you to assign units to a rational number, e.g.,
1438 * &quot;<code>(3/4) ml</code>&quot;.  (If the string is a division, units
1439 * are not interpreted in this way.)
1440 <p>
1441 * <li> Various settings may be altered by using an {@link L3ParserSettings} object in
1442 * conjunction with the functions <code><a
1443 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1444 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1445 * formula, {@link L3ParserSettings} settings)</a></code> and <code><a
1446 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode
1447 * tree)</a></code>, including the following:
1448 * <ul>
1449 * <li> The function <code>log</code> with a single argument (&quot;<code>log(x)</code>&quot;) 
1450 * can be parsed as <code>log10(x)</code>, <code>ln(x)</code>, or treated
1451 * as an error, as desired.
1452 * <li> Unary minus signs can be collapsed or preserved; that is,
1453 * sequential pairs of unary minuses (e.g., &quot;<code>- -3</code>&quot;)
1454 * can be removed from the input entirely and single unary minuses can be
1455 * incorporated into the number node, or all minuses can be preserved in
1456 * the AST node structure.
1457 * <li> Parsing of units embedded in the input string can be turned on and
1458 * off.
1459 * <li> The string <code>avogadro</code> can be parsed as a MathML <em>csymbol</em> or
1460 * as an identifier.
1461 * <li> A {@link Model} object may optionally be provided to the parser using the
1462 * variant function call
1463 * <code><a
1464 * href='libsbml.html#parseL3FormulaWithModel(java.lang.String,
1465 * org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula,
1466 * {@link Model} model)</a></code> or stored in a {@link L3ParserSettings} object
1467 * passed to the variant function <code><a
1468 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1469 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1470 * formula, {@link L3ParserSettings} settings)</a></code>.
1471 * When a {@link Model} object is provided, identifiers (values of type <code>SId</code>) from
1472 * that model are used in preference to pre-defined MathML definitions.  More
1473 * precisely, the {@link Model} entities whose identifiers will shadow identical
1474 * symbols in the mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter},
1475 * {@link Reaction}, and {@link SpeciesReference}.  For instance, if the parser is given a
1476 * {@link Model} containing a {@link Species} with the identifier
1477 * &quot;<code>pi</code>&quot;, and the formula to be parsed is
1478 * &quot;<code>3*pi</code>&quot;, the MathML produced will contain the
1479 * construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of the construct
1480 * <code>&lt;pi/&gt;</code>.  <li> Similarly, when a {@link Model} object is
1481 * provided, <code>SId</code> values of user-defined functions present in the model
1482 * will be used preferentially over pre-defined MathML functions.  For
1483 * example, if the passed-in {@link Model} contains a {@link FunctionDefinition} with the
1484 * identifier &quot;<code>sin</code>&quot;, that function will be used
1485 * instead of the predefined MathML function <code>&lt;sin/&gt;</code>.
1486 * </ul>
1487 * These configuration settings cannot be changed using the basic parser and
1488 * formatter functions, but can be changed on a per-call basis by using the
1489 * alternative functions <code><a
1490 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1491 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1492 * formula, {@link L3ParserSettings} settings)</a></code> and <code><a
1493 * href='libsbml.html#formulaToL3StringWithSettings(const ASTNode_t tree,
1494 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(ASTNode tree
1495 * {@link L3ParserSettings} settings)</a></code>.
1496 *
1497 * </ul> <p>
1498 * The parser function <code><a
1499 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1500 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1501 * formula, {@link L3ParserSettings} settings)</a></code>
1502 * returns the root node of the AST corresponding to the
1503 * formula given as the argument.  If the formula contains a syntax error,
1504 * the function will return <code>null</code> instead.  When <code>null</code> is returned, an
1505 * error is set; information about the error can be retrieved using
1506 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>.
1507 <p>
1508 * Note that this facility and the SBML Level&nbsp;1-based <code><a
1509 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1510 * formula)</a></code> are provided as a convenience by
1511 * libSBML&mdash;the MathML standard does not actually define a 'string-form'
1512 * equivalent to MathML expressions, so the choice of formula syntax is
1513 * arbitrary.  The approach taken by libSBML is to start with the syntax
1514 * defined by SBML Level&nbsp;1 (which in fact used a text-string
1515 * representation of formulas, and not MathML), and expand it to include the
1516 * above functionality.  This formula syntax is based mostly on C programming
1517 * syntax, and may contain operators, function calls, symbols, and white
1518 * space characters.  The following table provides the precedence rules for
1519 * the different entities that may appear in formula strings.
1520 <p>
1521 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em">
1522 <tr style="background: lightgray; font-size: 14px;">
1523     <th align="left">Token</th>
1524     <th align="left">Operation</th>
1525     <th align="left">Class</th>
1526     <th>Precedence</th>
1527     <th align="left">Associates</th>
1528 </tr>
1529<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">8</td><td>n/a</td></tr>
1530<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>
1531<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>
1532<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">7</td><td>left</td></tr>
1533<tr><td><code>-, !</code></td><td>negation and boolean 'not'</td><td>unary</td><td align="center">6</td><td>right</td></tr>
1534<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align="center">5</td><td>left</td></tr>
1535<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align="center">4</td><td>left</td></tr>
1536<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>
1537<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align="center">2</td><td>left</td></tr>
1538<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr>
1539<caption class="top-caption">A table of the expression operators and their precedence in the
1540text-string format for mathematical expressions used by SBML_parseL3Formula().
1541</caption>
1542</table>
1543
1544
1545 <p>
1546 * In the table above, <em>operand</em> implies the construct is an operand, 
1547 * <em>prefix</em> implies the operation is applied to the following arguments, 
1548 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are
1549 * two arguments.  The values in the <b>Precedence</b> column show how the
1550 * order of different types of operation are determined.  For example, the
1551 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code> 
1552 * because the @c * operator has higher precedence.  The
1553 * <b>Associates</b> column shows how the order of similar precedence
1554 * operations is determined; for example, <code>a && b || c</code> is
1555 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code>
1556 * operators are left-associative and have the same precedence.
1557 <p>
1558 * The function call syntax consists of a function name, followed by optional
1559 * white space, followed by an opening parenthesis token, followed by a
1560 * sequence of zero or more arguments separated by commas (with each comma
1561 * optionally preceded and/or followed by zero or more white space
1562 * characters), followed by a closing parenthesis token.  The function name
1563 * must be chosen from one of the pre-defined functions in SBML or a
1564 * user-defined function in the model.  The following table lists the names
1565 * of certain common mathematical functions; this table corresponds to
1566 * Table&nbsp;6 in the <a target='_blank'
1567 * href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML
1568 * Level&nbsp;1 Version&nbsp;2 specification</a> with additions based on the
1569 * functions added in SBML Level 2 and Level 3:
1570 <p>
1571 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
1572 <tr>
1573     <th align="left" width="100">Name</th>
1574     <th align="left" width="100">Argument(s)</th>
1575     <th align="left">Formula or meaning</th>
1576     <th align="left" width="110">Argument Constraints</th>
1577     <th align="left" width="100">Result constraints</th>
1578 </tr>
1579<tr><td><code>abs</code></td>   
1580    <td><em>x</em></td> 
1581    <td>Absolute value of <em>x</em>.</td>
1582    <td></td>
1583    <td></td>
1584</tr>
1585<tr><td><code>acos</code>, <code>arccos</code></td>
1586    <td><em>x</em></td>
1587    <td>Arccosine of <em>x</em> in radians.</td>
1588    <td>-1.0 &le; <em>x</em> &le; 1.0</td>
1589    <td>0 &le; <em>acos(x)</em> &le; &pi;</td>
1590</tr>
1591<tr><td><code>acosh</code>, <code>arccosh</code></td>
1592    <td><em>x</em></td>
1593    <td>Hyperbolic arccosine of <em>x</em> in radians.</td>
1594    <td></td>
1595    <td></td>
1596</tr>
1597<tr><td><code>acot</code>, <code>arccot</code></td>
1598    <td><em>x</em></td>
1599    <td>Arccotangent of <em>x</em> in radians.</td>
1600    <td></td>
1601    <td></td>
1602</tr>
1603<tr><td><code>acoth</code>, <code>arccoth</code></td>
1604    <td><em>x</em></td>
1605    <td>Hyperbolic arccotangent of <em>x</em> in radians.</td>
1606    <td></td>
1607    <td></td>
1608</tr>
1609<tr><td><code>acsc</code>, <code>arccsc</code></td>
1610    <td><em>x</em></td>
1611    <td>Arccosecant of <em>x</em> in radians.</td>
1612    <td></td>
1613    <td></td>
1614</tr>
1615<tr><td><code>acsch</code>, <code>arccsch</code></td>
1616    <td><em>x</em></td>
1617    <td>Hyperbolic arccosecant of <em>x</em> in radians.</td>
1618    <td></td>
1619    <td></td>
1620</tr>
1621<tr><td><code>asec</code>, <code>arcsec</code></td>
1622    <td><em>x</em></td>
1623    <td>Arcsecant of <em>x</em> in radians.</td>
1624    <td></td>
1625    <td></td>
1626</tr>
1627<tr><td><code>asech</code>, <code>arcsech</code></td>
1628    <td><em>x</em></td>
1629    <td>Hyperbolic arcsecant of <em>x</em> in radians.</td>
1630    <td></td>
1631    <td></td>
1632</tr>
1633<tr><td><code>asin</code>, <code>arcsin</code></td>
1634    <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td>
1635    <td>-1.0 &le; <em>x</em> &le; 1.0</td>
1636    <td>0 &le; <em>asin(x)</em> &le; &pi;</td>
1637</tr>
1638<tr><td><code>atan</code>, <code>arctan</code></td>
1639    <td><em>x</em></td>
1640    <td>Arctangent of <em>x</em> in radians.</td>
1641    <td></td>
1642    <td>0 &le; <em>atan(x)</em> &le; &pi;</td>
1643</tr>
1644<tr><td><code>atanh</code>, <code>arctanh</code></td>
1645    <td><em>x</em></td>
1646    <td>Hyperbolic arctangent of <em>x</em> in radians.</td>
1647    <td></td>
1648    <td></td>
1649</tr>
1650<tr><td><code>ceil</code>, <code>ceiling</code></td>
1651    <td><em>x</em></td>
1652    <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td>
1653    <td></td>
1654    <td></td>
1655</tr>
1656<tr><td><code>cos</code></td>
1657    <td><em>x</em></td>
1658    <td>Cosine of <em>x</em></td>
1659    <td></td>
1660    <td></td>
1661</tr>
1662<tr><td><code>cosh</code></td>
1663    <td><em>x</em></td>
1664    <td>Hyperbolic cosine of <em>x</em>.</td>
1665    <td></td>
1666    <td></td>
1667</tr>
1668<tr><td><code>cot</code></td>
1669    <td><em>x</em></td>
1670    <td>Cotangent of <em>x</em>.</td>
1671    <td></td>
1672    <td></td>
1673</tr>
1674<tr><td><code>coth</code></td>
1675    <td><em>x</em></td>
1676    <td>Hyperbolic cotangent of <em>x</em>.</td>
1677    <td></td>
1678    <td></td>
1679</tr>
1680<tr><td><code>csc</code></td>
1681    <td><em>x</em></td>
1682    <td>Cosecant of <em>x</em>.</td>
1683    <td></td>
1684    <td></td>
1685</tr>
1686<tr><td><code>csch</code></td>
1687    <td><em>x</em></td>
1688    <td>Hyperbolic cosecant of <em>x</em>.</td>
1689    <td></td>
1690    <td></td>
1691</tr>
1692<tr><td><code>delay</code></td>
1693    <td><em>x, y</em></td>
1694    <td>The value of <em>x</em> at <em>y</em> time units in the past.</td>
1695    <td></td>
1696    <td></td>
1697</tr>
1698<tr><td><code>factorial</code></td>
1699    <td><em>n</em></td>
1700    <td>The factorial of <em>n</em>. Factorials are defined by n! = n*(n-1)* ... * 1.</td>
1701    <td><em>n</em> must be an integer.</td>
1702    <td></td>
1703</tr>
1704<tr><td><code>exp</code></td>
1705    <td><em>x</em></td>
1706    <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td>
1707    <td></td>
1708    <td></td>
1709</tr>
1710<tr><td><code>floor</code></td>
1711    <td><em>x</em></td>
1712    <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td>
1713    <td></td>
1714    <td></td>
1715</tr>
1716<tr><td><code>ln</code></td>
1717    <td><em>x</em></td>
1718    <td>Natural logarithm of <em>x</em>.</td>
1719    <td><em>x</em> &gt; 0</td>
1720    <td></td>
1721</tr>
1722<tr><td><code>log</code></td>
1723    <td><em>x</em></td>
1724    <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>
1725    <td><em>x</em> &gt; 0</td>
1726    <td></td>
1727</tr>
1728<tr><td><code>log</code></td>
1729    <td><em>x, y</em></td>
1730    <td>The base <em>x</em> logarithm of <em>y</em>.</td>
1731    <td><em>y</em> &gt; 0</td>
1732    <td></td>
1733</tr>
1734<tr><td><code>log10</code></td>
1735    <td><em>x</em></td>
1736    <td>Base 10 logarithm of <em>x</em>.</td>
1737    <td><em>x</em> &gt; 0</td>
1738    <td></td>
1739</tr>
1740<tr><td><code>piecewise</code></td>
1741    <td><em>x1, y1, [x2, y2,] [...] [z]</em></td>
1742    <td>A piecewise function: if (<em>y1</em>), <em>x1</em>.  Otherwise, if (<em>y2</em>), <em>x2</em>, etc.  Otherwise, z. </td>
1743    <td><em>y1, y2, y3 [etc]</em> must be boolean</td>
1744    <td></td>
1745</tr>
1746<tr><td><code>pow</code>, <code>power</code> </td>
1747    <td><em>x, y</em></td>
1748    <td><em>x</em><sup><em> y</em></sup>.</td>
1749    <td></td>
1750    <td></td>
1751</tr>
1752<tr><td><code>root</code></td>
1753    <td><em>b, x</em></td>
1754    <td>The root base <em>b</em> of <em>x</em>.</td>
1755    <td></td>
1756    <td></td>
1757</tr>
1758<tr><td><code>sec</code></td>
1759    <td><em>x</em></td>
1760    <td>Secant of <em>x</em>.</td>
1761    <td></td>
1762    <td></td>
1763</tr>
1764<tr><td><code>sech</code></td>
1765    <td><em>x</em></td>
1766    <td>Hyperbolic secant of <em>x</em>.</td>
1767    <td></td>
1768    <td></td>
1769</tr>
1770<tr><td><code>sqr</code></td>
1771    <td><em>x</em></td>
1772    <td><em>x</em><sup><em>2</em></sup>.</td>
1773    <td></td>
1774    <td></td>
1775</tr>
1776<tr><td><code>sqrt</code></td>
1777    <td><em>x</em></td>
1778    <td>&radic;<em>x</em>.</td>
1779    <td><em>x</em> &gt; 0</td>
1780    <td><em>sqrt(x)</em> &ge; 0</td>
1781</tr>
1782<tr><td><code>sin</code></td>
1783    <td><em>x</em></td>
1784    <td>Sine of <em>x</em>.</td>
1785    <td></td>
1786    <td></td>
1787</tr>
1788<tr><td><code>sinh</code></td>
1789    <td><em>x</em></td>
1790    <td>Hyperbolic sine of <em>x</em>.</td>
1791    <td></td>
1792    <td></td>
1793</tr>
1794<tr><td><code>tan</code></td>
1795    <td><em>x</em></td>
1796    <td>Tangent of <em>x</em>.</td>
1797    <td>x &ne; n*&pi;/2, for odd integer <em>n</em></td>
1798    <td></td>
1799</tr>
1800<tr><td><code>tanh</code></td>
1801    <td><em>x</em></td>
1802    <td>Hyperbolic tangent of <em>x</em>.</td>
1803    <td></td>
1804    <td></td>
1805</tr>
1806<tr><td><code>and</code></td>
1807    <td><em>x, y, z...</em></td>
1808    <td>Boolean and(<em>x, y, z...</em>): returns true if all of its arguments are true.  Note that 'and' is an n-ary function, taking 0 or more arguments, and that and() returns 'true'.</td>
1809    <td>All arguments must be boolean</td>
1810    <td></td>
1811</tr>
1812<tr><td><code>not</code></td>
1813    <td><em>x</em></td>
1814    <td>Boolean not(<em>x</em>)</td>
1815    <td><em>x</em> must be boolean</td>
1816    <td></td>
1817</tr>
1818<tr><td><code>or</code></td>
1819    <td><em>x, y, z...</em></td>
1820    <td>Boolean or(<em>x, y, z...</em>): returns true if at least one of its arguments is true.  Note that 'or' is an n-ary function, taking 0 or more arguments, and that or() returns 'false'.</td>
1821    <td>All arguments must be boolean</td>
1822    <td></td>
1823</tr>
1824<tr><td><code>xor</code></td>
1825    <td><em>x, y, z...</em></td>
1826    <td>Boolean xor(<em>x, y, z...</em>): returns true if an odd number of its arguments is true.  Note that 'xor' is an n-ary function, taking 0 or more arguments, and that xor() returns 'false'.</td>
1827    <td>All arguments must be boolean</td>
1828    <td></td>
1829</tr>
1830<tr><td><code>eq</code></td>
1831    <td><em>x, y, z...</em></td>
1832    <td>Boolean eq(<em>x, y, z...</em>): returns true if all arguments are equal.  Note that 'eq' is an n-ary function, but must take 2 or more arguments.</td>
1833    <td></td>
1834    <td></td>
1835</tr>
1836<tr><td><code>geq</code></td>
1837    <td><em>x, y, z...</em></td>
1838    <td>Boolean geq(<em>x, y, z...</em>): returns true if each argument is greater than or equal to the argument following it.  Note that 'geq' is an n-ary function, but must take 2 or more arguments.</td>
1839    <td></td>
1840    <td></td>
1841</tr>
1842<tr><td><code>gt</code></td>
1843    <td><em>x, y, z...</em></td>
1844    <td>Boolean gt(<em>x, y, z...</em>): returns true if each argument is greater than the argument following it.  Note that 'gt' is an n-ary function, but must take 2 or more arguments.</td>
1845    <td></td>
1846    <td></td>
1847</tr>
1848<tr><td><code>leq</code></td>
1849    <td><em>x, y, z...</em></td>
1850    <td>Boolean leq(<em>x, y, z...</em>): returns true if each argument is less than or equal to the argument following it.  Note that 'leq' is an n-ary function, but must take 2 or more arguments.</td>
1851    <td></td>
1852    <td></td>
1853</tr>
1854<tr><td><code>lt</code></td>
1855    <td><em>x, y, z...</em></td>
1856    <td>Boolean lt(<em>x, y, z...</em>): returns true if each argument is less than the argument following it.  Note that 'lt' is an n-ary function, but must take 2 or more arguments.</td>
1857    <td></td>
1858    <td></td>
1859</tr>
1860<tr><td><code>neq</code></td>
1861    <td><em>x, y</em></td>
1862    <td>Boolean <em>x</em> != <em>y</em>: returns true unless x and y are equal.</td>
1863    <td></td>
1864    <td></td>
1865</tr>
1866<tr><td><code>plus</code></td>
1867    <td><em>x, y, z...</em></td>
1868    <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function.  Note that 'plus' is an n-ary function taking 0 or more arguments, and that 'plus()' returns 0.</td>
1869    <td></td>
1870    <td></td>
1871</tr>
1872<tr><td><code>times</code></td>
1873    <td><em>x, y, z...</em></td>
1874    <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function.  Note that 'times' is an n-ary function taking 0 or more arguments, and that 'times()' returns 1.</td>
1875    <td></td>
1876    <td></td>
1877</tr>
1878<tr><td><code>minus</code></td>
1879    <td><em>x, y</em></td>
1880    <td><em>x</em> - <em>y</em>.</td>
1881    <td></td>
1882    <td></td>
1883</tr>
1884<tr><td><code>divide</code></td>
1885    <td><em>x, y</em></td>
1886    <td><em>x</em> / <em>y</em>.</td>
1887    <td></td>
1888    <td></td>
1889</tr>
1890
1891<caption class="top-caption">The names of mathematical functions defined
1892in the text-string formula syntax understood by SBML_parseL3Formula() and
1893related functions.</caption>
1894
1895</table>
1896
1897
1898 <p>
1899 * Note that the manner in which the 'L3' versions of the formula parser and
1900 * formatter interpret the function &quot;<code>log</code>&quot; can be
1901 * changed.  To do so, callers should use the function <code><a
1902 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1903 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1904 * formula, {@link L3ParserSettings} settings)</a></code> 
1905 * and pass it an appropriate {@link L3ParserSettings} object.  By default,
1906 * unlike the SBML Level&nbsp;1 parser implemented by <code><a
1907 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String
1908 * formula)</a></code>, the string &quot;<code>log</code>&quot; is
1909 * interpreted as the base&nbsp;10 logarithm, and <em>not</em> as the natural
1910 * logarithm.  However, you can change the interpretation to be base-10 log,
1911 * natural log, or as an error; since the name 'log' by itself is ambiguous,
1912 * you require that the parser uses <code>log10</code> or <code>ln</code> instead, which are more
1913 * clear.  Please refer to <code><a
1914 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1915 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1916 * formula, {@link L3ParserSettings} settings)</a></code>.
1917 <p>
1918 * In addition, the following symbols will be translated to their MathML
1919 * equivalents, if no symbol with the same <code>SId</code> identifier string exists
1920 * in the {@link Model} object provided:
1921 <p>
1922 * <table border="0" class="centered text-table width80 normal-font alt-row-colors">
1923 <tr>
1924     <th align="left" width="60">Name</th>
1925     <th align="left" width="200">Meaning</th>
1926     <th align="left">MathML</th>
1927 </tr>
1928<tr><td><code>true</code></td>   
1929    <td>The boolean value <code>true</code></td>
1930    <td><code>&lt;true/&gt;</code></td>
1931</tr>
1932<tr><td><code>false</code></td>   
1933    <td>The boolean value <code>false</code></td>
1934    <td><code>&lt;false/&gt;</code></td>
1935</tr>
1936<tr><td><code>pi</code></td>   
1937    <td>The mathematical constant pi</td>
1938    <td><code>&lt;pi/&gt;</code></td>
1939</tr>
1940<tr><td><code>avogadro</code></td>   
1941    <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td>
1942    <td><code>&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"&gt; avogadro &lt;/csymbol/&gt;</code></td>
1943</tr>
1944<tr><td><code>time</code></td>   
1945    <td>Simulation time as defined in SBML</td>
1946    <td><code>&lt;csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"&gt; time &lt;/csymbol/&gt;</code></td>
1947</tr>
1948<tr><td><code>inf</code> or <code>infinity</code></td>   
1949    <td>The mathematical constant "infinity"</td>
1950    <td><code>&lt;infinity/&gt;</code></td>
1951</tr>
1952<tr><td><code>nan</code> or <code>notanumber</code></td>   
1953    <td>The mathematical concept "not a number"</td>
1954    <td><code>&lt;notanumber/&gt;</code></td>
1955</tr>
1956
1957<caption class="top-caption">The names of mathematical symbols defined
1958in the text-string formula syntax understood by
1959SBML_parseL3Formula() and related functions.
1960</caption>
1961</table>
1962
1963 <p>
1964 * Note that whether the string &quot;<code>avogadro</code>&quot; is parsed
1965 * as an AST node of type {@link  libsbmlConstants#AST_NAME_AVOGADRO
1966 * AST_NAME_AVOGADRO} or {@link  libsbmlConstants#AST_NAME AST_NAME}
1967 * is configurable; use the alternate version of this function, called <code><a
1968 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String,
1969 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String
1970 * formula, {@link L3ParserSettings} settings)</a></code>.  This
1971 * functionality is provided because SBML Level&nbsp;2 models may not use
1972 * {@link  libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes.
1973<p>
1974 * @param formula the text-string formula expression to be parsed
1975 <p>
1976 * @return the root node of an AST representing the mathematical formula,
1977 * or <code>null</code> if an error occurred while parsing the formula.  When <code>null</code>
1978 * is returned, an error is recorded internally; information about the
1979 * error can be retrieved using 
1980 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>.
1981 <p>
1982 <p>
1983 <p>
1984 <p>
1985 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
1986 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
1987 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
1988 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
1989 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
1990 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
1991 */ public
1992 static ASTNode parseL3Formula(String formula) {
1993    long cPtr = libsbmlJNI.parseL3Formula(formula);
1994    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
1995  }
1996
1997  
1998/**
1999 * Parses the given mathematical formula using specific a specific {@link Model} to
2000 * resolve symbols, and returns an Abstract Syntax Tree (AST)
2001 * representation of the result.
2002 <p>
2003 * This is identical to
2004 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>,
2005 * except that this function uses the given model in the argument <code>model</code>
2006 * to check against identifiers that appear in the <code>formula</code>.
2007 <p>
2008 * For more details about the parser, please see the definition of
2009 * the function <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>.
2010 <p>
2011 * @param formula the mathematical formula expression to be parsed
2012 <p>
2013 * @param model the {@link Model} object to use for checking identifiers
2014 <p>
2015 * @return the root node of an AST representing the mathematical formula,
2016 * or <code>null</code> if an error occurred while parsing the formula.  When <code>null</code>
2017 * is returned, an error is recorded internally; information about the
2018 * error can be retrieved using
2019 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>.
2020 <p>
2021 <p>
2022 <p>
2023 <p>
2024 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
2025 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
2026 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
2027 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
2028 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
2029 */ public
2030 static ASTNode parseL3FormulaWithModel(String formula, Model model) {
2031    long cPtr = libsbmlJNI.parseL3FormulaWithModel(formula, Model.getCPtr(model), model);
2032    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
2033  }
2034
2035  
2036/**
2037 * Parses the given mathematical formula using specific parser settings and
2038 * returns an Abstract Syntax Tree (AST) representation of the result.
2039 <p>
2040 * This is identical to
2041 <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>,
2042 * except that this function uses the parser settings given in the argument
2043 * <code>settings</code>.  The settings override the default parsing behavior.
2044 <p>
2045 * The parameter <code>settings</code> allows callers to change the following parsing
2046 * behaviors:
2047 <p>
2048 * <ul>
2049 * <li> Use a specific {@link Model} object against which identifiers to compare
2050 * identifiers.  This causes the parser to search the {@link Model} for identifiers
2051 * that the parser encounters in the formula.  If a given symbol in the
2052 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter},
2053 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the
2054 * symbol is assumed to refer to that model entity instead of any possible
2055 * mathematical terms with the same symbol.  For example, if the parser is
2056 * given a {@link Model} containing a {@link Species} with the identifier
2057 * &quot;<code>pi</code>&quot;, and the formula to be parsed is
2058 * &quot;<code>3*pi</code>&quot;, the MathML produced will contain the
2059 * construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of the
2060 * construct <code>&lt;pi/&gt;</code>.
2061 * <li> Whether to parse &quot;<code>log(x)</code>&quot; with a single
2062 * argument as the base 10
2063 * logarithm of x, the natural logarithm of x, or treat the case as an
2064 * error.
2065 * <li> Whether to parse &quot;<code>number id</code>&quot; by interpreting
2066 * <code>id</code> as the identifier of a unit of measurement associated with the
2067 * number, or whether to treat the case as an error.
2068 * <li> Whether to parse &quot;<code>avogadro</code>&quot; as an {@link ASTNode} of
2069 * type {@link  libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or
2070 * as type {@link  libsbmlConstants#AST_NAME AST_NAME}.
2071 * <li> Whether to always create explicit ASTNodes of type {@link 
2072 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or
2073 * collapse and remove minuses where possible.
2074 *
2075 * </ul> <p>
2076 * For more details about the parser, please see the definition of
2077 * {@link L3ParserSettings} and
2078 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>.
2079 <p>
2080 * @param formula the mathematical formula expression to be parsed
2081 <p>
2082 * @param settings the settings to be used for this parser invocation
2083 <p>
2084 * @return the root node of an AST representing the mathematical formula,
2085 * or <code>null</code> if an error occurred while parsing the formula.  When <code>null</code>
2086 * is returned, an error is recorded internally; information about the
2087 * error can be retrieved using
2088 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>.
2089 <p>
2090 <p>
2091 <p>
2092 <p>
2093 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
2094 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
2095 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
2096 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
2097 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
2098 */ public
2099 static ASTNode parseL3FormulaWithSettings(String formula, L3ParserSettings settings) {
2100    long cPtr = libsbmlJNI.parseL3FormulaWithSettings(formula, L3ParserSettings.getCPtr(settings), settings);
2101    return (cPtr == 0) ? null : new ASTNode(cPtr, true);
2102  }
2103
2104  
2105/**
2106 * Returns a copy of the default parser settings used by <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>.
2107 <p>
2108 * The settings structure allows callers to change the following parsing
2109 * behaviors:
2110 <p>
2111 * <ul>
2112 * <li> Use a specific {@link Model} object against which identifiers to compare
2113 * identifiers.  This causes the parser to search the {@link Model} for identifiers
2114 * that the parser encounters in the formula.  If a given symbol in the
2115 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter},
2116 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the
2117 * symbol is assumed to refer to that model entity instead of any possible
2118 * mathematical terms with the same symbol.  For example, if the parser is
2119 * given a {@link Model} containing a {@link Species} with the identifier
2120 * &quot;<code>pi</code>&quot;, and the formula to be parsed is
2121 * &quot;<code>3*pi</code>&quot;, the MathML produced will contain the
2122 * construct <code>&lt;ci&gt; pi &lt;/ci&gt;</code> instead of the
2123 * construct <code>&lt;pi/&gt;</code>.
2124 * <li> Whether to parse &quot;<code>log(x)</code>&quot; with a single
2125 * argument as the base 10
2126 * logarithm of x, the natural logarithm of x, or treat the case as an
2127 * error.
2128 * <li> Whether to parse &quot;<code>number id</code>&quot; by interpreting
2129 * <code>id</code> as the identifier of a unit of measurement associated with the
2130 * number, or whether to treat the case as an error.
2131 * <li> Whether to parse &quot;<code>avogadro</code>&quot; as an {@link ASTNode} of
2132 * type {@link  libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or
2133 * as type {@link  libsbmlConstants#AST_NAME AST_NAME}.
2134 * <li> Whether to always create explicit ASTNodes of type {@link 
2135 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or
2136 * collapse and remove minuses where possible.
2137 *
2138 * </ul> <p>
2139 * For more details about the parser, please see the definition of
2140 * {@link L3ParserSettings} and
2141 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>.
2142 <p>
2143 <p>
2144 <p>
2145 <p>
2146 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
2147 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
2148 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
2149 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
2150 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code>
2151 */ public
2152 static L3ParserSettings getDefaultL3ParserSettings() {
2153    long cPtr = libsbmlJNI.getDefaultL3ParserSettings();
2154    return (cPtr == 0) ? null : new L3ParserSettings(cPtr, true);
2155  }
2156
2157  
2158/**
2159 * Returns the last error reported by the parser.
2160 <p>
2161 * If <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 
2162 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>, or
2163 * <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula, {@link Model} model)</a></code> return <code>null</code>, an error is set internally which is accessible
2164 * via this function. 
2165 <p>
2166 * @return a string describing the error that occurred.  This will contain
2167 * the string the parser was trying to parse, which character it had parsed
2168 * when it encountered the error, and a description of the error.
2169 <p>
2170 <p>
2171 <p>
2172 <p>
2173 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code>
2174 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code>
2175 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>
2176 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code>
2177 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code>
2178 */ public
2179 static String getLastParseL3Error() {
2180    return libsbmlJNI.getLastParseL3Error();
2181  }
2182
2183  
2184/**
2185 * takes an annotation that has been read into the model
2186 * identifies the RDF elements
2187 * and creates a List of Layouts from the annotation
2188 */ public
2189 static void parseLayoutAnnotation(XMLNode annotation, ListOfLayouts layouts) {
2190    libsbmlJNI.parseLayoutAnnotation(XMLNode.getCPtr(annotation), annotation, ListOfLayouts.getCPtr(layouts), layouts);
2191  }
2192
2193  
2194/**
2195 * Takes an {@link XMLNode} and tries to find the layout annotation node and deletes it if it was found.
2196 */ public
2197 static XMLNode deleteLayoutAnnotation(XMLNode pAnnotation) {
2198    long cPtr = libsbmlJNI.deleteLayoutAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation);
2199    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
2200  }
2201
2202  
2203/**
2204 * Creates an {@link XMLNode} that represents the layouts of the model from the given {@link Model} object.
2205 */ public
2206 static XMLNode parseLayouts(Model pModel) {
2207    long cPtr = libsbmlJNI.parseLayouts(Model.getCPtr(pModel), pModel);
2208    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
2209  }
2210
2211  
2212/**
2213 * takes an annotation that has been read into the species reference
2214 * identifies the id elements and set the id of the species reference
2215 */ public
2216 static void parseSpeciesReferenceAnnotation(XMLNode annotation, SimpleSpeciesReference sr) {
2217    libsbmlJNI.parseSpeciesReferenceAnnotation(XMLNode.getCPtr(annotation), annotation, SimpleSpeciesReference.getCPtr(sr), sr);
2218  }
2219
2220  
2221/**
2222 * Takes an {@link XMLNode} and tries to find the layoutId annotation node and deletes it if it was found.
2223 */ public
2224 static XMLNode deleteLayoutIdAnnotation(XMLNode pAnnotation) {
2225    long cPtr = libsbmlJNI.deleteLayoutIdAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation);
2226    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
2227  }
2228
2229  
2230/**
2231 * Creates an {@link XMLNode} that represents the layoutId annotation of the species reference from the given {@link SpeciesReference} object.
2232 */ public
2233 static XMLNode parseLayoutId(SimpleSpeciesReference sr) {
2234    long cPtr = libsbmlJNI.parseLayoutId(SimpleSpeciesReference.getCPtr(sr), sr);
2235    return (cPtr == 0) ? null : new XMLNode(cPtr, true);
2236  }
2237
2238}