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