[Python] Document Species, SpeciesThermo, and derived classes

doc/sphinx/cython/thermo.rst

@@ -3,20 +3,37 @@
 Thermodynamic Properties
 ========================
 
+Phases
+------
+
 These classes are used to describe the thermodynamic state of a system.
 
 .. autoclass:: ThermoPhase(infile='', phaseid='')
 .. autoclass:: InterfacePhase(infile='', phaseid='')
 .. autoclass:: PureFluid(infile='', phaseid='')
+
+Mixture
+-------
+
 .. autoclass:: Mixture
 
+Species
+-------
+
+.. autoclass:: Species
+
 Species Thermodynamic Properties
-================================
+--------------------------------
 
 These classes are used to describe the reference-state thermodynamic properties
 of a pure species.
 
-.. autoclass:: SpeciesThermo
+.. autoclass:: SpeciesThermo(T_low, T_high, P_ref, coeffs)
 .. autoclass:: ConstantCp(T_low, T_high, P_ref, coeffs)
+    :no-undoc-members:
+
 .. autoclass:: NasaPoly2(T_low, T_high, P_ref, coeffs)
+    :no-undoc-members:
+
 .. autoclass:: ShomatePoly2(T_low, T_high, P_ref, coeffs)
+    :no-undoc-members:

interfaces/cython/cantera/speciesthermo.pyx

@@ -10,6 +10,17 @@ cdef class SpeciesThermo:
     a pure species. These properties are a function of temperature. Derived
     classes implement a parameterization of this temperature dependence. This is
     a wrapper for the C++ class :ct:`SpeciesThermoInterpType`.
+
+    :param T_low:
+        The minimum temperature [K] at which the parameterization is valid
+    :param T_high:
+        The maximum temperature [K] at which the parameterization is valid
+    :param P_ref:
+        The reference pressure [Pa] for the parameterization
+    :param coeffs:
+        An array of coefficients for the parameterization. The length of this
+        array and the meaning of each element depends on the specific
+        parameterization.
     """
     def __cinit__(self, T_low=None, T_high=None, P_ref=None, coeffs=None, *args,
                   init=True, **kwargs):
@@ -29,28 +40,38 @@ cdef class SpeciesThermo:
         self.spthermo = self._spthermo.get()
 
     def cp(self, T):
-        """ Molar heat capacity at constant pressure [J/kmol/K] """
+        """
+        Molar heat capacity at constant pressure [J/kmol/K] at temperature *T*.
+        """
         cdef double cp_r, h_rt, s_r
         self.spthermo.updatePropertiesTemp(T, &cp_r, &h_rt, &s_r)
         return cp_r * gas_constant
 
     def h(self, T):
-        """ Molar enthalpy [J/kmol] """
+        """ Molar enthalpy [J/kmol] at temperature *T* """
         cdef double cp_r, h_rt, s_r
         self.spthermo.updatePropertiesTemp(T, &cp_r, &h_rt, &s_r)
         return h_rt * gas_constant * T
 
     def s(self, T):
-        """ Molar entropy [J/kmol/K] """
+        """ Molar entropy [J/kmol/K] at temperature *T* """
         cdef double cp_r, h_rt, s_r
         self.spthermo.updatePropertiesTemp(T, &cp_r, &h_rt, &s_r)
         return s_r * gas_constant
 
 
 cdef class ConstantCp(SpeciesThermo):
-    """
+    r"""
     Thermodynamic properties for a species that has a constant specific heat
     capacity. This is a wrapper for the C++ class :ct:`ConstCpPoly`.
+
+    :param coeffs:
+        An array of 4 elements:
+
+             - `coeffs[0]` = :math:`T_0` [K]
+             - `coeffs[1]` = :math:`H^o(T_0, p_{ref})` [J/kmol]
+             - `coeffs[2]` = :math:`S^o(T_0, p_{ref})` [J/kmol-K]
+             - `coeffs[3]` = :math:`c_p^o(T_0, p_{ref})` [J/kmol-K]
     """
     derived_type = SPECIES_THERMO_CONSTANT_CP
     n_coeffs = 4
