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