Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Python] Fix typos in docstrings and extend documentation #1335

Merged
merged 4 commits into from Jul 16, 2022
Merged

[Python] Fix typos in docstrings and extend documentation #1335

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ee4a330
Fix typos in docstrings and extend documentation
g3bk47 Jul 13, 2022
8cc8dd0
use correct nomenclature for elemental mole fraction
g3bk47 Jul 13, 2022
208a369
[Python] use raw string for documentation
g3bk47 Jul 16, 2022
d206170
[Python] remove stray quotation mark
g3bk47 Jul 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
90 changes: 64 additions & 26 deletions interfaces/cython/cantera/thermo.pyx
View file
Open in desktop
Expand Up @@ -735,10 +735,10 @@ cdef class ThermoPhase(_SolutionBase):

>>> gas.set_equivalence_ratio(0.5, 'CH4', 'O2:1.0, N2:3.76', basis='mole')
>>> gas.mass_fraction_dict()
{'CH4': 0.02837633052851681, 'N2': 0.7452356312613029, 'O2': 0.22638803821018036}
>>> gas.set_equivalence_ratio(1.2, {'NH3':0.8, 'CO':0.2}, 'O2:1.0', basis='mole')
{'CH4': 0.02837633052851, 'N2': 0.7452356312613, 'O2': 0.22638803821018}
>>> gas.set_equivalence_ratio(1.2, "NH3':0.8,CO:0.2", 'O2:1', basis='mole')
g3bk47 marked this conversation as resolved.
Show resolved Hide resolved
>>> gas.mass_fraction_dict()
{'CO': 0.14784006249290754, 'NH3': 0.35956645545401045, 'O2': 0.49259348205308207}
{'CO': 0.14784006249290, 'NH3': 0.35956645545401, 'O2': 0.49259348205308}

