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