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