:param phi:
Equivalence ratio
Expand All @@ -748,23 +748,23 @@ cdef class ThermoPhase(_SolutionBase):
Oxidizer species name or mole/mass fractions as a string, array, or dict.
:param basis:
Determines if ``fuel`` and ``oxidizer`` are given in mole
fractions (``basis='mole'``) or mass fractions (``basis='mass'``)
fractions (``basis='mole'``) or mass fractions (``basis='mass'``).
:param diluent:
Optional parameter. Required if dilution is used. Specifies the composition
of the diluent in mole/mass fractions as a string, array or dict
of the diluent in mole/mass fractions as a string, array or dict.
:param fraction:
Optional parameter. Dilutes the fuel/oxidizer mixture with the diluent
according to ``fraction``. Fraction can refer to the fraction of diluent in
the mixture (for example ``fraction="diluent:0.7`` will create a mixture
the mixture (for example ``fraction="diluent:0.7"`` will create a mixture
with 30 % fuel/oxidizer and 70 % diluent), the fraction of fuel in the
mixture (for example ``fraction="fuel:0.1" means that the mixture contains
mixture (for example ``fraction="fuel:0.1"`` means that the mixture contains
10 % fuel. The amount of oxidizer is determined from the equivalence ratio
and the remaining mixture is the diluent) or fraction of oxidizer in the
mixture (for example ``fraction="oxidizer:0.1")``. The fraction itself is
mixture (for example ``fraction="oxidizer:0.1"``). The fraction itself is
interpreted as mole or mass fraction based on ``basis``. The diluent is not
considered in the computation of the equivalence ratio. Default is no
dilution or ``fraction=None``. May be given as string or dictionary (for
example ``fraction={"fuel":0.7})``
example ``fraction={"fuel":0.7}``).
"""
cdef np.ndarray[np.double_t, ndim=1] fuel_comp = np.ascontiguousarray(
self.__composition_to_array(fuel, basis), dtype=np.double)
Expand Down Expand Up @@ -873,7 +873,9 @@ cdef class ThermoPhase(_SolutionBase):
H to H2O and S to SO2. Other elements are assumed not to participate in
oxidation (that is, N ends up as N2). The ``basis`` determines the composition
of fuel and oxidizer: ``basis='mole'`` (default) means mole fractions,
``basis='mass'`` means mass fractions::
``basis='mass'`` means mass fractions. For more information, see `Python
example
<https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_ ::

>>> gas.set_mixture_fraction(0.5, 'CH4', 'O2:1.0, N2:3.76')
>>> gas.mass_fraction_dict()
Expand Down Expand Up @@ -901,15 +903,29 @@ cdef class ThermoPhase(_SolutionBase):

def equivalence_ratio(self, fuel=None, oxidizer=None, basis="mole",
include_species=None):
"""
Get the equivalence ratio of the current mixture, which is a
r"""
Get the equivalence ratio :math:`\phi` of the current mixture, which is a
conserved quantity. Considers the oxidation of C to CO2, H to H2O
and S to SO2. Other elements are assumed not to participate in oxidation
(that is, N ends up as N2). If fuel and oxidizer are not specified, the
equivalence ratio is computed from the available oxygen and the
required oxygen for complete oxidation. The ``basis`` determines the
composition of fuel and oxidizer: ``basis='mole'`` (default) means mole
fractions, ``basis='mass'`` means mass fractions. Additionally, a
required oxygen for complete oxidation:

.. math:: \phi = \frac{Z_{\mathrm{mole},C} + Z_{\mathrm{mole},S}
+ \frac{1}{4}Z_{\mathrm{mole},H}} {\frac{1}{2}Z_{\mathrm{mole},O}}

where :math:`Z_{\mathrm{mole},e}` is the elemental mole fraction of element
:math:`e`. If the fuel and oxidizer compositions are specified, :math:`\phi` is
computed from:

.. math:: \phi = \frac{Z}{1-Z}\frac{1-Z_{\mathrm{st}}}{Z_{\mathrm{st}}}

where :math:`Z` is the Bilger mixture fraction and :math:`Z_{\mathrm{st}}`
the Bilger mixture fraction at stoichiometric conditions.
The ``basis`` determines the composition of fuel and oxidizer:
``basis='mole'`` (default) means mole fractions, ``basis='mass'`` means
mass fractions. Note that this definition takes all species into account.
In case certain species like inert diluents should be ignored, a
list of species can be provided with ``include_species``. This means that
only these species are considered for the computation of the equivalence
ratio. For more information, see `Python example
Expand Down Expand Up @@ -958,19 +974,41 @@ cdef class ThermoPhase(_SolutionBase):
return phi

def mixture_fraction(self, fuel, oxidizer, basis='mole', element="Bilger"):
"""
Get the mixture fraction of the current mixture (kg fuel / (kg oxidizer + kg fuel))
This is a quantity that is conserved after oxidation. Considers the
oxidation of C to CO2, H to H2O and S to SO2. Other elements are assumed
not to participate in oxidation (that is, N ends up as N2).
r"""
Get the mixture fraction of the current mixture in
(kg fuel / (kg oxidizer + kg fuel)). This is a quantity that is conserved after
oxidation. Considers the oxidation of C to CO2, H to H2O and S to SO2. Other
elements are assumed not to participate in oxidation (that is, N ends up as N2).
The ``basis`` determines the composition of fuel and oxidizer:
``basis="mole"`` (default) means mole fractions, ``basis="mass"`` means mass fractions.
The mixture fraction can be computed from a single element (for example, carbon
with ``element="C"``) or from all elements, which is the Bilger mixture
fraction (``element="Bilger"``). The Bilger mixture fraction is computed by default::
``basis="mole"`` (default) means mole fractions, ``basis="mass"`` means mass
fractions. The mixture fraction can be computed from a single element (for
example, carbon with ``element="C"``)

>>> gas.set_mixture_fraction(0.5, 'CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
>>> gas.mixture_fraction('CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
.. math:: Z_m = \frac{Z_{\mathrm{mass},m}-Z_{\mathrm{mass},m,\mathrm{ox}}}
{Z_{\mathrm{mass},\mathrm{fuel}}-Z_{\mathrm{mass},m,\mathrm{ox}}}

where :math:`Z_{\mathrm{mass},m}` is the elemental mass fraction of
element :math:`m` in the mixture, and :math:`Z_{\mathrm{mass},m,\mathrm{ox}}`
and :math:`Z_{\mathrm{mass},\mathrm{fuel}}` are the elemental mass fractions of
the oxidizer and fuel, or from the Bilger mixture fraction
(``element="Bilger"``), which considers the elements C, S, H and O
(R. W. Bilger, "Turbulent jet diffusion flames," Prog. Energy Combust. Sci.,
109-131 (1979)). The Bilger mixture fraction is computed by default:

.. math:: Z_m = Z_{\mathrm{Bilger}} = \frac{\beta-\beta_{\mathrm{ox}}}
{\beta_{\mathrm{fuel}}-\beta_{\mathrm{ox}}}

with

.. math:: \beta = 2\frac{Z_C}{M_C}+2\frac{Z_S}{M_S}+\frac{1}{2}\frac{Z_H}{M_H}
- \frac{Z_O}{M_O}

and :math:`M_m` the atomic weight of element :math:`m`.
For more information, see `Python example
<https://cantera.org/examples/python/thermo/equivalenceRatio.py.html>`_.::

>>> gas.set_mixture_fraction(0.5, 'CH3:0.5, CH3OH:0.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
>>> gas.mixture_fraction('CH3:0.5, CH3OH:0.5, N2:0.125', 'O2:0.21, N2:0.79, NO:.01')
0.5

:param fuel:
Expand Down