From 4ea96b810d39136c528c2ad8e22129c3a2facc82 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 4 May 2015 00:03:03 -0400 Subject: [PATCH] [Python] Document Species, SpeciesThermo, and derived classes --- doc/sphinx/cython/thermo.rst | 21 +++++++- interfaces/cython/cantera/speciesthermo.pyx | 56 +++++++++++++++++++-- interfaces/cython/cantera/thermo.pyx | 33 ++++++++++++ 3 files changed, 104 insertions(+), 6 deletions(-) diff --git a/doc/sphinx/cython/thermo.rst b/doc/sphinx/cython/thermo.rst index 00b8bb01e..bffbe7abb 100644 --- a/doc/sphinx/cython/thermo.rst +++ b/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: diff --git a/interfaces/cython/cantera/speciesthermo.pyx b/interfaces/cython/cantera/speciesthermo.pyx index 45ea23b2b..8cb02e5f7 100644 --- a/interfaces/cython/cantera/speciesthermo.pyx +++ b/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 diff --git a/interfaces/cython/cantera/thermo.pyx b/interfaces/cython/cantera/thermo.pyx index 565956ab5..96d2b7911 100644 --- a/interfaces/cython/cantera/thermo.pyx +++ b/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)