001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.11 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("layout")) 058 return new LayoutExtension(cPtr, owner); 059 060 061 if (pkgName.equals("comp")) 062 return new CompExtension(cPtr, owner); 063 064 065 if (pkgName.equals("fbc")) 066 return new FbcExtension(cPtr, owner); 067 068 069 return new SBMLExtension(cPtr,owner); 070 } 071 072 /** 073 * SBMLExtension derived classes must override this method 074 * @internal 075 */ 076 public static SBasePlugin DowncastSBasePlugin(long cPtr, boolean owner) 077 { 078 if (cPtr == 0) return null; 079 080 SBasePlugin sbp = new SBasePlugin(cPtr,false); 081 String pkgName = sbp.getPackageName(); 082 083 SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName); 084 if (sbmlext != null) 085 { 086 return sbmlext.DowncastSBasePlugin(cPtr,owner); 087 } 088 return new SBasePlugin(cPtr,owner); 089 } 090 091 /** 092 * @internal 093 */ 094 public static SBMLNamespaces DowncastSBMLNamespaces(long cPtr, boolean owner) 095 { 096 if (cPtr == 0) return null; 097 098 SBMLNamespaces sbn = new SBMLNamespaces(cPtr, false); 099 if (sbn != null) 100 { 101 XMLNamespaces ns = sbn.getNamespaces(); 102 103 104 105 if (ns.hasURI(FbcExtension.getXmlnsL3V1V1())) 106 { 107 return new FbcPkgNamespaces(cPtr, owner); 108 } 109 110 111 112 if (ns.hasURI(LayoutExtension.getXmlnsL3V1V1()) || ns.hasURI(LayoutExtension.getXmlnsL2())) 113 { 114 return new LayoutPkgNamespaces(cPtr, owner); 115 } 116 117 118 119 if (ns.hasURI(CompExtension.getXmlnsL3V1V1())) 120 { 121 return new CompPkgNamespaces(cPtr, owner); 122 } 123 124 125 } 126 return new SBMLNamespaces(cPtr, owner); 127 } 128 129 /** 130 * Internal method. 131 * 132 * @internal 133 */ 134 public static SBase DowncastSBase(long cPtr, boolean owner) 135 { 136 if (cPtr == 0) return null; 137 138 SBase sb = new SBase(cPtr,false); 139 String pkgName = sb.getPackageName(); 140 if (pkgName.equals("core")) 141 { 142 switch( sb.getTypeCode() ) 143 { 144 case libsbmlConstants.SBML_COMPARTMENT: 145 return new Compartment(cPtr, owner); 146 147 case libsbmlConstants.SBML_COMPARTMENT_TYPE: 148 return new CompartmentType(cPtr, owner); 149 150 case libsbmlConstants.SBML_CONSTRAINT: 151 return new Constraint(cPtr, owner); 152 153 case libsbmlConstants.SBML_DOCUMENT: 154 return new SBMLDocument(cPtr, owner); 155 156 case libsbmlConstants.SBML_DELAY: 157 return new Delay(cPtr, owner); 158 159 case libsbmlConstants.SBML_EVENT: 160 return new Event(cPtr, owner); 161 162 case libsbmlConstants.SBML_EVENT_ASSIGNMENT: 163 return new EventAssignment(cPtr, owner); 164 165 case libsbmlConstants.SBML_FUNCTION_DEFINITION: 166 return new FunctionDefinition(cPtr, owner); 167 168 case libsbmlConstants.SBML_INITIAL_ASSIGNMENT: 169 return new InitialAssignment(cPtr, owner); 170 171 case libsbmlConstants.SBML_KINETIC_LAW: 172 return new KineticLaw(cPtr, owner); 173 174 case libsbmlConstants.SBML_LIST_OF: 175 String name = sb.getElementName(); 176 if(name.equals("listOf")){ 177 return new ListOf(cPtr, owner); 178 } 179 else if(name.equals("listOfCompartments")){ 180 return new ListOfCompartments(cPtr, owner); 181 } 182 else if(name.equals("listOfCompartmentTypes")){ 183 return new ListOfCompartmentTypes(cPtr, owner); 184 } 185 else if(name.equals("listOfConstraints")){ 186 return new ListOfConstraints(cPtr, owner); 187 } 188 else if(name.equals("listOfEvents")){ 189 return new ListOfEvents(cPtr, owner); 190 } 191 else if(name.equals("listOfEventAssignments")){ 192 return new ListOfEventAssignments(cPtr, owner); 193 } 194 else if(name.equals("listOfFunctionDefinitions")){ 195 return new ListOfFunctionDefinitions(cPtr, owner); 196 } 197 else if(name.equals("listOfInitialAssignments")){ 198 return new ListOfInitialAssignments(cPtr, owner); 199 } 200 else if(name.equals("listOfParameters")){ 201 return new ListOfParameters(cPtr, owner); 202 } 203 else if(name.equals("listOfLocalParameters")){ 204 return new ListOfLocalParameters(cPtr, owner); 205 } 206 else if(name.equals("listOfReactions")){ 207 return new ListOfReactions(cPtr, owner); 208 } 209 else if(name.equals("listOfRules")){ 210 return new ListOfRules(cPtr, owner); 211 } 212 else if(name.equals("listOfSpecies")){ 213 return new ListOfSpecies(cPtr, owner); 214 } 215 else if(name.equals("listOfUnknowns")){ 216 return new ListOfSpeciesReferences(cPtr, owner); 217 } 218 else if(name.equals("listOfReactants")){ 219 return new ListOfSpeciesReferences(cPtr, owner); 220 } 221 else if(name.equals("listOfProducts")){ 222 return new ListOfSpeciesReferences(cPtr, owner); 223 } 224 else if(name.equals("listOfModifiers")){ 225 return new ListOfSpeciesReferences(cPtr, owner); 226 } 227 else if(name.equals("listOfSpeciesTypes")){ 228 return new ListOfSpeciesTypes(cPtr, owner); 229 } 230 else if(name.equals("listOfUnits")){ 231 return new ListOfUnits(cPtr, owner); 232 } 233 else if(name.equals("listOfUnitDefinitions")){ 234 return new ListOfUnitDefinitions(cPtr, owner); 235 } 236 return new ListOf(cPtr, owner); 237 238 case libsbmlConstants.SBML_MODEL: 239 return new Model(cPtr, owner); 240 241 case libsbmlConstants.SBML_PARAMETER: 242 return new Parameter(cPtr, owner); 243 244 case libsbmlConstants.SBML_PRIORITY: 245 return new Priority(cPtr, owner); 246 247 case libsbmlConstants.SBML_LOCAL_PARAMETER: 248 return new LocalParameter(cPtr, owner); 249 250 case libsbmlConstants.SBML_REACTION: 251 return new Reaction(cPtr, owner); 252 253 case libsbmlConstants.SBML_SPECIES: 254 return new Species(cPtr, owner); 255 256 case libsbmlConstants.SBML_SPECIES_REFERENCE: 257 return new SpeciesReference(cPtr, owner); 258 259 case libsbmlConstants.SBML_MODIFIER_SPECIES_REFERENCE: 260 return new ModifierSpeciesReference(cPtr, owner); 261 262 case libsbmlConstants.SBML_SPECIES_TYPE: 263 return new SpeciesType(cPtr, owner); 264 265 case libsbmlConstants.SBML_TRIGGER: 266 return new Trigger(cPtr, owner); 267 268 case libsbmlConstants.SBML_UNIT_DEFINITION: 269 return new UnitDefinition(cPtr, owner); 270 271 case libsbmlConstants.SBML_UNIT: 272 return new Unit(cPtr, owner); 273 274 case libsbmlConstants.SBML_ALGEBRAIC_RULE: 275 return new AlgebraicRule(cPtr, owner); 276 277 case libsbmlConstants.SBML_ASSIGNMENT_RULE: 278 return new AssignmentRule(cPtr, owner); 279 280 case libsbmlConstants.SBML_RATE_RULE: 281 return new RateRule(cPtr, owner); 282 283 case libsbmlConstants.SBML_STOICHIOMETRY_MATH: 284 return new StoichiometryMath(cPtr, owner); 285 286 default: 287 return new SBase(cPtr, owner); 288 } 289 } 290 else 291 { 292 SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName); 293 if (sbmlext != null) 294 { 295 return sbmlext.DowncastSBase(cPtr,owner); 296 } 297 } 298 return new SBase(cPtr, owner); 299 } 300 301 302 static String getAbsolutePath(String filename) 303 { 304 java.io.File file = new java.io.File(filename); 305 return file.getAbsolutePath(); 306 } 307 308 309 /** 310 * Stream handle for low-level C++ standard output stream. 311 * <p> 312 * A few libSBML methods accept an argument for indicating where to send 313 * text string output. An example is the {@link 314 * SBMLDocument#printErrors} method. However, the methods use C++ style 315 * streams and not Java stream objects. The OStream object class in the 316 * libSBML Java interface provides a wrapper for the underlying C++ 317 * streams. The present object (cout) is a static final variable that 318 * can be used directly from your code. An example use might be 319 * something like this: 320 * <p> 321 * <div class="fragment"><pre class="fragment"> 322 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 323 * if (document.getNumErrors() > 0) 324 * { 325 * document.printErrors(libsbml.cout); 326 * println("Please correct the above problems first."); 327 * System.exit(1); 328 * }</div> 329 * 330 * @see #cerr 331 * @see #clog 332 */ 333 public final static OStream cout; 334 335 336 /** 337 * Stream handle for low-level C++ standard error stream. 338 * <p> 339 * A few libSBML methods accept an argument for indicating where to send 340 * text string output. An example is the {@link 341 * SBMLDocument#printErrors} method. However, the methods use C++ style 342 * streams and not Java stream objects. The OStream object class in the 343 * libSBML Java interface provides a wrapper for the underlying C++ 344 * streams. The present object (cerr) is a static final variable that 345 * can be used directly from your code. An example use might be 346 * something like this: 347 * <p> 348 * <div class="fragment"><pre class="fragment"> 349 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 350 * if (document.getNumErrors() > 0) 351 * { 352 * document.printErrors(libsbml.cerr); 353 * println("Please correct the above problems first."); 354 * System.exit(1); 355 * }</div> 356 * <p> 357 * By default, most operating systems have have their standard error and 358 * logging output streams directed to the console/terminal, and this is 359 * where text messages will be shown. This can usually be redirected 360 * elsewhere, although how to do this depends on the specific environment 361 * where the program is running. 362 * 363 * @see #cout 364 * @see #clog 365 */ 366 public final static OStream cerr; 367 368 369 /** 370 * Stream handle for low-level C++ standard logging stream. 371 * <p> 372 * A few libSBML methods accept an argument for indicating where to send 373 * text string output. An example is the {@link 374 * SBMLDocument#printErrors} method. However, the methods use C++ style 375 * streams and not Java stream objects. The OStream object class in the 376 * libSBML Java interface provides a wrapper for the underlying C++ 377 * streams. The present object (clog) is a static final variable that 378 * can be used directly from your code. An example use might be 379 * something like this: 380 * <p> 381 * <div class="fragment"><pre class="fragment"> 382 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 383 * if (document.getNumErrors() > 0) 384 * { 385 * document.printErrors(libsbml.clog); 386 * println("Please correct the above problems first."); 387 * System.exit(1); 388 * }</div> 389 * <p> 390 * By default, most operating systems have have their standard error and 391 * logging output streams directed to the console/terminal, and this is 392 * where text messages will be shown. This can usually be redirected 393 * elsewhere, although how to do this depends on the specific environment 394 * where the program is running. 395 * 396 * @see #cout 397 * @see #cerr 398 */ 399 public final static OStream clog; 400 401 static { 402 cout = new OStream(OStream.COUT); 403 cerr = new OStream(OStream.CERR); 404 clog = new OStream(OStream.CLOG); 405 } 406 407 /** 408 * This private constructor does nothing and never invoked. 409 * The purpose of this constuctor is to hide a default constructor of this 410 * class in javadoc documentation. 411 */ 412 private libsbml() {} 413 414 415 416/** 417 * Returns the version number of this copy of libSBML as an integer. 418 * <p> 419 * @return the libSBML version as an integer; version 1.2.3 becomes 10203. 420 */ public 421 static int getLibSBMLVersion() { 422 return libsbmlJNI.getLibSBMLVersion(); 423 } 424 425 426/** 427 * Returns the version number of this copy of libSBML as a string. 428 * <p> 429 * @return the libSBML version as a string; version 1.2.3 becomes 430 * '1.2.3'. 431 * <p> 432 * @see #getLibSBMLVersionString() 433 */ public 434 static String getLibSBMLDottedVersion() { 435 return libsbmlJNI.getLibSBMLDottedVersion(); 436 } 437 438 439/** 440 * Returns the version number of this copy of libSBML as a string without 441 * periods. 442 * <p> 443 * @return the libSBML version as a string: version 1.2.3 becomes '10203'. 444 * <p> 445 * @see #getLibSBMLDottedVersion() 446 */ public 447 static String getLibSBMLVersionString() { 448 return libsbmlJNI.getLibSBMLVersionString(); 449 } 450 451 452/** 453 * Reads an SBML document from the given file <code>filename</code>. 454 * <p> 455 * If <code>filename</code> does not exist, or it is not an SBML file, an error will 456 * be logged in the error log of the {@link SBMLDocument} object returned by this 457 * method. Calling programs can inspect this error log to determine 458 * the nature of the problem. Please refer to the definition of 459 * {@link SBMLDocument} for more information about the error reporting mechanism. 460 * <p> 461 * @return a pointer to the {@link SBMLDocument} read. 462 */ public 463 static SBMLDocument readSBML(String filename) { 464 long cPtr = libsbmlJNI.readSBML(libsbml.getAbsolutePath(filename)); 465 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 466 } 467 468 469/** 470 * Reads an SBML document from the given file <code>filename</code>. 471 * <p> 472 * If <code>filename</code> does not exist, or it is not an SBML file, an error will 473 * be logged in the error log of the {@link SBMLDocument} object returned by this 474 * method. Calling programs can inspect this error log to determine 475 * the nature of the problem. Please refer to the definition of 476 * {@link SBMLDocument} for more information about the error reporting mechanism. 477 * <p> 478 * @return a pointer to the {@link SBMLDocument} read. 479 */ public 480 static SBMLDocument readSBMLFromFile(String filename) { 481 long cPtr = libsbmlJNI.readSBMLFromFile(libsbml.getAbsolutePath(filename)); 482 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 483 } 484 485 486/** 487 * Reads an SBML document from a string assumed to be in XML format. 488 * <p> 489 * If the string does not begin with XML declaration, 490 *<div class='fragment'><pre> 491<?xml version='1.0' encoding='UTF-8'?> 492</pre></div> 493 * <p> 494 * an XML declaration string will be prepended. 495 * <p> 496 * This method will report an error if the given string <code>xml</code> is not SBML. 497 * The error will be logged in the error log of the {@link SBMLDocument} object 498 * returned by this method. Calling programs can inspect this error log to 499 * determine the nature of the problem. Please refer to the definition of 500 * {@link SBMLDocument} for more information about the error reporting mechanism. 501 * <p> 502 * @return a pointer to the {@link SBMLDocument} read. 503 */ public 504 static SBMLDocument readSBMLFromString(String xml) { 505 long cPtr = libsbmlJNI.readSBMLFromString(xml); 506 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 507 } 508 509 510/** 511 * Writes the given SBML document <code>d</code> to the file named by <code>filename</code>. 512 * <p> 513 * This function is identical to <a href='#writeSBMLToFile(org.sbml.libsbml.SBMLDocument, java.lang.String)'><code>writeSBMLToFile(SBMLDocument d, String filename)</code></a>. 514 * <p> 515 * If the given filename ends with the suffix <code>".gz"</code> 516(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 517caller wants the file to be written compressed in <em>gzip</em> format. 518Similarly, if the given filename ends with <code>".zip"</code> or 519<code>".bz2"</code>, libSBML assumes the caller wants the file to 520be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 521Files whose names lack these suffixes will be written uncompressed. 522<em>Special considerations for the zip format</em>: If the given filename 523ends with <code>".zip"</code>, the file placed in the zip archive 524will have the suffix <code>".xml"</code> or 525<code>".sbml"</code>. For example, the file in the zip archive 526will be named <code>"test.xml"</code> if the given filename is 527<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 528Similarly, the filename in the archive will be 529<code>"test.sbml"</code> if the given filename is 530<code>"test.sbml.zip"</code>. 531 532 * <p> 533 * @param d the {@link SBMLDocument} object to be written out in XML format 534 * <p> 535 * @param filename a string giving the path to a file where the XML 536 * content is to be written. 537 * <p> 538 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be 539 * written. Some possible reasons for failure include (a) being unable to 540 * open the file, and (b) using a filename that indicates a compressed SBML 541 * file (i.e., a filename ending in <code>".zip"</code> or 542 * similar) when the compression functionality has not been enabled in 543 * the underlying copy of libSBML. 544 * <p> 545 * <p> 546 * <p> 547 * @see SBMLWriter#hasZlib() 548 * @see SBMLWriter#hasBzip2() 549 */ public 550 static int writeSBML(SBMLDocument d, String filename) { 551 return libsbmlJNI.writeSBML(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 552 } 553 554 555/** 556 * Writes the given SBML document <code>d</code> to an in-memory string and 557 * returns the string. 558 * <p> 559 * This is a convenience function that uses the 560 * {@link SBMLWriter#writeSBMLToString(SBMLDocument d)} method internally, 561 * yet does not require the caller to create an {@link SBMLWriter} object first. 562 * <p> 563 * @param d an {@link SBMLDocument} object to be written out in XML format 564 * <p> 565 * @return the string on success and <code>null</code> if one of the underlying parser 566 * components fail. 567 * <p> 568 * <p> 569 */ public 570 static String writeSBMLToString(SBMLDocument d) { 571 return libsbmlJNI.writeSBMLToString(SBMLDocument.getCPtr(d), d); 572 } 573 574 575/** 576 * Writes the given SBML document <code>d</code> to the file <code>filename</code>. 577 * <p> 578 * This is a convenience function that uses the 579 * {@link SBMLWriter#writeSBMLToFile(SBMLDocument d, String 580 * filename)} method internally, yet does not require the caller to create 581 * an {@link SBMLWriter} object first. 582 * <p> 583 * If the given filename ends with the suffix <code>".gz"</code> 584(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 585caller wants the file to be written compressed in <em>gzip</em> format. 586Similarly, if the given filename ends with <code>".zip"</code> or 587<code>".bz2"</code>, libSBML assumes the caller wants the file to 588be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 589Files whose names lack these suffixes will be written uncompressed. 590<em>Special considerations for the zip format</em>: If the given filename 591ends with <code>".zip"</code>, the file placed in the zip archive 592will have the suffix <code>".xml"</code> or 593<code>".sbml"</code>. For example, the file in the zip archive 594will be named <code>"test.xml"</code> if the given filename is 595<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 596Similarly, the filename in the archive will be 597<code>"test.sbml"</code> if the given filename is 598<code>"test.sbml.zip"</code>. 599 600 * <p> 601 * @param d an {@link SBMLDocument} object to be written out in XML format 602 * <p> 603 * @param filename a string giving the path to a file where the XML 604 * content is to be written. 605 * <p> 606 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be 607 * written. Some possible reasons for failure include (a) being unable to 608 * open the file, and (b) using a filename that indicates a compressed SBML 609 * file (i.e., a filename ending in <code>".zip"</code> or 610 * similar) when the compression functionality has not been enabled in 611 * the underlying copy of libSBML. 612 * <p> 613 * <p> 614 * <p> 615 * @see SBMLWriter#hasZlib() 616 * @see SBMLWriter#hasBzip2() 617 */ public 618 static int writeSBMLToFile(SBMLDocument d, String filename) { 619 return libsbmlJNI.writeSBMLToFile(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 620 } 621 622 623/** 624 * This method takes an SBML type code and returns a string representing 625 * the code. 626 * <p> 627 * LibSBML attaches an identifying code to every 628 * kind of SBML object. These are known as <em>SBML type codes</em>. In 629 * other languages, the set of type codes is stored in an enumeration; in 630 * the Java language interface for libSBML, the type codes are defined as 631 * static integer constants in the interface class {@link 632 * libsbmlConstants}. The names of the type codes all begin with the 633 * characters <code>SBML_.</code> 634 * <p> 635 * @return a human readable name for the given 636 * SBML type code. 637 * <p> 638 * @note The caller does not own the returned string and is therefore not 639 * allowed to modify it. 640 */ public 641 static String SBMLTypeCode_toString(int tc, String pkgName) { 642 return libsbmlJNI.SBMLTypeCode_toString(tc, pkgName); 643 } 644 645 646/** 647 * Tests for logical equality between two given <code>UNIT_KIND_</code> 648 * code values. 649 * <p> 650 * This function behaves exactly like C's <code>==</code> operator, except 651 * for the following two cases: 652 * <ul> 653 * <li>{@link libsbmlConstants#UNIT_KIND_LITER UNIT_KIND_LITER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_LITRE UNIT_KIND_LITRE} 654 * <li>{@link libsbmlConstants#UNIT_KIND_METER UNIT_KIND_METER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_METRE UNIT_KIND_METRE} 655 * </ul> 656 * <p> 657 * In the two cases above, C equality comparison would yield <code>false</code> 658 * (because each of the above is a distinct enumeration value), but 659 * this function returns <code>true.</code> 660 * <p> 661 * @param uk1 a <code>UNIT_KIND_</code> value 662 * @param uk2 a second <code>UNIT_KIND_</code> value to compare to <code>uk1</code> 663 * <p> 664 * @return nonzero (for <code>true</code>) if <code>uk1</code> is logically equivalent to 665 * <code>uk2</code>, zero (for <code>false</code>) otherwise. 666 * <p> 667 * @note For more information about the libSBML unit codes, please refer to 668 * the class documentation for {@link Unit}. 669 */ public 670 static int UnitKind_equals(int uk1, int uk2) { 671 return libsbmlJNI.UnitKind_equals(uk1, uk2); 672 } 673 674 675/** 676 * Converts a text string naming a kind of unit to its corresponding 677 * libSBML <code>UNIT_KIND_</code> constant/enumeration value. 678 * <p> 679 * @param name a string, the name of a predefined base unit in SBML 680 * <p> 681 * @return a value the set of <code>UNIT_KIND_</code> codes 682 * defined in class {@link libsbmlConstants}, corresponding to the string 683 * <code>name</code> (determined in a case-insensitive manner). 684 * <p> 685 * @note For more information about the libSBML unit codes, please refer to 686 * the class documentation for {@link Unit}. 687 */ public 688 static int UnitKind_forName(String name) { 689 return libsbmlJNI.UnitKind_forName(name); 690 } 691 692 693/** 694 * Converts a unit code to a text string equivalent. 695 * <p> 696 * @param uk a value from the set of <code>UNIT_KIND_</code> codes 697 * defined in the class {@link libsbmlConstants} 698 * <p> 699 * <p> 700 * @return the name corresponding to the given unit code. 701 * <p> 702 * @note For more information about the libSBML unit codes, please refer to 703 * the class documentation for {@link Unit}. 704 * <p> 705 * @warning The string returned is a static data value. The caller does not 706 * own the returned string and is therefore not allowed to modify it. 707 */ public 708 static String UnitKind_toString(int uk) { 709 return libsbmlJNI.UnitKind_toString(uk); 710 } 711 712 713/** 714 * Predicate for testing whether a given string corresponds to a 715 * predefined libSBML unit code. 716 * <p> 717 * @param str a text string naming a base unit defined by SBML 718 * @param level the Level of SBML 719 * @param version the Version within the Level of SBML 720 * <p> 721 * @return nonzero (for <code>true</code>) if string is the name of a valid 722 * <code>UNIT_KIND_</code> value, zero (for <code>false</code>) otherwise. 723 * <p> 724 * @note For more information about the libSBML unit codes, please refer to 725 * the class documentation for {@link Unit}. 726 */ public 727 static int UnitKind_isValidUnitKindString(String str, long level, long version) { 728 return libsbmlJNI.UnitKind_isValidUnitKindString(str, level, version); 729 } 730 731 732/** 733 * Reads the MathML from the given XML string, constructs a corresponding 734 * abstract syntax tree, and returns a pointer to the root of the tree. 735 * <p> 736 * @param xml a string containing a full MathML expression 737 * <p> 738 * @return the root of an AST corresponding to the given mathematical 739 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code> 740 * or invalid. 741 */ public 742 static ASTNode readMathMLFromString(String xml) { 743 long cPtr = libsbmlJNI.readMathMLFromString(xml); 744 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 745 } 746 747 748/** 749 * Writes the given {@link ASTNode} (and its children) to a string as MathML, and 750 * returns the string. 751 * <p> 752 * @param node the root of an AST to write out to the stream. 753 * <p> 754 * @return a string containing the written-out MathML representation 755 * of the given AST. 756 * <p> 757 * @note The string is owned by the caller and should be freed (with 758 * free()) when no longer needed. <code>null</code> is returned if the given 759 * argument is <code>null.</code> 760 */ public 761 static String writeMathMLToString(ASTNode node) { 762 return libsbmlJNI.writeMathMLToString(ASTNode.getCPtr(node), node); 763 } 764 765 766/** 767 * Parses the given SBML formula and returns a representation of it as an 768 * Abstract Syntax Tree (AST). 769 * <p> 770 * The text-string form of mathematical formulas produced by 771 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 772 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 773 * and 774 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 775 * use a simple C-inspired infix notation. A 776 * formula in this text-string form therefore can be handed to a program 777 * that understands SBML mathematical expressions, or used as 778 * part of a formula translation system. The syntax is described in detail 779 * in the documentation for {@link ASTNode}. 780 * <p> 781 * This returns the root node of the AST corresponding to the formula. If 782 * the formula contains a syntax error, <code>null</code> is returned instead. 783 * <p> 784 * Note that this facility is provided as a convenience by libSBML—the 785 * MathML standard does not actually define a 'string-form' equivalent to 786 * MathML expression trees, so the choice of formula syntax is somewhat 787 * arbitrary. The approach taken by libSBML is to use the syntax defined by 788 * SBML Level 1 (which in fact used a text-string representation of 789 * formulas and not MathML). This formula syntax is based mostly on C 790 * programming syntax, and may contain operators, function calls, symbols, 791 * and white space characters. The following table provides the precedence 792 * rules for the different entities that may appear in formula strings. 793 * <p> 794 * <center style='padding-bottom: 0.5em'> 795<table border='0' class='text-table width80 normal-font alt-row-colors'> 796 <tr style='background: lightgray; font-size: 14px;'> 797 <th align='left'>Token</th> 798 <th align='left'>Operation</th> 799 <th align='left'>Class</th> 800 <th>Precedence</th> 801 <th align='left'>Associates</th> 802 </tr> 803<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align='center'>6</td><td>n/a</td></tr> 804<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> 805<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> 806<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align='center'>5</td><td>right</td></tr> 807<tr><td><code>^</code></td><td>power</td><td>binary</td><td align='center'>4</td><td>left</td></tr> 808<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align='center'>3</td><td>left</td></tr> 809<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align='center'>3</td><td>left</td></tr> 810<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align='center'>2</td><td>left</td></tr> 811<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align='center'>2</td><td>left</td></tr> 812<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align='center'>1</td><td>left</td></tr> 813<caption class='top-caption'>A table of the expression operators and their precedence in the 814text-string format for mathematical expressions used by SBML_parseFormula(). 815</caption> 816</table> 817</center> 818 819 * <p> 820 * In the table above, <em>operand</em> implies the construct is an operand, 821 * <em>prefix</em> implies the operation is applied to the following arguments, 822 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 823 * two arguments. The values in the <b>Precedence</b> column show how the 824 * order of different types of operation are determined. For example, the 825 * expression <code>a * b + c</code> is evaluated as <code>(a * b) + 826 * c</code> because the @c * operator has higher precedence. The 827 * <b>Associates</b> column shows how the order of similar precedence 828 * operations is determined; for example, <code>a - b + c</code> is 829 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code> 830 * operators are left-associative. 831 * <p> 832 * The function call syntax consists of a function name, followed by optional 833 * white space, followed by an opening parenthesis token, followed by a 834 * sequence of zero or more arguments separated by commas (with each comma 835 * optionally preceded and/or followed by zero or more white space 836 * characters, followed by a closing parenthesis token. The function name 837 * must be chosen from one of the pre-defined functions in SBML or a 838 * user-defined function in the model. The following table lists the names 839 * of certain common mathematical functions; this table corresponds to 840 * 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>: 841 * <p> 842 * <center> 843<table border='0' class='text-table width80 normal-font alt-row-colors'> 844 <tr> 845 <th align='left' width='60'>Name</th> 846 <th align='left' width='35'>Args</th> 847 <th align='left'>Formula or meaning</th> 848 <th align='left' width='110'>Argument Constraints</th> 849 <th align='left' width='100'>Result constraints</th> 850 </tr> 851<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr> 852<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> 853<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> 854<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> 855<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> 856<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr> 857<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> 858<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> 859<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> 860<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> 861<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> 862<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> 863<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> 864<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr> 865<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> 866<caption class='bottom-caption'>The names of mathematical functions defined in the SBML 867Level 1 Version 2 text-string formula syntax.</caption> 868</table> 869</center> 870 871 * <p> 872 * @warning There are differences between the symbols used to represent the 873 * common mathematical functions and the corresponding MathML token names. 874 * This is a potential source of incompatibilities. Note in particular that 875 * in this text-string syntax, <code>log(x)</code> represents the natural 876 * logarithm, whereas in MathML, the natural logarithm is 877 * <code><ln/></code>. Application writers are urged to be careful 878 * when translating between text forms and MathML forms, especially if they 879 * provide a direct text-string input facility to users of their software 880 * systems.<br><br> 881 * We urge developers to keep in mind that the text-string formula syntax is 882specific to SBML Level 1's C-like mathematical formula syntax. In 883particular, it is <em>not a general-purpose mathematical expression 884syntax</em>. LibSBML provides methods for parsing and transforming 885text-string math formulas back and forth from AST structures, but it is 886important to keep the system's limitations in mind. 887 888 * <p> 889 * @param formula the text-string formula expression to be parsed 890 * <p> 891 * @return the root node of the AST, or null if an error occurred in 892 * parsing the formula 893 * <p> 894 * <p> 895 * <p> 896 * <p> 897 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 898 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 899 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 900 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 901 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 902 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 903 * <p> 904 */ public 905 static ASTNode parseFormula(String formula) { 906 long cPtr = libsbmlJNI.parseFormula(formula); 907 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 908 } 909 910 911/** 912 * Converts an AST to a string representation of a formula using a syntax 913 * basically derived from SBML Level 1. 914 * <p> 915 * The text-string form of mathematical formulas produced by 916 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 917 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 918 * use a simple C-inspired infix notation taken from SBML Level 1. A 919 * formula in this text-string form therefore can be handed to a program 920 * that understands SBML Level 1 mathematical expressions, or used as 921 * part of a formula translation system. The syntax is described in detail 922 * in the documentation for {@link ASTNode}. 923 * <p> 924 * Note that this facility is provided as a convenience by libSBML—the 925 * MathML standard does not actually define a 'string-form' equivalent to 926 * MathML expression trees, so the choice of formula syntax is somewhat 927 * arbitrary. The approach taken by libSBML is to use the syntax defined by 928 * SBML Level 1 (which in fact used a text-string representation of 929 * formulas and not MathML). This formula syntax is based mostly on C 930 * programming syntax, and may contain operators, function calls, symbols, 931 * and white space characters. The following table provides the precedence 932 * rules for the different entities that may appear in formula strings. 933 * <p> 934 * <center style='padding-bottom: 0.5em'> 935<table border='0' class='text-table width80 normal-font alt-row-colors'> 936 <tr style='background: lightgray; font-size: 14px;'> 937 <th align='left'>Token</th> 938 <th align='left'>Operation</th> 939 <th align='left'>Class</th> 940 <th>Precedence</th> 941 <th align='left'>Associates</th> 942 </tr> 943<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align='center'>6</td><td>n/a</td></tr> 944<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> 945<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> 946<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align='center'>5</td><td>right</td></tr> 947<tr><td><code>^</code></td><td>power</td><td>binary</td><td align='center'>4</td><td>left</td></tr> 948<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align='center'>3</td><td>left</td></tr> 949<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align='center'>3</td><td>left</td></tr> 950<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align='center'>2</td><td>left</td></tr> 951<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align='center'>2</td><td>left</td></tr> 952<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align='center'>1</td><td>left</td></tr> 953<caption class='top-caption'>A table of the expression operators and their precedence in the 954text-string format for mathematical expressions used by SBML_parseFormula(). 955</caption> 956</table> 957</center> 958 959 * <p> 960 * In the table above, <em>operand</em> implies the construct is an operand, 961 * <em>prefix</em> implies the operation is applied to the following arguments, 962 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 963 * two arguments. The values in the <b>Precedence</b> column show how the 964 * order of different types of operation are determined. For example, the 965 * expression <code>a * b + c</code> is evaluated as <code>(a * b) + 966 * c</code> because the @c * operator has higher precedence. The 967 * <b>Associates</b> column shows how the order of similar precedence 968 * operations is determined; for example, <code>a - b + c</code> is 969 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code> 970 * operators are left-associative. 971 * <p> 972 * The function call syntax consists of a function name, followed by optional 973 * white space, followed by an opening parenthesis token, followed by a 974 * sequence of zero or more arguments separated by commas (with each comma 975 * optionally preceded and/or followed by zero or more white space 976 * characters, followed by a closing parenthesis token. The function name 977 * must be chosen from one of the pre-defined functions in SBML or a 978 * user-defined function in the model. The following table lists the names 979 * of certain common mathematical functions; this table corresponds to 980 * 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>: 981 * <p> 982 * <center> 983<table border='0' class='text-table width80 normal-font alt-row-colors'> 984 <tr> 985 <th align='left' width='60'>Name</th> 986 <th align='left' width='35'>Args</th> 987 <th align='left'>Formula or meaning</th> 988 <th align='left' width='110'>Argument Constraints</th> 989 <th align='left' width='100'>Result constraints</th> 990 </tr> 991<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr> 992<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> 993<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> 994<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> 995<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> 996<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr> 997<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> 998<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> 999<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> 1000<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> 1001<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> 1002<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> 1003<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> 1004<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr> 1005<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> 1006<caption class='bottom-caption'>The names of mathematical functions defined in the SBML 1007Level 1 Version 2 text-string formula syntax.</caption> 1008</table> 1009</center> 1010 1011 * <p> 1012 * @warning There are differences between the symbols used to represent the 1013 * common mathematical functions and the corresponding MathML token names. 1014 * This is a potential source of incompatibilities. Note in particular that 1015 * in this text-string syntax, <code>log(x)</code> represents the natural 1016 * logarithm, whereas in MathML, the natural logarithm is 1017 * <code><ln/></code>. Application writers are urged to be careful 1018 * when translating between text forms and MathML forms, especially if they 1019 * provide a direct text-string input facility to users of their software 1020 * systems.<br><br> 1021 * We urge developers to keep in mind that the text-string formula syntax is 1022specific to SBML Level 1's C-like mathematical formula syntax. In 1023particular, it is <em>not a general-purpose mathematical expression 1024syntax</em>. LibSBML provides methods for parsing and transforming 1025text-string math formulas back and forth from AST structures, but it is 1026important to keep the system's limitations in mind. 1027 1028 * <p> 1029 * @param tree the AST to be converted. 1030 * <p> 1031 * @return the formula from the given AST as an SBML Level 1 text-string 1032 * mathematical formula. The caller owns the returned string and is 1033 * responsible for freeing it when it is no longer needed. 1034 * <p> 1035 * <p> 1036 * <p> 1037 * <p> 1038 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1039 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1040 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1041 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1042 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1043 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1044 * <p> 1045 */ public 1046 static String formulaToString(ASTNode tree) { 1047 return libsbmlJNI.formulaToString(ASTNode.getCPtr(tree), tree); 1048 } 1049 1050 1051/** 1052 * Parses the given mathematical formula and returns a representation of it 1053 * as an Abstract Syntax Tree (AST). 1054 * <p> 1055 * The text-string form of mathematical formulas read by this function 1056 * are expanded versions of the formats produced and read by <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 1057 * and 1058 * <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>, 1059 * respectively. The latter two libSBML functions were originally 1060 * developed to support conversion between SBML Levels 1 and 2, 1061 * and were focused on the syntax of mathematical formulas used in SBML 1062 * Level 1. With time, and the use of MathML in SBML Levels 2 1063 * and 3, it became clear that supporting Level 2 and 3's 1064 * expanded mathematical syntax would be useful for software developers. 1065 * To maintain backwards compatibility, the original 1066 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 1067 * and 1068 * <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1069 * have been left untouched, and instead, the new functionality is 1070 * provided in the form of 1071 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 1072 * <p> 1073 * The following are the differences in the formula syntax supported by 1074 * this function, compared to what is supported by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>: 1075 * <p> 1076 * <ul> 1077 * <li> Units may be asociated with bare numbers, using the following syntax: 1078 * <div style='margin: 10px auto 10px 25px; display: block'> 1079 * <span class='code' style='background-color: #d0d0ee'>number</span> 1080 * <span class='code' style='background-color: #edd'>unit</span> 1081 * </div> 1082 * The <span class='code' style='background-color: #d0d0ee'>number</span> 1083 * may be in any form (an integer, real, or rational 1084 * number), and the 1085 * <span class='code' style='background-color: #edd'>unit</span> 1086 * must conform to the syntax of an SBML identifier (technically, the 1087 * type defined as <code>SId</code> in the SBML specifications). The whitespace between 1088 * <span class='code' style='background-color: #d0d0ee'>number</span> 1089 * and <span class='code' style='background-color: #edd'>unit</span> 1090 * is optional. 1091 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be used. 1092 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and 1093 * will produce a piecewise function in the MathML. 1094 * <li> All inverse trigonometric functions may be defined in the infix 1095 * either using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both 1096 * <code>arccsc</code> and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> 1097 * defined in MathML. (Many functions in the SBML Level 1 infix-notation 1098 * parser implemented by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1099 * are defined this way as well, but not all.) 1100 * <li> The following expression is parsed as a rational number instead of 1101 * as a numerical division: 1102 * <pre style='display: block; margin-left: 25px'> 1103 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre> 1104 * No spaces are allowed in this construct; in other words, 1105 * "<code>(3 / 4)</code>" will be parsed into the MathML 1106 * <code><divide></code> construct rather than a rational number. The 1107 * general number syntax allows you to assign units to a rational number, e.g., 1108 * "<code>(3/4) ml</code>". (If the string is a division, units 1109 * are not interpreted in this way.) 1110 * <li> Various settings may be altered by using an {@link L3ParserSettings} object 1111 * in conjunction with the alternative function call 1112 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>, including the following: 1113 * <ul> 1114 * <li> The function <code>log</code> with a single argument ("<code>log(x)</code>") 1115 * can be parsed as <code>log10(x)</code>, <code>ln(x)</code>, or treated 1116 * as an error, as desired. 1117 * <li> Unary minus signs can be collapsed or preserved; that is, 1118 * sequential pairs of unary minuses (e.g., "<code>- -3</code>") 1119 * can be removed from the input entirely and single unary minuses can be 1120 * incorporated into the number node, or all minuses can be preserved in 1121 * the AST node structure. 1122 * <li> Parsing of units embedded in the input string can be turned on and 1123 * off. 1124 * <li> The string <code>avogadro</code> can be parsed as a MathML <em>csymbol</em> or 1125 * as an identifier. 1126 * <li> A {@link Model} object may optionally be provided to the parser using 1127 * the variant function call <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula, {@link Model} model)</a></code>. 1128 * or stored in a {@link L3ParserSettings} object passed to the variant function 1129 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>. 1130 * When a {@link Model} object is provided, identifiers (values of type <code>SId</code>) 1131 * from that model are used in preference to pre-defined MathML 1132 * definitions. More precisely, the {@link Model} entities whose identifiers will 1133 * shadow identical symbols in the mathematical formula are: {@link Species}, 1134 * {@link Compartment}, {@link Parameter}, {@link Reaction}, and {@link SpeciesReference}. For instance, 1135 * if the parser is given a {@link Model} containing a {@link Species} with the identifier 1136 * "<code>pi</code>", and the formula to be parsed is 1137 * "<code>3*pi</code>", the MathML produced will contain the 1138 * construct <code><ci> pi </ci></code> instead of the 1139 * construct <code><pi/></code>. 1140 * <li> Similarly, when a {@link Model} object is provided, <code>SId</code> values of 1141 * user-defined functions present in the model will be used preferentially 1142 * over pre-defined MathML functions. For example, if the passed-in {@link Model} 1143 * contains a {@link FunctionDefinition} with the identifier 1144 * "<code>sin</code>", that function will be used instead of the 1145 * predefined MathML function <code><sin/></code>. 1146 * </ul> 1147 * These configuration settings cannot be changed using <em>this</em> function 1148 * (i.e., <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>), 1149 * but they can be change on a per-call basis by using the alternative function 1150 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code> 1151 * </ul> 1152 * <p> 1153 * This function returns the root node of the AST corresponding to the 1154 * formula given as the argument. If the formula contains a syntax error, 1155 * this function will return <code>null</code> instead. When <code>null</code> is returned, an 1156 * error is set; information about the error can be retrieved using 1157 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1158 * <p> 1159 * Note that this facility and the SBML Level 1-based <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1160 * are provided as a convenience by libSBML—the MathML standard does not 1161 * actually define a 'string-form' equivalent to MathML expressions, so the 1162 * choice of formula syntax is arbitrary. The approach taken by libSBML is 1163 * to start with the syntax defined by SBML Level 1 (which in fact 1164 * used a text-string representation of formulas, and not MathML), and 1165 * expand it to include the above functionality. This formula syntax is 1166 * based mostly on C programming syntax, and may contain operators, 1167 * function calls, symbols, and white space characters. The following 1168 * table provides the precedence rules for the different entities that may 1169 * appear in formula strings. 1170 * <p> 1171 * <center style='padding-bottom: 0.5em'> 1172<table border='0' class='text-table width80 normal-font alt-row-colors'> 1173 <tr style='background: lightgray; font-size: 14px;'> 1174 <th align='left'>Token</th> 1175 <th align='left'>Operation</th> 1176 <th align='left'>Class</th> 1177 <th>Precedence</th> 1178 <th align='left'>Associates</th> 1179 </tr> 1180<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align='center'>10</td><td>n/a</td></tr> 1181<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align='center'>10</td><td>n/a</td></tr> 1182<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align='center'>9</td><td>left</td></tr> 1183<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align='center'>8</td><td>right</td></tr> 1184<tr><td><code>^</code></td><td>power</td><td>binary</td><td align='center'>7</td><td>left</td></tr> 1185<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align='center'>6</td><td>left</td></tr> 1186<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align='center'>5</td><td>left</td></tr> 1187<tr><td><code>!</code></td><td>boolean 'not'</td><td>unary</td><td align='center'>4</td><td>right</td></tr> 1188<tr><td><code>==, <, >, <=, >=, !=</code></td><td>boolean equality, inequality, and comparison</td><td>binary</td><td align='center'>3</td><td>left</td></tr> 1189<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align='center'>2</td><td>left</td></tr> 1190<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align='center'>1</td><td>left</td></tr> 1191<caption class='top-caption'>A table of the expression operators and their precedence in the 1192text-string format for mathematical expressions used by SBML_parseL3Formula(). 1193</caption> 1194</table> 1195</center> 1196 1197 * <p> 1198 * In the table above, <em>operand</em> implies the construct is an operand, 1199 * <em>prefix</em> implies the operation is applied to the following arguments, 1200 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 1201 * two arguments. The values in the <b>Precedence</b> column show how the 1202 * order of different types of operation are determined. For example, the 1203 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code> 1204 * because the @c * operator has higher precedence. The 1205 * <b>Associates</b> column shows how the order of similar precedence 1206 * operations is determined; for example, <code>a && b || c</code> is 1207 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code> 1208 * operators are left-associative and have the same precedence. 1209 * <p> 1210 * The function call syntax consists of a function name, followed by optional 1211 * white space, followed by an opening parenthesis token, followed by a 1212 * sequence of zero or more arguments separated by commas (with each comma 1213 * optionally preceded and/or followed by zero or more white space 1214 * characters), followed by a closing parenthesis token. The function name 1215 * must be chosen from one of the pre-defined functions in SBML or a 1216 * user-defined function in the model. The following table lists the names 1217 * of certain common mathematical functions; this table corresponds to 1218 * 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> with additions based on the 1219 * functions added in SBML Level 2 and Level 3: 1220 * <p> 1221 * <center> 1222<table border='0' class='text-table width80 normal-font alt-row-colors'> 1223 <tr> 1224 <th align='left' width='100'>Name</th> 1225 <th align='left' width='100'>Argument(s)</th> 1226 <th align='left'>Formula or meaning</th> 1227 <th align='left' width='110'>Argument Constraints</th> 1228 <th align='left' width='100'>Result constraints</th> 1229 </tr> 1230<tr><td><code>abs</code></td> 1231 <td><em>x</em></td> 1232 <td>Absolute value of <em>x</em>.</td> 1233 <td></td> 1234 <td></td> 1235</tr> 1236<tr><td><code>acos</code>, <code>arccos</code></td> 1237 <td><em>x</em></td> 1238 <td>Arccosine of <em>x</em> in radians.</td> 1239 <td>-1.0 ≤ <em>x</em> ≤ 1.0</td> 1240 <td>0 ≤ <em>acos(x)</em> ≤ π</td> 1241</tr> 1242<tr><td><code>acosh</code>, <code>arccosh</code></td> 1243 <td><em>x</em></td> 1244 <td>Hyperbolic arccosine of <em>x</em> in radians.</td> 1245 <td></td> 1246 <td></td> 1247</tr> 1248<tr><td><code>acot</code>, <code>arccot</code></td> 1249 <td><em>x</em></td> 1250 <td>Arccotangent of <em>x</em> in radians.</td> 1251 <td></td> 1252 <td></td> 1253</tr> 1254<tr><td><code>acoth</code>, <code>arccoth</code></td> 1255 <td><em>x</em></td> 1256 <td>Hyperbolic arccotangent of <em>x</em> in radians.</td> 1257 <td></td> 1258 <td></td> 1259</tr> 1260<tr><td><code>acsc</code>, <code>arccsc</code></td> 1261 <td><em>x</em></td> 1262 <td>Arccosecant of <em>x</em> in radians.</td> 1263 <td></td> 1264 <td></td> 1265</tr> 1266<tr><td><code>acsch</code>, <code>arccsch</code></td> 1267 <td><em>x</em></td> 1268 <td>Hyperbolic arccosecant of <em>x</em> in radians.</td> 1269 <td></td> 1270 <td></td> 1271</tr> 1272<tr><td><code>asec</code>, <code>arcsec</code></td> 1273 <td><em>x</em></td> 1274 <td>Arcsecant of <em>x</em> in radians.</td> 1275 <td></td> 1276 <td></td> 1277</tr> 1278<tr><td><code>asech</code>, <code>arcsech</code></td> 1279 <td><em>x</em></td> 1280 <td>Hyperbolic arcsecant of <em>x</em> in radians.</td> 1281 <td></td> 1282 <td></td> 1283</tr> 1284<tr><td><code>asin</code>, <code>arcsin</code></td> 1285 <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td> 1286 <td>-1.0 ≤ <em>x</em> ≤ 1.0</td> 1287 <td>0 ≤ <em>asin(x)</em> ≤ π</td> 1288</tr> 1289<tr><td><code>atan</code>, <code>arctan</code></td> 1290 <td><em>x</em></td> 1291 <td>Arctangent of <em>x</em> in radians.</td> 1292 <td></td> 1293 <td>0 ≤ <em>atan(x)</em> ≤ π</td> 1294</tr> 1295<tr><td><code>atanh</code>, <code>arctanh</code></td> 1296 <td><em>x</em></td> 1297 <td>Hyperbolic arctangent of <em>x</em> in radians.</td> 1298 <td></td> 1299 <td></td> 1300</tr> 1301<tr><td><code>ceil</code>, <code>ceiling</code></td> 1302 <td><em>x</em></td> 1303 <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td> 1304 <td></td> 1305 <td></td> 1306</tr> 1307<tr><td><code>cos</code></td> 1308 <td><em>x</em></td> 1309 <td>Cosine of <em>x</em></td> 1310 <td></td> 1311 <td></td> 1312</tr> 1313<tr><td><code>cosh</code></td> 1314 <td><em>x</em></td> 1315 <td>Hyperbolic cosine of <em>x</em>.</td> 1316 <td></td> 1317 <td></td> 1318</tr> 1319<tr><td><code>cot</code></td> 1320 <td><em>x</em></td> 1321 <td>Cotangent of <em>x</em>.</td> 1322 <td></td> 1323 <td></td> 1324</tr> 1325<tr><td><code>coth</code></td> 1326 <td><em>x</em></td> 1327 <td>Hyperbolic cotangent of <em>x</em>.</td> 1328 <td></td> 1329 <td></td> 1330</tr> 1331<tr><td><code>csc</code></td> 1332 <td><em>x</em></td> 1333 <td>Cosecant of <em>x</em>.</td> 1334 <td></td> 1335 <td></td> 1336</tr> 1337<tr><td><code>csch</code></td> 1338 <td><em>x</em></td> 1339 <td>Hyperbolic cosecant of <em>x</em>.</td> 1340 <td></td> 1341 <td></td> 1342</tr> 1343<tr><td><code>delay</code></td> 1344 <td><em>x, y</em></td> 1345 <td>The value of <em>x</em> at <em>y</em> time units in the past.</td> 1346 <td></td> 1347 <td></td> 1348</tr> 1349<tr><td><code>factorial</code></td> 1350 <td><em>n</em></td> 1351 <td>The factorial of <em>n</em>. Factorials are defined by n! = n*(n-1)* ... * 1.</td> 1352 <td><em>n</em> must be an integer.</td> 1353 <td></td> 1354</tr> 1355<tr><td><code>exp</code></td> 1356 <td><em>x</em></td> 1357 <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td> 1358 <td></td> 1359 <td></td> 1360</tr> 1361<tr><td><code>floor</code></td> 1362 <td><em>x</em></td> 1363 <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td> 1364 <td></td> 1365 <td></td> 1366</tr> 1367<tr><td><code>ln</code></td> 1368 <td><em>x</em></td> 1369 <td>Natural logarithm of <em>x</em>.</td> 1370 <td><em>x</em> > 0</td> 1371 <td></td> 1372</tr> 1373<tr><td><code>log</code></td> 1374 <td><em>x</em></td> 1375 <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> 1376 <td><em>x</em> > 0</td> 1377 <td></td> 1378</tr> 1379<tr><td><code>log</code></td> 1380 <td><em>x, y</em></td> 1381 <td>The base <em>x</em> logarithm of <em>y</em>.</td> 1382 <td><em>y</em> > 0</td> 1383 <td></td> 1384</tr> 1385<tr><td><code>log10</code></td> 1386 <td><em>x</em></td> 1387 <td>Base 10 logarithm of <em>x</em>.</td> 1388 <td><em>x</em> > 0</td> 1389 <td></td> 1390</tr> 1391<tr><td><code>piecewise</code></td> 1392 <td><em>x1, y1, [x2, y2,] [...] [z]</em></td> 1393 <td>A piecewise function: if (<em>y1</em>), <em>x1</em>. Otherwise, if (<em>y2</em>), <em>x2</em>, etc. Otherwise, z. </td> 1394 <td><em>y1, y2, y3 [etc]</em> must be boolean</td> 1395 <td></td> 1396</tr> 1397<tr><td><code>pow</code>, <code>power</code> </td> 1398 <td><em>x, y</em></td> 1399 <td><em>x</em><sup><em> y</em></sup>.</td> 1400 <td></td> 1401 <td></td> 1402</tr> 1403<tr><td><code>root</code></td> 1404 <td><em>b, x</em></td> 1405 <td>The root base <em>b</em> of <em>x</em>.</td> 1406 <td></td> 1407 <td></td> 1408</tr> 1409<tr><td><code>sec</code></td> 1410 <td><em>x</em></td> 1411 <td>Secant of <em>x</em>.</td> 1412 <td></td> 1413 <td></td> 1414</tr> 1415<tr><td><code>sech</code></td> 1416 <td><em>x</em></td> 1417 <td>Hyperbolic secant of <em>x</em>.</td> 1418 <td></td> 1419 <td></td> 1420</tr> 1421<tr><td><code>sqr</code></td> 1422 <td><em>x</em></td> 1423 <td><em>x</em><sup><em>2</em></sup>.</td> 1424 <td></td> 1425 <td></td> 1426</tr> 1427<tr><td><code>sqrt</code></td> 1428 <td><em>x</em></td> 1429 <td>√<em>x</em>.</td> 1430 <td><em>x</em> > 0</td> 1431 <td><em>sqrt(x)</em> ≥ 0</td> 1432</tr> 1433<tr><td><code>sin</code></td> 1434 <td><em>x</em></td> 1435 <td>Sine of <em>x</em>.</td> 1436 <td></td> 1437 <td></td> 1438</tr> 1439<tr><td><code>sinh</code></td> 1440 <td><em>x</em></td> 1441 <td>Hyperbolic sine of <em>x</em>.</td> 1442 <td></td> 1443 <td></td> 1444</tr> 1445<tr><td><code>tan</code></td> 1446 <td><em>x</em></td> 1447 <td>Tangent of <em>x</em>.</td> 1448 <td>x ≠ n*π/2, for odd integer <em>n</em></td> 1449 <td></td> 1450</tr> 1451<tr><td><code>tanh</code></td> 1452 <td><em>x</em></td> 1453 <td>Hyperbolic tangent of <em>x</em>.</td> 1454 <td></td> 1455 <td></td> 1456</tr> 1457<tr><td><code>and</code></td> 1458 <td><em>x, y, z...</em></td> 1459 <td>Boolean and(<em>x, y, z...</em>): returns true if all of its arguments are true. Note that 'and' is an n-ary function, taking 0 or more arguments, and that and() returns 'true'.</td> 1460 <td>All arguments must be boolean</td> 1461 <td></td> 1462</tr> 1463<tr><td><code>not</code></td> 1464 <td><em>x</em></td> 1465 <td>Boolean not(<em>x</em>)</td> 1466 <td><em>x</em> must be boolean</td> 1467 <td></td> 1468</tr> 1469<tr><td><code>or</code></td> 1470 <td><em>x, y, z...</em></td> 1471 <td>Boolean or(<em>x, y, z...</em>): returns true if at least one of its arguments is true. Note that 'or' is an n-ary function, taking 0 or more arguments, and that or() returns 'false'.</td> 1472 <td>All arguments must be boolean</td> 1473 <td></td> 1474</tr> 1475<tr><td><code>xor</code></td> 1476 <td><em>x, y, z...</em></td> 1477 <td>Boolean xor(<em>x, y, z...</em>): returns true if an odd number of its arguments is true. Note that 'xor' is an n-ary function, taking 0 or more arguments, and that xor() returns 'false'.</td> 1478 <td>All arguments must be boolean</td> 1479 <td></td> 1480</tr> 1481<tr><td><code>eq</code></td> 1482 <td><em>x, y, z...</em></td> 1483 <td>Boolean eq(<em>x, y, z...</em>): returns true if all arguments are equal. Note that 'eq' is an n-ary function, but must take 2 or more arguments.</td> 1484 <td></td> 1485 <td></td> 1486</tr> 1487<tr><td><code>geq</code></td> 1488 <td><em>x, y, z...</em></td> 1489 <td>Boolean geq(<em>x, y, z...</em>): returns true if each argument is greater than or equal to the argument following it. Note that 'geq' is an n-ary function, but must take 2 or more arguments.</td> 1490 <td></td> 1491 <td></td> 1492</tr> 1493<tr><td><code>gt</code></td> 1494 <td><em>x, y, z...</em></td> 1495 <td>Boolean gt(<em>x, y, z...</em>): returns true if each argument is greater than the argument following it. Note that 'gt' is an n-ary function, but must take 2 or more arguments.</td> 1496 <td></td> 1497 <td></td> 1498</tr> 1499<tr><td><code>leq</code></td> 1500 <td><em>x, y, z...</em></td> 1501 <td>Boolean leq(<em>x, y, z...</em>): returns true if each argument is less than or equal to the argument following it. Note that 'leq' is an n-ary function, but must take 2 or more arguments.</td> 1502 <td></td> 1503 <td></td> 1504</tr> 1505<tr><td><code>lt</code></td> 1506 <td><em>x, y, z...</em></td> 1507 <td>Boolean lt(<em>x, y, z...</em>): returns true if each argument is less than the argument following it. Note that 'lt' is an n-ary function, but must take 2 or more arguments.</td> 1508 <td></td> 1509 <td></td> 1510</tr> 1511<tr><td><code>neq</code></td> 1512 <td><em>x, y</em></td> 1513 <td>Boolean <em>x</em> != <em>y</em>: returns true unless x and y are equal.</td> 1514 <td></td> 1515 <td></td> 1516</tr> 1517<tr><td><code>plus</code></td> 1518 <td><em>x, y, z...</em></td> 1519 <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function. Note that 'plus' is an n-ary function taking 0 or more arguments, and that 'plus()' returns 0.</td> 1520 <td></td> 1521 <td></td> 1522</tr> 1523<tr><td><code>times</code></td> 1524 <td><em>x, y, z...</em></td> 1525 <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function. Note that 'times' is an n-ary function taking 0 or more arguments, and that 'times()' returns 1.</td> 1526 <td></td> 1527 <td></td> 1528</tr> 1529<tr><td><code>minus</code></td> 1530 <td><em>x, y</em></td> 1531 <td><em>x</em> - <em>y</em>.</td> 1532 <td></td> 1533 <td></td> 1534</tr> 1535<tr><td><code>divide</code></td> 1536 <td><em>x, y</em></td> 1537 <td><em>x</em> / <em>y</em>.</td> 1538 <td></td> 1539 <td></td> 1540</tr> 1541 1542<caption class='top-caption'>The names of mathematical functions defined 1543in the text-string formula syntax understood by SBML_parseL3Formula() and 1544related functions.</caption> 1545 1546</table> 1547</center> 1548 1549 * <p> 1550 * Note that this function's interpretation of the string 1551 * "<code>log</code>" as a function with a single argument can be 1552 * changed; use the function <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code> 1553 * instead of this function and pass it an appropriate {@link L3ParserSettings} 1554 * object. By default, unlike the SBML Level 1 parser implemented by 1555 * <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code>, 1556 * the string "<code>log</code>" is interpreted as the base 10 1557 * logarithm, and <em>not</em> as the natural logarithm. However, you can change 1558 * the interpretation to be base-10 log, natural log, or as an error; since 1559 * the name 'log' by itself is ambiguous, you require that the parser uses 1560 * <code>log10</code> or <code>ln</code> instead, which are more clear. Please refer to 1561 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>. 1562 * <p> 1563 * In addition, the following symbols will be translated to their MathML 1564 * equivalents, if no symbol with the same <code>SId</code> identifier string exists 1565 * in the {@link Model} object provided: 1566 * <p> 1567 * <center> 1568<table border='0' class='text-table width80 normal-font alt-row-colors'> 1569 <tr> 1570 <th align='left' width='60'>Name</th> 1571 <th align='left' width='200'>Meaning</th> 1572 <th align='left'>MathML</th> 1573 </tr> 1574<tr><td><code>true</code></td> 1575 <td>The boolean value <code>true</code></td> 1576 <td><code><true/></code></td> 1577</tr> 1578<tr><td><code>false</code></td> 1579 <td>The boolean value <code>false</code></td> 1580 <td><code><false/></code></td> 1581</tr> 1582<tr><td><code>pi</code></td> 1583 <td>The mathematical constant pi</td> 1584 <td><code><pi/></code></td> 1585</tr> 1586<tr><td><code>avogadro</code></td> 1587 <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td> 1588 <td><code><csymbol encoding='text' definitionURL='http://www.sbml.org/sbml/symbols/avogadro'> avogadro </csymbol/></code></td> 1589</tr> 1590<tr><td><code>time</code></td> 1591 <td>Simulation time as defined in SBML</td> 1592 <td><code><csymbol encoding='text' definitionURL='http://www.sbml.org/sbml/symbols/time'> time </csymbol/></code></td> 1593</tr> 1594<tr><td><code>inf</code> or <code>infinity</code></td> 1595 <td>The mathematical constant 'infinity'</td> 1596 <td><code><infinity/></code></td> 1597</tr> 1598<tr><td><code>nan</code> or <code>notanumber</code></td> 1599 <td>The mathematical concept 'not a number'</td> 1600 <td><code><notanumber/></code></td> 1601</tr> 1602 1603<caption class='top-caption'>The names of mathematical symbols defined 1604in the text-string formula syntax understood by 1605SBML_parseL3Formula() and related functions. 1606</caption> 1607</table> 1608</center> 1609 1610 * <p> 1611 * Note that whether the string "<code>avogadro</code>" is parsed 1612 * as an AST node of type {@link libsbmlConstants#AST_NAME_AVOGADRO 1613 * AST_NAME_AVOGADRO} or {@link libsbmlConstants#AST_NAME 1614 * AST_NAME} is configurable; use the alternate version of this 1615 * function, called 1616 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>. 1617 * This functionality is provided because SBML Level 2 models may not 1618 * use {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes. 1619 * <p> 1620 * @param formula the text-string formula expression to be parsed 1621 * <p> 1622 * @return the root node of an AST representing the mathematical formula, 1623 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 1624 * is returned, an error is recorded internally; information about the 1625 * error can be retrieved using 1626 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1627 * <p> 1628 * <p> 1629 * <p> 1630 * <p> 1631 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1632 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1633 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1634 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1635 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1636 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1637 * <p> 1638 */ public 1639 static ASTNode parseL3Formula(String formula) { 1640 long cPtr = libsbmlJNI.parseL3Formula(formula); 1641 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1642 } 1643 1644 1645/** 1646 * Parses the given mathematical formula using specific a specific {@link Model} to 1647 * resolve symbols, and returns an Abstract Syntax Tree (AST) 1648 * representation of the result. 1649 * <p> 1650 * This is identical to 1651 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 1652 * except that this function uses the given model in the argument <code>model</code> 1653 * to check against identifiers that appear in the <code>formula</code>. 1654 * <p> 1655 * For more details about the parser, please see the definition of 1656 * the function <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 1657 * <p> 1658 * @param formula the mathematical formula expression to be parsed 1659 * <p> 1660 * @param model the {@link Model} object to use for checking identifiers 1661 * <p> 1662 * @return the root node of an AST representing the mathematical formula, 1663 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 1664 * is returned, an error is recorded internally; information about the 1665 * error can be retrieved using 1666 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1667 * <p> 1668 * <p> 1669 * <p> 1670 * <p> 1671 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1672 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1673 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1674 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1675 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1676 * <p> 1677 */ public 1678 static ASTNode parseL3FormulaWithModel(String formula, Model model) { 1679 long cPtr = libsbmlJNI.parseL3FormulaWithModel(formula, Model.getCPtr(model), model); 1680 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1681 } 1682 1683 1684/** 1685 * Parses the given mathematical formula using specific parser settings and 1686 * returns an Abstract Syntax Tree (AST) representation of the result. 1687 * <p> 1688 * This is identical to 1689 <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 1690 * except that this function uses the parser settings given in the argument 1691 * <code>settings</code>. The settings override the default parsing behavior. 1692 * <p> 1693 * The parameter <code>settings</code> allows callers to change the following parsing 1694 * behaviors: 1695 * <p> 1696 * <ul> 1697 * <li> Use a specific {@link Model} object against which identifiers to compare 1698 * identifiers. This causes the parser to search the {@link Model} for identifiers 1699 * that the parser encounters in the formula. If a given symbol in the 1700 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter}, 1701 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the 1702 * symbol is assumed to refer to that model entity instead of any possible 1703 * mathematical terms with the same symbol. For example, if the parser is 1704 * given a {@link Model} containing a {@link Species} with the identifier 1705 * "<code>pi</code>", and the formula to be parsed is 1706 * "<code>3*pi</code>", the MathML produced will contain the 1707 * construct <code><ci> pi </ci></code> instead of the 1708 * construct <code><pi/></code>. 1709 * <li> Whether to parse "<code>log(x)</code>" with a single 1710 * argument as the base 10 1711 * logarithm of x, the natural logarithm of x, or treat the case as an 1712 * error. 1713 * <li> Whether to parse "<code>number id</code>" by interpreting 1714 * <code>id</code> as the identifier of a unit of measurement associated with the 1715 * number, or whether to treat the case as an error. 1716 * <li> Whether to parse "<code>avogadro</code>" as an {@link ASTNode} of 1717 * type {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or 1718 * as type {@link libsbmlConstants#AST_NAME AST_NAME}. 1719 * <li> Whether to always create explicit ASTNodes of type {@link 1720 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or 1721 * collapse and remove minuses where possible. 1722 * </ul> 1723 * <p> 1724 * For more details about the parser, please see the definition of 1725 * {@link L3ParserSettings} and 1726 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 1727 * <p> 1728 * @param formula the mathematical formula expression to be parsed 1729 * <p> 1730 * @param settings the settings to be used for this parser invocation 1731 * <p> 1732 * @return the root node of an AST representing the mathematical formula, 1733 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 1734 * is returned, an error is recorded internally; information about the 1735 * error can be retrieved using 1736 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1737 * <p> 1738 * <p> 1739 * <p> 1740 * <p> 1741 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1742 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1743 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1744 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1745 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1746 * <p> 1747 */ public 1748 static ASTNode parseL3FormulaWithSettings(String formula, L3ParserSettings settings) { 1749 long cPtr = libsbmlJNI.parseL3FormulaWithSettings(formula, L3ParserSettings.getCPtr(settings), settings); 1750 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1751 } 1752 1753 1754/** 1755 * Returns a copy of the default parser settings used by <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 1756 * <p> 1757 * The settings structure allows callers to change the following parsing 1758 * behaviors: 1759 * <p> 1760 * <ul> 1761 * <li> Use a specific {@link Model} object against which identifiers to compare 1762 * identifiers. This causes the parser to search the {@link Model} for identifiers 1763 * that the parser encounters in the formula. If a given symbol in the 1764 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter}, 1765 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the 1766 * symbol is assumed to refer to that model entity instead of any possible 1767 * mathematical terms with the same symbol. For example, if the parser is 1768 * given a {@link Model} containing a {@link Species} with the identifier 1769 * "<code>pi</code>", and the formula to be parsed is 1770 * "<code>3*pi</code>", the MathML produced will contain the 1771 * construct <code><ci> pi </ci></code> instead of the 1772 * construct <code><pi/></code>. 1773 * <li> Whether to parse "<code>log(x)</code>" with a single 1774 * argument as the base 10 1775 * logarithm of x, the natural logarithm of x, or treat the case as an 1776 * error. 1777 * <li> Whether to parse "<code>number id</code>" by interpreting 1778 * <code>id</code> as the identifier of a unit of measurement associated with the 1779 * number, or whether to treat the case as an error. 1780 * <li> Whether to parse "<code>avogadro</code>" as an {@link ASTNode} of 1781 * type {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or 1782 * as type {@link libsbmlConstants#AST_NAME AST_NAME}. 1783 * <li> Whether to always create explicit ASTNodes of type {@link 1784 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or 1785 * collapse and remove minuses where possible. 1786 * </ul> 1787 * <p> 1788 * For more details about the parser, please see the definition of 1789 * {@link L3ParserSettings} and 1790 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 1791 * <p> 1792 * <p> 1793 * <p> 1794 * <p> 1795 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1796 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1797 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1798 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1799 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1800 * <p> 1801 */ public 1802 static L3ParserSettings getDefaultL3ParserSettings() { 1803 long cPtr = libsbmlJNI.getDefaultL3ParserSettings(); 1804 return (cPtr == 0) ? null : new L3ParserSettings(cPtr, true); 1805 } 1806 1807 1808/** 1809 * Returns the last error reported by the parser. 1810 * <p> 1811 * If <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 1812 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>, or 1813 * <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula, {@link Model} model)</a></code> return <code>null</code>, an error is set internally which is accessible 1814 * via this function. 1815 * <p> 1816 * @return a string describing the error that occurred. This will contain 1817 * the string the parser was trying to parse, which character it had parsed 1818 * when it encountered the error, and a description of the error. 1819 * <p> 1820 * <p> 1821 * <p> 1822 * <p> 1823 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1824 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1825 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1826 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1827 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1828 * <p> 1829 */ public 1830 static String getLastParseL3Error() { 1831 return libsbmlJNI.getLastParseL3Error(); 1832 } 1833 1834 public static void parseLayoutAnnotation(XMLNode annotation, ListOfLayouts layouts) { 1835 libsbmlJNI.parseLayoutAnnotation(XMLNode.getCPtr(annotation), annotation, ListOfLayouts.getCPtr(layouts), layouts); 1836 } 1837 1838 public static XMLNode deleteLayoutAnnotation(XMLNode pAnnotation) { 1839 long cPtr = libsbmlJNI.deleteLayoutAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation); 1840 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 1841 } 1842 1843 public static XMLNode parseLayouts(Model pModel) { 1844 long cPtr = libsbmlJNI.parseLayouts(Model.getCPtr(pModel), pModel); 1845 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 1846 } 1847 1848 public static void parseSpeciesReferenceAnnotation(XMLNode annotation, SimpleSpeciesReference sr) { 1849 libsbmlJNI.parseSpeciesReferenceAnnotation(XMLNode.getCPtr(annotation), annotation, SimpleSpeciesReference.getCPtr(sr), sr); 1850 } 1851 1852 public static XMLNode deleteLayoutIdAnnotation(XMLNode pAnnotation) { 1853 long cPtr = libsbmlJNI.deleteLayoutIdAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation); 1854 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 1855 } 1856 1857 public static XMLNode parseLayoutId(SimpleSpeciesReference sr) { 1858 long cPtr = libsbmlJNI.parseLayoutId(SimpleSpeciesReference.getCPtr(sr), sr); 1859 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 1860 } 1861 1862}