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 * A definition of a unit used in an SBML model. 013 <p> 014 * Units of measurement may be supplied in a number of contexts in an SBML 015 * model. The SBML unit definition facility uses two classes of objects, 016 * {@link UnitDefinition} and {@link Unit}. The approach to defining units in SBML is 017 * compositional; for example, <em>meter second<sup> –2</sup></em> is 018 * constructed by combining a {@link Unit} object representing <em>meter</em> with 019 * another {@link Unit} object representing <em>second<sup> –2</sup></em>. 020 * The combination is wrapped inside a {@link UnitDefinition}, which provides for 021 * assigning an identifier and optional name to the combination. The 022 * identifier can then be referenced from elsewhere in a model. Thus, the 023 * {@link UnitDefinition} class is the container, and {@link Unit} instances are placed 024 * inside {@link UnitDefinition} instances. 025 <p> 026 * Two points are worth discussing in the context of SBML units. First, 027 * unit declarations in SBML models are <em>optional</em>. The consequence of 028 * this is that a model must be numerically self-consistent independently 029 * of unit declarations, for the benefit of software tools that cannot 030 * interpret or manipulate units. {@link Unit} declarations in SBML are thus more 031 * akin to a type of annotation; they can indicate intentions, and can be 032 * used by model readers for checking the consistency of the model, 033 * labeling simulation output, etc., but any transformations of values 034 * implied by different units must be incorporated <em>explicitly</em> into a 035 * model. 036 <p> 037 * Second, the vast majority of situations that require new SBML unit 038 * definitions involve simple multiplicative combinations of base units and 039 * factors. An example is <em>moles per litre per second</em>. What 040 * distinguishes these sorts of unit definitions from more complex ones is 041 * that they may be expressed without the use of an additive offset from a 042 * zero point. The use of offsets complicates all unit definition systems, 043 * yet in the domain of SBML, the real-life cases requiring offsets are few 044 * (and in fact, to the best of our knowledge, only involve temperature). 045 * Consequently, the SBML unit system has been consciously designed to 046 * simplify implementation of unit support for the most common cases in 047 * systems biology. The cost of this simplification is to require units 048 * with offsets to be handled explicitly by the modeler. 049 <p> 050 * <h2>Summary of the {@link UnitDefinition} construct</h2> 051 <p> 052 * {@link UnitDefinition} has two attributes and one subelement. The two 053 * attributes are 'id' and 'name', and the subelement is {@link ListOfUnits}. 054 <p> 055 * The required attribute 'id' and optional attribute 'name' are both 056 * strings. The 'id' attribute is used to give the defined unit a unique 057 * identifier by which other parts of an SBML model definition can refer to 058 * it. The 'name' attribute is intended to be used for giving the unit 059 * definition an optional human-readable name. Please see the <a 060 * href='#unitdef-id'>next section</a> for information about the values 061 * permitted for 'id'. 062 <p> 063 * A {@link UnitDefinition} must contain exactly one {@link ListOfUnits}, and this list 064 * must contain one or more {@link Unit} definitions; see the definitions of these 065 * other object classes for more information about them. The following 066 * example illustrates a complete unit definition (when written in XML) 067 * when they all the pieces are combined together. This defines 'mmls' 068 * to be millimoles per litre per second. 069 * <pre class='fragment'> 070 <listOfUnitDefinitions> 071 <unitDefinition id='mmls'> 072 <listOfUnits> 073 <unit kind='mole' scale='-3'/> 074 <unit kind='litre' exponent='-1'/> 075 <unit kind='second' exponent='-1'/> 076 </listOfUnits> 077 </unitDefinition> 078 </listOfUnitDefinitions> 079 </pre> 080 <p> 081 * <h2>Special considerations for {@link Unit} object identifiers</h2> 082 <p> 083 * The attribute 'id' in {@link UnitDefinition} cannot be given simply any value, 084 * and the precise details of the values permitted differ slightly between 085 * Levels of SBML: 086 * <ul> 087 <p> 088 * <li> The 'id' of a {@link UnitDefinition} must <em>not</em> contain a value from the 089 * list of SBML's predefined base unit names (i.e., the strings <code>gram</code>, 090 * <code>litre</code>, etc.). In SBML Level 3, this list consists of the 091 * following: 092 <p> 093 * <p> 094<table border='0' class='centered text-table width80 normal-font code' 095 style='border: none !important'> 096<tr> 097<td>ampere</td><td>farad</td><td>joule</td><td>lux</td><td>radian</td><td>volt</td> 098</tr> 099<tr> 100<td>avogadro</td><td>gram</td><td>katal</td><td>metre</td><td>second</td><td>watt</td> 101</tr> 102<tr> 103<td>becquerel</td><td>gray</td><td>kelvin</td><td>mole</td><td>siemens</td><td>weber</td> 104</tr> 105<tr> 106<td>candela</td><td>henry</td><td>kilogram</td><td>newton</td><td>sievert</td> 107</tr> 108<tr> 109<td>coulomb</td><td>hertz</td><td>litre</td><td>ohm</td><td>steradian</td> 110</tr> 111<tr> 112<td>dimensionless</td><td>item</td><td>lumen</td><td>pascal</td><td>tesla</td> 113</tr> 114</table> 115 <p> 116 * This list of predefined base units is nearly identical in SBML 117 * Level 2 Version 4, the exception being that Level 2 does 118 * not define <code>avogadro.</code> SBML Level 2 Version 1 (and <em>only</em> 119 * this Level+Version combination) provides an additional predefined unit 120 * name, <code>Celsius</code>, not available in Level 3. Finally, SBML 121 * Level 1 Versions 2–3 provide two more additional 122 * predefined unit names, <code>meter</code> and <code>liter.</code> This is explained in 123 * somewhat greater detail in the description of the {@link Unit} class. 124 <p> 125 * <ul> 126 * <li> In SBML Level 2 (all Versions), there is an additional set of 127 * reserved identifiers: <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and 128 * <code>time.</code> Using one of these values for the attribute 'id' of a 129 * {@link UnitDefinition} has the effect of redefining the model-wide default units 130 * for the corresponding quantities. The list of special unit names in 131 * SBML Level 2 is given in the table below: 132 * </ul> 133 <p> 134 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 135 <tr> 136 <th align="left">Identifier</th> 137 <th align="left">Possible scalable units</th> 138 <th align="left">Default units</th> 139 </tr> 140<tr><td><code>substance</code></td><td>mole, item, gram, kilogram, dimensionless</td><td>mole</td></tr> 141<tr><td><code>volume</code></td><td>litre, cubic metre, dimensionless</td><td>litre</td></tr> 142<tr><td><code>area</code></td><td>square metre, dimensionless</td><td>square metre</td></tr> 143<tr><td><code>length</code></td><td>metre, dimensionless</td><td>metre</td></tr> 144<tr><td><code>time</code></td><td>second, dimensionless</td><td>second</td></tr> 145</table> 146 147 148 <p> 149 * Also, SBML Level 2 imposes two limitations on redefining the 150 * predefined unit <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and 151 * <code>time:</code> (1) The {@link UnitDefinition} of a predefined SBML unit can only contain 152 * a single {@link Unit} object within it. (2) The value of the 'kind' attribute 153 * in a {@link Unit} instance must be drawn from one of the values in the second 154 * column of the table above. 155 <p> 156 * The special unit names <code>substance</code>, <code>volume</code>, <code>area</code>, <code>length</code>, and 157 * <code>time</code> are not defined by SBML Level 3, which uses a different 158 * approach to setting model-wide inherited units. 159 <p> 160 * <h2>Further comments about SBML's unit definition system</h2> 161 <p> 162 * The vast majority of modeling situations requiring new SBML unit 163 * definitions involve simple multiplicative combinations of base units and 164 * factors. An example of this might be <em>moles per litre per 165 * second</em>. What distinguishes these sorts of simpler unit definitions 166 * from more complex ones is that they may be expressed without the use of 167 * an additive offset from a zero point. The use of offsets complicates 168 * all unit definition systems, yet in the domain of SBML the real-life 169 * cases requiring offsets are few (and in fact, to the best of our 170 * knowledge, only involve temperature). Consequently, the SBML unit 171 * system has been consciously designed in a way that attempts to simplify 172 * implementation of unit support for the most common cases in systems 173 * biology. 174 <p> 175 * As of SBML Level 2 Version 2, {@link Unit} no longer has the 176 * attribute called 'offset' introduced in SBML Level 2 177 * Version 1. It turned out that the general case involving units 178 * with offsets was incorrectly defined, and few (if any) developers even 179 * attempted to support offset-based units in their software. In the 180 * development of Level 2 Version 2, a consensus among SBML 181 * developers emerged that a fully generalized unit scheme is <em>so</em> 182 * confusing and complicated that it actually <em>impedes</em> interoperability. 183 * SBML Level 2 Version 2, Version 3 and Version 4 acknowledge this 184 * reality by reducing and simplifying the unit system, specifically by 185 * removing the 'offset' attribute on {@link Unit} and <code>Celsius</code> as a pre-defined 186 * unit. 187 <p> 188 * The following guidelines suggest methods for handling units that do 189 * require the use of zero offsets for their definitions: 190 * <ul> 191 * <li> <em>Handling Celsius</em>. A model in which certain quantities are 192 * temperatures measured in degrees Celsius can be converted 193 * straightforwardly to a model in which those temperatures are in 194 * kelvin. A software tool could do this by performing a straightforward 195 * substitution using the following relationship: <em>T<sub> kelvin</sub> = 196 * T<sub>Celsius</sub> + 273.15</em>. In every mathematical formula of the 197 * model where a quantity (call it <em>x</em>) in degrees Celsius appears, 198 * replace <em>x</em> with <em>x<sub>k</sub>+ 273.15</em>, where 199 * <em>x<sub>k</sub></em> is now in kelvin. An alternative approach would 200 * be to use a {@link FunctionDefinition} object to define a function encapsulating this 201 * relationship above and then using that in the rest of the model as 202 * needed. Since Celsius is a commonly-used unit, software tools could 203 * help users by providing users with the ability to express temperatures 204 * in Celsius in the tools' interfaces, and making substitutions 205 * automatically when writing out the SBML. 206 <p> 207 * <li> <em>Other units requiring offsets</em>. One approach to handling 208 * other kinds of units is to use a {@link FunctionDefinition} to define a function 209 * encapsulating the necessary mathematical relationship, then 210 * substituting a call to this function wherever the original quantity 211 * appeared in the model. For example, here is a possible definition for 212 * converting Fahrenheit to Celsius degrees: 213 * <pre class='fragment'> 214 <functionDefinition id='Fahrenheit_to_kelvin'> 215 <math xmlns='http://www.w3.org/1998/Math/MathML'> 216 <lambda> 217 <bvar><ci> temp_in_fahrenheit </ci></bvar> 218 <apply> 219 <divide/> 220 <apply> 221 <plus/> 222 <ci> temp_in_fahrenheit </ci> 223 <cn> 459.67 </cn> 224 </apply> 225 <cn> 1.8 </cn> 226 </apply> 227 </lambda> 228 </math> 229 </functionDefinition> 230 </pre> 231 <p> 232 * <li> An alternative approach not requiring the use of function definitions 233 * is to use an {@link AssignmentRule} for each variable in Fahrenheit units. 234 * The {@link AssignmentRule} could compute the conversion from Fahrenheit to 235 * (say) kelvin, assign its value to a variable (in Kelvin units), and 236 * then that variable could be used elsewhere in the model. 237 <p> 238 * <li> Still another approach is to rewrite the mathematical formulas of a 239 * model to directly incorporate the conversion formula wherever the 240 * original quantity appeared. 241 * </ul> 242 <p> 243 * Please consult the SBML specifications for more information about this 244 * and other issues involving units. 245 */ 246 247public class UnitDefinition extends SBase { 248 private long swigCPtr; 249 250 protected UnitDefinition(long cPtr, boolean cMemoryOwn) 251 { 252 super(libsbmlJNI.UnitDefinition_SWIGUpcast(cPtr), cMemoryOwn); 253 swigCPtr = cPtr; 254 } 255 256 protected static long getCPtr(UnitDefinition obj) 257 { 258 return (obj == null) ? 0 : obj.swigCPtr; 259 } 260 261 protected static long getCPtrAndDisown (UnitDefinition obj) 262 { 263 long ptr = 0; 264 265 if (obj != null) 266 { 267 ptr = obj.swigCPtr; 268 obj.swigCMemOwn = false; 269 } 270 271 return ptr; 272 } 273 274 protected void finalize() { 275 delete(); 276 } 277 278 public synchronized void delete() { 279 if (swigCPtr != 0) { 280 if (swigCMemOwn) { 281 swigCMemOwn = false; 282 libsbmlJNI.delete_UnitDefinition(swigCPtr); 283 } 284 swigCPtr = 0; 285 } 286 super.delete(); 287 } 288 289 290/** 291 * Creates a new {@link UnitDefinition} using the given SBML <code>level</code> and <code>version</code> 292 * values. 293 <p> 294 * @param level a long integer, the SBML Level to assign to this {@link UnitDefinition} 295 <p> 296 * @param version a long integer, the SBML Version to assign to this 297 * {@link UnitDefinition} 298 <p> 299 * <p> 300 * @throws SBMLConstructorException 301 * Thrown if the given <code>level</code> and <code>version</code> combination are invalid 302 * or if this object is incompatible with the given level and version. 303 <p> 304 * <p> 305 * @note Attempting to add an object to an {@link SBMLDocument} having a different 306 * combination of SBML Level, Version and XML namespaces than the object 307 * itself will result in an error at the time a caller attempts to make the 308 * addition. A parent object must have compatible Level, Version and XML 309 * namespaces. (Strictly speaking, a parent may also have more XML 310 * namespaces than a child, but the reverse is not permitted.) The 311 * restriction is necessary to ensure that an SBML model has a consistent 312 * overall structure. This requires callers to manage their objects 313 * carefully, but the benefit is increased flexibility in how models can be 314 * created by permitting callers to create objects bottom-up if desired. In 315 * situations where objects are not yet attached to parents (e.g., 316 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 317 * libSBML determine such things as whether it is valid to assign a 318 * particular value to an attribute. 319 */ public 320 UnitDefinition(long level, long version) throws org.sbml.libsbml.SBMLConstructorException { 321 this(libsbmlJNI.new_UnitDefinition__SWIG_0(level, version), true); 322 } 323 324 325/** 326 * Creates a new {@link UnitDefinition} using the given {@link SBMLNamespaces} object 327 * <code>sbmlns</code>. 328 <p> 329 * <p> 330 * The {@link SBMLNamespaces} object encapsulates SBML Level/Version/namespaces 331 * information. It is used to communicate the SBML Level, Version, and (in 332 * Level 3) packages used in addition to SBML Level 3 Core. A 333 * common approach to using libSBML's {@link SBMLNamespaces} facilities is to create an 334 * {@link SBMLNamespaces} object somewhere in a program once, then hand that object 335 * as needed to object constructors that accept {@link SBMLNamespaces} as arguments. 336 <p> 337 * @param sbmlns an {@link SBMLNamespaces} object. 338 <p> 339 * <p> 340 * @throws SBMLConstructorException 341 * Thrown if the given <code>sbmlns</code> is inconsistent or incompatible 342 * with this object. 343 <p> 344 * <p> 345 * @note Attempting to add an object to an {@link SBMLDocument} having a different 346 * combination of SBML Level, Version and XML namespaces than the object 347 * itself will result in an error at the time a caller attempts to make the 348 * addition. A parent object must have compatible Level, Version and XML 349 * namespaces. (Strictly speaking, a parent may also have more XML 350 * namespaces than a child, but the reverse is not permitted.) The 351 * restriction is necessary to ensure that an SBML model has a consistent 352 * overall structure. This requires callers to manage their objects 353 * carefully, but the benefit is increased flexibility in how models can be 354 * created by permitting callers to create objects bottom-up if desired. In 355 * situations where objects are not yet attached to parents (e.g., 356 * {@link SBMLDocument}), knowledge of the intented SBML Level and Version help 357 * libSBML determine such things as whether it is valid to assign a 358 * particular value to an attribute. 359 */ public 360 UnitDefinition(SBMLNamespaces sbmlns) throws org.sbml.libsbml.SBMLConstructorException { 361 this(libsbmlJNI.new_UnitDefinition__SWIG_1(SBMLNamespaces.getCPtr(sbmlns), sbmlns), true); 362 } 363 364 365/** 366 * Copy constructor; creates a copy of this {@link UnitDefinition}. 367 <p> 368 * @param orig the object to copy. 369 */ public 370 UnitDefinition(UnitDefinition orig) throws org.sbml.libsbml.SBMLConstructorException { 371 this(libsbmlJNI.new_UnitDefinition__SWIG_2(UnitDefinition.getCPtr(orig), orig), true); 372 } 373 374 375/** 376 * Creates and returns a deep copy of this {@link UnitDefinition} object. 377 <p> 378 * @return the (deep) copy of this {@link UnitDefinition} object. 379 */ public 380 UnitDefinition cloneObject() { 381 long cPtr = libsbmlJNI.UnitDefinition_cloneObject(swigCPtr, this); 382 return (cPtr == 0) ? null : new UnitDefinition(cPtr, true); 383 } 384 385 386/** 387 * Returns the first child element found that has the given <code>id</code> in the 388 * model-wide SId namespace, or <code>null</code> if no such object is found. 389 <p> 390 * @param id string representing the id of objects to find. 391 <p> 392 * @return pointer to the first element found with the given <code>id</code>. 393 */ public 394 SBase getElementBySId(String id) { 395 return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementBySId(swigCPtr, this, id), false); 396} 397 398 399/** 400 * Returns the first child element it can find with the given <code>metaid</code>, or 401 * <code>null</code> if no such object is found. 402 <p> 403 * @param metaid string representing the metaid of objects to find 404 <p> 405 * @return pointer to the first element found with the given <code>metaid</code>. 406 */ public 407 SBase getElementByMetaId(String metaid) { 408 return libsbml.DowncastSBase(libsbmlJNI.UnitDefinition_getElementByMetaId(swigCPtr, this, metaid), false); 409} 410 411 412/** 413 * Returns the value of the 'id' attribute of this {@link UnitDefinition}. 414 <p> 415 * @return the id of this {@link UnitDefinition}. 416 */ public 417 String getId() { 418 return libsbmlJNI.UnitDefinition_getId(swigCPtr, this); 419 } 420 421 422/** 423 * Returns the value of the 'name' attribute of this {@link UnitDefinition}. 424 <p> 425 * @return the name of this {@link UnitDefinition}. 426 */ public 427 String getName() { 428 return libsbmlJNI.UnitDefinition_getName(swigCPtr, this); 429 } 430 431 432/** 433 * Predicate returning <code>true</code> if this 434 * {@link UnitDefinition}'s 'id' attribute is set. 435 <p> 436 * @return <code>true</code> if the 'id' attribute of this {@link UnitDefinition} is 437 * set, <code>false</code> otherwise. 438 */ public 439 boolean isSetId() { 440 return libsbmlJNI.UnitDefinition_isSetId(swigCPtr, this); 441 } 442 443 444/** 445 * Predicate returning <code>true</code> if this 446 * {@link UnitDefinition}'s 'name' attribute is set. 447 <p> 448 * @return <code>true</code> if the 'name' attribute of this {@link UnitDefinition} is 449 * set, <code>false</code> otherwise. 450 */ public 451 boolean isSetName() { 452 return libsbmlJNI.UnitDefinition_isSetName(swigCPtr, this); 453 } 454 455 456/** 457 * Sets the value of the 'id' attribute of this {@link UnitDefinition}. 458 <p> 459 * The string <code>sid</code> is copied. 460 <p> 461 * <p> 462 * SBML has strict requirements for the syntax of identifiers, that is, the 463 * values of the 'id' attribute present on most types of SBML objects. 464 * The following is a summary of the definition of the SBML identifier type 465 * <code>SId</code>, which defines the permitted syntax of identifiers. We 466 * express the syntax using an extended form of BNF notation: 467 * <pre style='margin-left: 2em; border: none; font-weight: bold; font-size: 13px; color: black'> 468 * letter .= 'a'..'z','A'..'Z' 469 * digit .= '0'..'9' 470 * idChar .= letter | digit | '_' 471 * SId .= ( letter | '_' ) idChar*</pre> 472 * The characters <code>(</code> and <code>)</code> are used for grouping, the 473 * character <code>*</code> 'zero or more times', and the character 474 * <code>|</code> indicates logical 'or'. The equality of SBML identifiers is 475 * determined by an exact character sequence match; i.e., comparisons must be 476 * performed in a case-sensitive manner. In addition, there are a few 477 * conditions for the uniqueness of identifiers in an SBML model. Please 478 * consult the SBML specifications for the exact details of the uniqueness 479 * requirements. 480 <p> 481 * @param sid the string to use as the identifier of this {@link UnitDefinition} 482 <p> 483 * <p> 484 * @return integer value indicating success/failure of the 485 * function. The possible values 486 * returned by this function are: 487 * <ul> 488 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 489 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 490 * </ul> 491 */ public 492 int setId(String sid) { 493 return libsbmlJNI.UnitDefinition_setId(swigCPtr, this, sid); 494 } 495 496 497/** 498 * Sets the value of the 'name' attribute of this {@link UnitDefinition}. 499 <p> 500 * The string in <code>name</code> is copied. 501 <p> 502 * @param name the new name for the {@link UnitDefinition} 503 <p> 504 * <p> 505 * @return integer value indicating success/failure of the 506 * function. The possible values 507 * returned by this function are: 508 * <ul> 509 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 510 * <li> {@link libsbmlConstants#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE} 511 * </ul> 512 */ public 513 int setName(String name) { 514 return libsbmlJNI.UnitDefinition_setName(swigCPtr, this, name); 515 } 516 517 518/** 519 * Unsets the value of the 'name' attribute of this {@link UnitDefinition}. 520 <p> 521 * <p> 522 * @return integer value indicating success/failure of the 523 * function. The possible values 524 * returned by this function are: 525 * <ul> 526 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 527 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 528 * </ul> 529 */ public 530 int unsetName() { 531 return libsbmlJNI.UnitDefinition_unsetName(swigCPtr, this); 532 } 533 534 535/** 536 * Convenience function for testing if a given unit definition is a 537 * variant of the predefined unit identifier <code>'area'.</code> 538 <p> 539 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 540 * unit <code>area</code>, meaning square metres with only abritrary variations 541 * in scale or multiplier values; <code>false</code> otherwise. 542 */ public 543 boolean isVariantOfArea() { 544 return libsbmlJNI.UnitDefinition_isVariantOfArea(swigCPtr, this); 545 } 546 547 548/** 549 * Convenience function for testing if a given unit definition is a 550 * variant of the predefined unit identifier <code>'length'.</code> 551 <p> 552 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 553 * unit <code>length</code>, meaning metres with only abritrary variations in scale 554 * or multiplier values; <code>false</code> otherwise. 555 */ public 556 boolean isVariantOfLength() { 557 return libsbmlJNI.UnitDefinition_isVariantOfLength(swigCPtr, this); 558 } 559 560 561/** 562 * Convenience function for testing if a given unit definition is a 563 * variant of the predefined unit identifier <code>'substance'.</code> 564 <p> 565 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 566 * unit <code>substance</code>, meaning moles or items (and grams or kilograms from 567 * SBML Level 2 Version 2 onwards) with only abritrary variations 568 * in scale or multiplier values; <code>false</code> otherwise. 569 */ public 570 boolean isVariantOfSubstance() { 571 return libsbmlJNI.UnitDefinition_isVariantOfSubstance(swigCPtr, this); 572 } 573 574 575/** 576 * Convenience function for testing if a given unit definition is a 577 * variant of the predefined unit identifier <code>'time'.</code> 578 <p> 579 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 580 * unit <code>time</code>, meaning seconds with only abritrary variations in scale or 581 * multiplier values; <code>false</code> otherwise. 582 */ public 583 boolean isVariantOfTime() { 584 return libsbmlJNI.UnitDefinition_isVariantOfTime(swigCPtr, this); 585 } 586 587 588/** 589 * Convenience function for testing if a given unit definition is a 590 * variant of the predefined unit identifier <code>'volume'.</code> 591 <p> 592 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 593 * unit <code>volume</code>, meaning litre or cubic metre with only abritrary 594 * variations in scale or multiplier values; <code>false</code> otherwise. 595 */ public 596 boolean isVariantOfVolume() { 597 return libsbmlJNI.UnitDefinition_isVariantOfVolume(swigCPtr, this); 598 } 599 600 601/** 602 * Convenience function for testing if a given unit definition is a 603 * variant of the unit <code>'dimensionless'.</code> 604 <p> 605 * @return <code>true</code> if this {@link UnitDefinition} is a variant of 606 * <code>dimensionless</code>, meaning dimensionless with only abritrary variations in 607 * scale or multiplier values; <code>false</code> otherwise. 608 */ public 609 boolean isVariantOfDimensionless() { 610 return libsbmlJNI.UnitDefinition_isVariantOfDimensionless(swigCPtr, this); 611 } 612 613 614/** 615 * Convenience function for testing if a given unit definition is a 616 * variant of the predefined unit identifier <code>'mass'.</code> 617 <p> 618 * @return <code>true</code> if this {@link UnitDefinition} is a variant of mass units, 619 * meaning gram or kilogram with only abritrary variations in scale or 620 * multiplier values; <code>false</code> otherwise. 621 */ public 622 boolean isVariantOfMass() { 623 return libsbmlJNI.UnitDefinition_isVariantOfMass(swigCPtr, this); 624 } 625 626 627/** 628 * Convenience function for testing if a given unit definition is a 629 * variant of the predefined unit <code>'substance'</code> divided by the predefined 630 * unit <code>'time'.</code> 631 <p> 632 * @return <code>true</code> if this {@link UnitDefinition} is a variant of the predefined 633 * unit <code>substance</code> per predefined unit <code>time</code>, meaning it contains two 634 * units one of which is a variant of substance and the other is a 635 * variant of time which an exponent of -1; <code>false</code> otherwise. 636 */ public 637 boolean isVariantOfSubstancePerTime() { 638 return libsbmlJNI.UnitDefinition_isVariantOfSubstancePerTime(swigCPtr, this); 639 } 640 641 642/** 643 * Adds a copy of the given {@link Unit} to this {@link UnitDefinition}. 644 <p> 645 * @param u the {@link Unit} instance to add to this {@link UnitDefinition}. 646 <p> 647 * <p> 648 * @return integer value indicating success/failure of the 649 * function. The possible values 650 * returned by this function are: 651 * <ul> 652 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS} 653 * <li> {@link libsbmlConstants#LIBSBML_LEVEL_MISMATCH LIBSBML_LEVEL_MISMATCH} 654 * <li> {@link libsbmlConstants#LIBSBML_VERSION_MISMATCH LIBSBML_VERSION_MISMATCH} 655 * <li> {@link libsbmlConstants#LIBSBML_INVALID_OBJECT LIBSBML_INVALID_OBJECT} 656 * <li> {@link libsbmlConstants#LIBSBML_OPERATION_FAILED LIBSBML_OPERATION_FAILED} 657 * 658 * </ul> <p> 659 * <p> 660 * @note This method should be used with some caution. The fact that this 661 * method <em>copies</em> the object passed to it means that the caller will be 662 * left holding a physically different object instance than the one contained 663 * inside this object. Changes made to the original object instance (such as 664 * resetting attribute values) will <em>not affect the instance in this 665 * object</em>. In addition, the caller should make sure to free the 666 * original object if it is no longer being used, or else a memory leak will 667 * result. Please see other methods on this class (particularly a 668 * corresponding method whose name begins with the word <code>create</code>) 669 * for alternatives that do not lead to these issues. 670 <p> 671 * @see #createUnit() 672 */ public 673 int addUnit(Unit u) { 674 return libsbmlJNI.UnitDefinition_addUnit(swigCPtr, this, Unit.getCPtr(u), u); 675 } 676 677 678/** 679 * Creates a new and empty {@link Unit}, adds it to this {@link UnitDefinition}'s list of 680 * units, and returns it. 681 <p> 682 * @return a newly constructed (and empty) {@link Unit} instance. 683 <p> 684 * @note It is worth emphasizing that the attribute 'kind' value of a 685 * {@link Unit} is a required attribute for a valid {@link Unit} definition. The 686 * createUnit() method does not assign a valid kind to the constructed 687 * unit (instead, it sets the 'kind' to {@link libsbmlConstants#UNIT_KIND_INVALID UNIT_KIND_INVALID}). 688 * Callers are cautioned to set the newly-constructed {@link Unit}'s kind using 689 * {@link Unit#setKind(int)} soon after calling this method. 690 <p> 691 * @see #addUnit(Unit u) 692 */ public 693 Unit createUnit() { 694 long cPtr = libsbmlJNI.UnitDefinition_createUnit(swigCPtr, this); 695 return (cPtr == 0) ? null : new Unit(cPtr, false); 696 } 697 698 699/** 700 * Returns the list of Units for this {@link UnitDefinition} instance. 701 * @return the {@link ListOfUnits} value for this {@link UnitDefinition}. 702 */ public 703 ListOfUnits getListOfUnits() { 704 long cPtr = libsbmlJNI.UnitDefinition_getListOfUnits__SWIG_0(swigCPtr, this); 705 return (cPtr == 0) ? null : new ListOfUnits(cPtr, false); 706 } 707 708 709/** 710 * Returns a specific {@link Unit} instance belonging to this {@link UnitDefinition}. 711 <p> 712 * @param n an integer, the index of the {@link Unit} to be returned. 713 <p> 714 * @return the nth {@link Unit} of this {@link UnitDefinition}. 715 <p> 716 * @see #getNumUnits() 717 */ public 718 Unit getUnit(long n) { 719 long cPtr = libsbmlJNI.UnitDefinition_getUnit__SWIG_0(swigCPtr, this, n); 720 return (cPtr == 0) ? null : new Unit(cPtr, false); 721 } 722 723 724/** 725 * Returns the number of {@link Unit} objects contained within this 726 * {@link UnitDefinition}. 727 <p> 728 * @return an integer representing the number of Units in this 729 * {@link UnitDefinition}. 730 */ public 731 long getNumUnits() { 732 return libsbmlJNI.UnitDefinition_getNumUnits(swigCPtr, this); 733 } 734 735 736/** 737 * Removes the nth {@link Unit} object from this {@link UnitDefinition} object and 738 * returns a pointer to it. 739 <p> 740 * The caller owns the returned object and is responsible for deleting it. 741 <p> 742 * @param n the index of the {@link Unit} object to remove 743 <p> 744 * @return the {@link Unit} object removed, or <code>null</code> if the given index 745 * is out of range. 746 */ public 747 Unit removeUnit(long n) { 748 long cPtr = libsbmlJNI.UnitDefinition_removeUnit(swigCPtr, this, n); 749 return (cPtr == 0) ? null : new Unit(cPtr, true); 750 } 751 752 public void connectToChild() { 753 libsbmlJNI.UnitDefinition_connectToChild(swigCPtr, this); 754 } 755 756 757/** * @internal */ public 758 void enablePackageInternal(String pkgURI, String pkgPrefix, boolean flag) { 759 libsbmlJNI.UnitDefinition_enablePackageInternal(swigCPtr, this, pkgURI, pkgPrefix, flag); 760 } 761 762 763/** 764 * Returns the libSBML type code for this object instance. 765 <p> 766 * <p> 767 * LibSBML attaches an identifying code to every kind of SBML object. These 768 * are integer constants known as <em>SBML type codes</em>. The names of all 769 * the codes begin with the characters <code>SBML_</code>. 770 * In the Java language interface for libSBML, the 771 * type codes are defined as static integer constants in the interface class 772 * {@link libsbmlConstants}. Note that different Level 3 773 * package plug-ins may use overlapping type codes; to identify the package 774 * to which a given object belongs, call the <code>getPackageName()</code> 775 * method on the object. 776 <p> 777 * @return the SBML type code for this object: 778 * {@link libsbmlConstants#SBML_UNIT_DEFINITION SBML_UNIT_DEFINITION} (default). 779 <p> 780 * <p> 781 * @warning <span class='warning'>The specific integer values of the possible 782 * type codes may be reused by different libSBML plug-ins for SBML Level 3. 783 * packages, To fully identify the correct code, <strong>it is necessary to 784 * invoke both getTypeCode() and getPackageName()</strong>.</span> 785 <p> 786 * @see #getPackageName() 787 * @see #getElementName() 788 */ public 789 int getTypeCode() { 790 return libsbmlJNI.UnitDefinition_getTypeCode(swigCPtr, this); 791 } 792 793 794/** 795 * Returns the XML element name of this object, which for {@link UnitDefinition}, 796 * is always <code>'unitDefinition'.</code> 797 <p> 798 * @return the name of this element, i.e., <code>'unitDefinition'.</code> 799 */ public 800 String getElementName() { 801 return libsbmlJNI.UnitDefinition_getElementName(swigCPtr, this); 802 } 803 804 805/** 806 * Simplifies the {@link UnitDefinition} such that any given kind of {@link Unit} object 807 * occurs only once in the {@link ListOfUnits}. 808 <p> 809 * For example, the following definition, 810 * <pre class='fragment'> 811 <unitDefinition> 812 <listOfUnits> 813 <unit kind='metre' exponent='1'/> 814 <unit kind='metre' exponent='2'/> 815 </listOfUnits> 816 <unitDefinition> 817 </pre> 818 * will be simplified to 819 * <pre class='fragment'> 820 <unitDefinition> 821 <listOfUnits> 822 <unit kind='metre' exponent='3'/> 823 </listOfUnits> 824 <unitDefinition> 825 </pre> 826 <p> 827 * @param ud the {@link UnitDefinition} object to be simplified. 828 <p> 829 * 830 */ public 831 static void simplify(UnitDefinition ud) { 832 libsbmlJNI.UnitDefinition_simplify(UnitDefinition.getCPtr(ud), ud); 833 } 834 835 836/** 837 * Alphabetically orders the {@link Unit} objects within the {@link ListOfUnits} of a 838 * {@link UnitDefinition}. 839 <p> 840 * @param ud the {@link UnitDefinition} object whose units are to be reordered. 841 <p> 842 * 843 */ public 844 static void reorder(UnitDefinition ud) { 845 libsbmlJNI.UnitDefinition_reorder(UnitDefinition.getCPtr(ud), ud); 846 } 847 848 849/** 850 * Convert a given {@link UnitDefinition} into a new {@link UnitDefinition} object 851 * that uses SI units. 852 <p> 853 * @param ud the {@link UnitDefinition} object to convert to SI 854 <p> 855 * @return a new {@link UnitDefinition} object representing the results of the 856 * conversion. 857 <p> 858 * 859 */ public 860 static UnitDefinition convertToSI(UnitDefinition ud) { 861 long cPtr = libsbmlJNI.UnitDefinition_convertToSI(UnitDefinition.getCPtr(ud), ud); 862 return (cPtr == 0) ? null : new UnitDefinition(cPtr, true); 863 } 864 865 866/** 867 * Predicate returning <code>true</code> if two 868 * {@link UnitDefinition} objects are identical. 869 <p> 870 * For the purposes of performing this comparison, two {@link UnitDefinition} 871 * objects are considered identical when they contain identical lists of 872 * {@link Unit} objects. Pairs of {@link Unit} objects in the lists are in turn 873 * considered identical if they satisfy the predicate 874 * {@link Unit#areIdentical(Unit, Unit)}. 875 * The predicate compares every attribute of the 876 * {@link Unit} objects. 877 <p> 878 * @param ud1 the first {@link UnitDefinition} object to compare 879 * @param ud2 the second {@link UnitDefinition} object to compare 880 <p> 881 * @return <code>true</code> if all the {@link Unit} objects in ud1 are identical to the 882 * {@link Unit} objects of ud2, <code>false</code> otherwise. 883 <p> 884 * 885 <p> 886 * @see UnitDefinition#areEquivalent(UnitDefinition ud1, UnitDefinition ud2) 887 * @see Unit#areIdentical(Unit unit1, Unit unit2) 888 */ public 889 static boolean areIdentical(UnitDefinition ud1, UnitDefinition ud2) { 890 return libsbmlJNI.UnitDefinition_areIdentical(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2); 891 } 892 893 894/** 895 * Predicate returning <code>true</code> if two 896 * {@link UnitDefinition} objects are equivalent. 897 <p> 898 * For the purposes of performing this comparison, two {@link UnitDefinition} 899 * objects are considered equivalent when they contain <em>equivalent</em> 900 * list of {@link Unit} objects. {@link Unit} objects are in turn considered equivalent 901 * if they satisfy the predicate 902 * {@link Unit#areEquivalent(Unit, Unit)}. 903 * The predicate tests a subset of the objects's attributes. 904 <p> 905 * @param ud1 the first {@link UnitDefinition} object to compare 906 <p> 907 * @param ud2 the second {@link UnitDefinition} object to compare 908 <p> 909 * @return <code>true</code> if all the {@link Unit} objects in ud1 are equivalent 910 * to the {@link Unit} objects in ud2, <code>false</code> otherwise. 911 <p> 912 * 913 <p> 914 * @see UnitDefinition#areIdentical(UnitDefinition ud1, UnitDefinition ud2) 915 * @see Unit#areEquivalent(Unit unit1, Unit unit2) 916 */ public 917 static boolean areEquivalent(UnitDefinition ud1, UnitDefinition ud2) { 918 return libsbmlJNI.UnitDefinition_areEquivalent(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2); 919 } 920 921 922/** 923 * Combines two {@link UnitDefinition} objects into a single {@link UnitDefinition}. 924 <p> 925 * This takes {@link UnitDefinition} objects <code>ud1</code> and <code>ud2</code>, and creates a 926 * {@link UnitDefinition} object that expresses the product of the units of 927 * <code>ud1</code> and <code>ud2</code>. 928 <p> 929 * @param ud1 the first {@link UnitDefinition} object 930 * @param ud2 the second {@link UnitDefinition} object 931 <p> 932 * @return a {@link UnitDefinition} which represents the product of the 933 * units of the two argument UnitDefinitions. 934 <p> 935 * 936 */ public 937 static UnitDefinition combine(UnitDefinition ud1, UnitDefinition ud2) { 938 long cPtr = libsbmlJNI.UnitDefinition_combine(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2); 939 return (cPtr == 0) ? null : new UnitDefinition(cPtr, true); 940 } 941 942 943/** 944 * Combines two {@link UnitDefinition} objects into a single {@link UnitDefinition} as 945 * a division. 946 <p> 947 * This takes {@link UnitDefinition} objects <code>ud1</code> and <code>ud2</code>, and creates a 948 * {@link UnitDefinition} object that expresses the division of the units of 949 * <code>ud1</code> and <code>ud2</code>. 950 <p> 951 * @param ud1 the first {@link UnitDefinition} object 952 * @param ud2 the second {@link UnitDefinition} object 953 <p> 954 * @return a {@link UnitDefinition} which represents the division of the 955 * units of the two argument UnitDefinitions. 956 <p> 957 * 958 */ public 959 static UnitDefinition divide(UnitDefinition ud1, UnitDefinition ud2) { 960 long cPtr = libsbmlJNI.UnitDefinition_divide(UnitDefinition.getCPtr(ud1), ud1, UnitDefinition.getCPtr(ud2), ud2); 961 return (cPtr == 0) ? null : new UnitDefinition(cPtr, false); 962 } 963 964 965/** 966 * Expresses the given definition in a plain-text form. 967 <p> 968 * For example, 969 * {@link UnitDefinition#printUnits(UnitDefinition)} 970 * applied to 971 * <pre class='fragment'> 972 <unitDefinition> 973 <listOfUnits> 974 <unit kind='metre' exponent='1'/> 975 <unit kind='second' exponent='-2'/> 976 </listOfUnits> 977 <unitDefinition> 978 </pre> 979 * will return the string <code>'metre (exponent = 1, multiplier = 1, 980 * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code> 981 * or, if the optional parameter <code>compact</code> is given the value <code>true</code>, 982 * the string <code>'(1 metre)^1 (1 second)^-2'</code>. This method may 983 * be useful for printing unit information to human users, or in 984 * debugging software, or other situations. 985 <p> 986 * @param ud the {@link UnitDefinition} object 987 * @param compact boolean indicating whether the compact form 988 * should be used (defaults to false) 989 <p> 990 * @return a string expressing the unit definition defined by the given 991 * {@link UnitDefinition} object <code>ud</code>. 992 <p> 993 * 994 */ public 995 static String printUnits(UnitDefinition ud, boolean compact) { 996 return libsbmlJNI.UnitDefinition_printUnits__SWIG_0(UnitDefinition.getCPtr(ud), ud, compact); 997 } 998 999 1000/** 1001 * Expresses the given definition in a plain-text form. 1002 <p> 1003 * For example, 1004 * {@link UnitDefinition#printUnits(UnitDefinition)} 1005 * applied to 1006 * <pre class='fragment'> 1007 <unitDefinition> 1008 <listOfUnits> 1009 <unit kind='metre' exponent='1'/> 1010 <unit kind='second' exponent='-2'/> 1011 </listOfUnits> 1012 <unitDefinition> 1013 </pre> 1014 * will return the string <code>'metre (exponent = 1, multiplier = 1, 1015 * scale = 0) second (exponent = -2, multiplier = 1, scale = 0)'</code> 1016 * or, if the optional parameter <code>compact</code> is given the value <code>true</code>, 1017 * the string <code>'(1 metre)^1 (1 second)^-2'</code>. This method may 1018 * be useful for printing unit information to human users, or in 1019 * debugging software, or other situations. 1020 <p> 1021 * @param ud the {@link UnitDefinition} object 1022 * @param compact boolean indicating whether the compact form 1023 * should be used (defaults to false) 1024 <p> 1025 * @return a string expressing the unit definition defined by the given 1026 * {@link UnitDefinition} object <code>ud</code>. 1027 <p> 1028 * 1029 */ public 1030 static String printUnits(UnitDefinition ud) { 1031 return libsbmlJNI.UnitDefinition_printUnits__SWIG_1(UnitDefinition.getCPtr(ud), ud); 1032 } 1033 1034 1035/** 1036 * Predicate returning <code>true</code> if 1037 * all the required attributes for this {@link UnitDefinition} object 1038 * have been set. 1039 <p> 1040 * The required attributes for a {@link UnitDefinition} object are: 1041 * <ul> 1042 * <li> 'id' 1043 * 1044 * </ul> <p> 1045 * @return <code>true</code> if the required attributes have been set, <code>false</code> 1046 * otherwise. 1047 */ public 1048 boolean hasRequiredAttributes() { 1049 return libsbmlJNI.UnitDefinition_hasRequiredAttributes(swigCPtr, this); 1050 } 1051 1052 1053/** 1054 * Predicate returning <code>true</code> if 1055 * all the required elements for this {@link UnitDefinition} object 1056 * have been set. 1057 <p> 1058 * @note The required elements for a {@link Constraint} object are: 1059 * <ul> 1060 * <li> 'listOfUnits' (required in SBML Level 2 only, optional in Level 3) 1061 * 1062 * </ul> <p> 1063 * @return a boolean value indicating whether all the required 1064 * elements for this object have been defined. 1065 */ public 1066 boolean hasRequiredElements() { 1067 return libsbmlJNI.UnitDefinition_hasRequiredElements(swigCPtr, this); 1068 } 1069 1070}