@@ -61,6 +82,19 @@ cdef class NasaPoly2(SpeciesThermo):
     Thermodynamic properties for a species which is parameterized using the
     7-coefficient NASA polynomial form in two temperature ranges. This is a
     wrapper for the C++ class :ct:`NasaPoly2`.
+
+    :param coeffs:
+        An array of 15 elements, in the following order:
+
+            - `coeffs[0]`: The mid-point temperature [K] between the two
+              parameterizations
+            - `coeffs[1:8]`: The 7 coefficients of the high-temperature
+              parameterization
+            - `coeffs[8:15]`: The 7 coefficients of the low-temperature
+              parameterization
+
+        This is the coefficient order used in the standard fixed-format NASA
+        input files.
     """
     derived_type = SPECIES_THERMO_NASA2
     n_coeffs = 15
@@ -71,6 +105,20 @@ cdef class ShomatePoly2(SpeciesThermo):
     Thermodynamic properties for a species which is parameterized using the
     Shomate equation in two temperature ranges. This is a wrapper for the C++
     class :ct:`ShomatePoly2`.
+
+    :param coeffs:
+        An array of 15 elements, in the following order:
+
+            - `coeffs[0]`: The mid-point temperature [K] between the two
+              parameterizations
+            - `coeffs[1:8]`: The 7 coefficients of the low-temperature
+              parameterization
+            - `coeffs[8:15]`: The 7 coefficients of the high-temperature
+              parameterization
+
+        These coefficients should be provided in their customary units (i.e.
+        such that :math:`c_p^o` is in J/gmol-K and :math:`H^o` is in kJ/gmol,
+        as in the NIST Chemistry WebBook).
     """
     derived_type = SPECIES_THERMO_SHOMATE2
     n_coeffs = 15

interfaces/cython/cantera/thermo.pyx

@@ -6,6 +6,22 @@ cdef enum Thermasis:
 
 
 cdef class Species:
+    """
+    A class which stores data about a single chemical species that may be
+    needed to add it to a ThermoPhase or Transport object.
+
+    :param name:
+        A string giving the name of the species, e.g. ``'CH4'``
+    :param composition:
+        The elemental composition of the species, given either as a dict or a
+        composition string, e.g. `{'C':1, 'H':4}` or `'C:1, H:4'`.
+    :param charge:
+        The electrical charge, in units of the elementary charge. Default 0.0.
+    :param size:
+        The effective size [m] of the species. Default 1.0.
+    :param init:
+        Used internally when wrapping :ct:`Species` objects returned from C++
+    """
     def __cinit__(self, *args, init=True, **kwargs):
         if init:
             self._species.reset(new CxxSpecies())
@@ -107,22 +123,35 @@ cdef class Species:
         return species
 
     property name:
+        """ The name of the species. """
         def __get__(self):
             return pystr(self.species.name)
 
     property composition:
+        """
+        A dict containing the elemental composition of the species. Keys are
+        element names; values are the corresponding atomicities.
+        """
         def __get__(self):
             return comp_map_to_dict(self.species.composition)
 
     property charge:
+        """
+        The electrical charge on the species, in units of the elementary charge.
+        """
         def __get__(self):
             return self.species.charge
 
     property size:
+        """ The effective size [m] of the species. """
         def __get__(self):
             return self.species.size
 
     property thermo:
+        """
+        Get/Set the species reference-state thermodynamic data, as an instance
+        of class `SpeciesThermo`.
+        """
         def __get__(self):
             return wrapSpeciesThermo(self.species.thermo)
 
@@ -130,6 +159,10 @@ cdef class Species:
             self.species.thermo = spthermo._spthermo
 
     property transport:
+        """
+        Get/Set the species transport parameters, as an instance of class
+        `GasTransportData`.
+        """
         def __get__(self):
             data = GasTransportData(init=False)
             data._assign(self.species.transport)