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