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