[Python] Add docs for class Quantity

doc/sphinx/cython/thermo.rst

@@ -29,6 +29,10 @@ Mixture
 
 .. autoclass:: Mixture
 
+Quantity
+--------
+.. autoclass:: Quantity
+
 Species
 -------
 

interfaces/cython/cantera/composite.py

@@ -2,7 +2,67 @@ from ._cantera import *
 
 class Quantity(object):
     """
-    A class representing a specific quantity of a `Solution`.
+    A class representing a specific quantity of a `Solution`. In addition to the
+    properties which can be computed for class `Solution`, class `Quantity`
+    provides several additional capabilities. A `Quantity` object is created
+    from a `Solution` with either the mass or number of moles specified::
+
+        >>> gas = ct.Solution('gri30.xml')
+        >>> gas.TPX = 300, 5e5, 'O2:1.0, N2:3.76'
+        >>> q1 = ct.Quantity(gas, mass=5) # 5 kg of air
+
+    The state of a `Quantity` can be changed in the same way as a `Solution`::
+
+        >>> q1.TP = 500, 101325
+
+    Quantities have properties which provide access to extensive properties::
+
+        >>> q1.volume
+        7.1105094
+        >>> q1.enthalpy
+        1032237.84
+
+    The size of a `Quantity` can be changed by setting the mass or number of
+    moles::
+
+        >>> q1.moles = 3
+        >>> q1.mass
+        86.552196
+        >>> q1.volume
+        123.086
+
+    or by multiplication::
+
+        >>> q1 *= 2
+        >>> q1.moles
+        6.0
+
+    Finally, Quantities can be added, providing an easy way of calculating the
+    state resulting from mixing two substances::
+
+        >>> q1.mass = 5
+        >>> q2 = ct.Quantity(gas)
+        >>> q2.TPX = 300, 101325, 'CH4:1.0'
+        >>> q2.mass = 1
+        >>> q3 = q1 + q2 # combine at constant UV
+        >>> q3.T
+        432.31234
+        >>> q3.P
+        97974.9871
+        >>> q3.mole_fraction_dict()
+        {'CH4': 0.26452900448117395,
+         'N2': 0.5809602821745349,
+         'O2': 0.1545107133442912}
+
+    If a different property pair should be held constant when combining, this
+    can be specified as follows::
+
+        >>> q1.constant = q2.constant = 'HP'
+        >>> q3 = q1 + q2 # combine at constant HP
+        >>> q3.T
+        436.03320
+        >>> q3.P
+        101325.0
     """
     def __init__(self, phase, mass=None, moles=None, constant='UV'):
         self.state = phase.TDY
@@ -20,11 +80,16 @@ class Quantity(object):
 
     @property
     def phase(self):
+        """
+        Get the underlying `Solution` object, with the state set to match the
+        wrapping `Quantity` object.
+        """
         self._phase.TDY = self.state
         return self._phase
 
     @property
     def moles(self):
+        """ Get/Set the number of moles [kmol] represented by the `Quantity`. """
         return self.mass / self.phase.mean_molecular_weight
 
     @moles.setter
@@ -33,22 +98,29 @@ class Quantity(object):
 
     @property
     def volume(self):
+        """ Get the total volume [m^3] represented by the `Quantity`. """
         return self.mass * self.phase.volume_mass
 
     @property
     def int_energy(self):
+        """ Get the total internal energy [J] represented by the `Quantity`. """
         return self.mass * self.phase.int_energy_mass
 
     @property
     def enthalpy(self):
+        """ Get the total enthalpy [J] represented by the `Quantity`. """
         return self.mass * self.phase.enthalpy_mass
 
     @property
     def entropy(self):
+        """ Get the total entropy [J/K] represented by the `Quantity`. """
         return self.mass * self.phase.entropy_mass
 
     @property
     def gibbs(self):
+        """
+        Get the total Gibbs free energy [J] represented by the `Quantity`.
+        """
         return self.mass * self.phase.gibbs_mass
 
     def __imul__(self, other):