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