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