From d559af9d382b1d3db606ee364aad73b89f4f0b32 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Wed, 5 Aug 2015 15:36:57 -0400
Subject: [PATCH] [Python] Add docs for class Quantity

---
 doc/sphinx/cython/thermo.rst           |  4 ++
 interfaces/cython/cantera/composite.py | 74 +++++++++++++++++++++++++-
 2 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/doc/sphinx/cython/thermo.rst b/doc/sphinx/cython/thermo.rst
index aa75e1528..8c0afe7d3 100644
--- a/doc/sphinx/cython/thermo.rst
+++ b/doc/sphinx/cython/thermo.rst
@@ -29,6 +29,10 @@ Mixture
 
 .. autoclass:: Mixture
 
+Quantity
+--------
+.. autoclass:: Quantity
+
 Species
 -------
 
diff --git a/interfaces/cython/cantera/composite.py b/interfaces/cython/cantera/composite.py
index acb8de8e4..b2b063be4 100644
--- a/interfaces/cython/cantera/composite.py
+++ b/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):