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