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> &ndash;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> &ndash;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 &lt;listOfUnitDefinitions&gt;
071     &lt;unitDefinition id='mmls'&gt;
072         &lt;listOfUnits&gt;
073             &lt;unit kind='mole'   scale='-3'/&gt;
074             &lt;unit kind='litre'  exponent='-1'/&gt;
075             &lt;unit kind='second' exponent='-1'/&gt;
076         &lt;/listOfUnits&gt;
077     &lt;/unitDefinition&gt;
078 &lt;/listOfUnitDefinitions&gt;
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&nbsp;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&nbsp;2 Version&nbsp;4, the exception being that Level&nbsp;2 does
118 * not define <code>avogadro.</code>  SBML Level&nbsp;2 Version&nbsp;1 (and <em>only</em>
119 * this Level+Version combination) provides an additional predefined unit
120 * name, <code>Celsius</code>, not available in Level&nbsp;3.  Finally, SBML
121 * Level&nbsp;1 Versions&nbsp;2&ndash;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&nbsp;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&nbsp;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&nbsp;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&nbsp;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&nbsp;2 Version&nbsp;2, {@link Unit} no longer has the
176 * attribute called 'offset' introduced in SBML Level&nbsp;2
177 * Version&nbsp;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&nbsp;2 Version&nbsp;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&nbsp;2 Version&nbsp;2, Version&nbsp;3 and Version&nbsp;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 &lt;functionDefinition id='Fahrenheit_to_kelvin'&gt;
215     &lt;math xmlns='http://www.w3.org/1998/Math/MathML'&gt;
216         &lt;lambda&gt;
217             &lt;bvar&gt;&lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;&lt;/bvar&gt;
218             &lt;apply&gt;
219                 &lt;divide/&gt;
220                 &lt;apply&gt;
221                     &lt;plus/&gt;
222                     &lt;ci&gt; temp_in_fahrenheit &lt;/ci&gt;
223                     &lt;cn&gt; 459.67 &lt;/cn&gt;
224                 &lt;/apply&gt;
225                 &lt;cn&gt; 1.8 &lt;/cn&gt;
226             &lt;/apply&gt;
227         &lt;/lambda&gt;
228     &lt;/math&gt;
229 &lt;/functionDefinition&gt;
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&nbsp;3) packages used in addition to SBML Level&nbsp;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&nbsp;2 Version&nbsp;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&nbsp;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&nbsp;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 &lt;unitDefinition&gt;
812  &lt;listOfUnits&gt;
813    &lt;unit kind='metre' exponent='1'/&gt;
814    &lt;unit kind='metre' exponent='2'/&gt;
815  &lt;/listOfUnits&gt;
816 &lt;unitDefinition&gt;
817 </pre>
818   * will be simplified to 
819   * <pre class='fragment'>
820 &lt;unitDefinition&gt;
821   &lt;listOfUnits&gt;
822     &lt;unit kind='metre' exponent='3'/&gt;
823   &lt;/listOfUnits&gt;
824 &lt;unitDefinition&gt;
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 &lt;unitDefinition&gt;
973  &lt;listOfUnits&gt;
974    &lt;unit kind='metre' exponent='1'/&gt;
975    &lt;unit kind='second' exponent='-2'/&gt;
976  &lt;/listOfUnits&gt;
977 &lt;unitDefinition&gt;
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 &lt;unitDefinition&gt;
1008  &lt;listOfUnits&gt;
1009    &lt;unit kind='metre' exponent='1'/&gt;
1010    &lt;unit kind='second' exponent='-2'/&gt;
1011  &lt;/listOfUnits&gt;
1012 &lt;unitDefinition&gt;
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&nbsp;2 only, optional in Level&nbsp;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}