diff --git a/doc/sphinx/cython/importing.rst b/doc/sphinx/cython/importing.rst index ac46889f15..6b1b3e79ad 100644 --- a/doc/sphinx/cython/importing.rst +++ b/doc/sphinx/cython/importing.rst @@ -12,11 +12,11 @@ Composite Phase Objects These classes are composite representations of a substance which has thermodynamic, chemical kinetic, and (optionally) transport properties. -.. autoclass:: Solution(infile='', phaseid='', source=None, thermo=None, species=(), kinetics=None, reactions=(), **kwargs) +.. autoclass:: Solution(infile='', name='', *, origin=None, source=None, yaml=None, thermo=None, species=(), kinetics=None, reactions=()) -.. autoclass:: Interface(infile='', phaseid='', phases=(), thermo=None, species=(), kinetics=None, reactions=()) +.. autoclass:: Interface(infile='', name='', adjacent=(), *, origin=None, source=None, yaml=None, thermo=None, species=(), kinetics=None, reactions=()) -.. autoclass:: DustyGas(infile, phaseid='') +.. autoclass:: DustyGas(infile, name='') Pure Fluid Phases ----------------- diff --git a/doc/sphinx/cython/kinetics.rst b/doc/sphinx/cython/kinetics.rst index bba7133c84..8b8ca4767b 100644 --- a/doc/sphinx/cython/kinetics.rst +++ b/doc/sphinx/cython/kinetics.rst @@ -11,7 +11,7 @@ Kinetics Managers Kinetics ^^^^^^^^ -.. autoclass:: Kinetics(infile='', phaseid='', phases=()) +.. autoclass:: Kinetics InterfaceKinetics ^^^^^^^^^^^^^^^^^ @@ -27,47 +27,47 @@ evaluation is handled by dedicated `ReactionRate` objects. Reaction ^^^^^^^^ -.. autoclass:: Reaction(reactants='', products='') +.. autoclass:: Reaction :no-undoc-members: ElementaryReaction ^^^^^^^^^^^^^^^^^^ -.. autoclass:: ElementaryReaction(reactants='', products='') +.. autoclass:: ElementaryReaction :no-undoc-members: ThreeBodyReaction ^^^^^^^^^^^^^^^^^ -.. autoclass:: ThreeBodyReaction(reactants='', products='') +.. autoclass:: ThreeBodyReaction :no-undoc-members: FalloffReaction ^^^^^^^^^^^^^^^ -.. autoclass:: FalloffReaction(reactants='', products='') +.. autoclass:: FalloffReaction :no-undoc-members: ChemicallyActivatedReaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: ChemicallyActivatedReaction(reactants='', products='') +.. autoclass:: ChemicallyActivatedReaction :no-undoc-members: PlogReaction ^^^^^^^^^^^^ -.. autoclass:: PlogReaction(reactants='', products='') +.. autoclass:: PlogReaction :no-undoc-members: ChebyshevReaction ^^^^^^^^^^^^^^^^^ -.. autoclass:: ChebyshevReaction(reactants='', products='') +.. autoclass:: ChebyshevReaction :no-undoc-members: InterfaceReaction ^^^^^^^^^^^^^^^^^ -.. autoclass:: InterfaceReaction(reactants='', products='') +.. autoclass:: InterfaceReaction :no-undoc-members: BlowersMaselInterfaceReaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: BlowersMaselInterfaceReaction(reactants='', products='') +.. autoclass:: BlowersMaselInterfaceReaction :no-undoc-members: Reaction Rates @@ -137,8 +137,8 @@ CustomRate .. autoclass:: CustomRate(k) :no-undoc-members: -Auxilliary Reaction Data (legacy only) --------------------------------------- +Auxiliary Reaction Data (legacy only) +------------------------------------- Arrhenius ^^^^^^^^^ diff --git a/doc/sphinx/cython/onedim.rst b/doc/sphinx/cython/onedim.rst index 138fb01042..7cace3e1f0 100644 --- a/doc/sphinx/cython/onedim.rst +++ b/doc/sphinx/cython/onedim.rst @@ -13,27 +13,27 @@ Composite Domains FreeFlame ^^^^^^^^^ -.. autoclass:: FreeFlame(gas, grid=None, width=None) +.. autoclass:: FreeFlame BurnerFlame ^^^^^^^^^^^ -.. autoclass:: BurnerFlame(gas, grid=None, width=None) +.. autoclass:: BurnerFlame CounterflowDiffusionFlame ^^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: CounterflowDiffusionFlame(gas, grid=None, width=None) +.. autoclass:: CounterflowDiffusionFlame CounterflowPremixedFlame ^^^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: CounterflowPremixedFlame(gas, grid=None, width=None) +.. autoclass:: CounterflowPremixedFlame ImpingingJet ^^^^^^^^^^^^ -.. autoclass:: ImpingingJet(gas, grid=None, width=None) +.. autoclass:: ImpingingJet IonFreeFlame ^^^^^^^^^^^^ -.. autoclass:: IonFreeFlame(gas, grid=None, width=None) +.. autoclass:: IonFreeFlame .. autoattribute:: E .. autoattribute:: electric_field_enabled @@ -41,7 +41,7 @@ IonFreeFlame IonBurnerFlame ^^^^^^^^^^^^^^ -.. autoclass:: IonBurnerFlame(gas, grid=None, width=None) +.. autoclass:: IonBurnerFlame .. autoattribute:: E .. autoattribute:: electric_field_enabled @@ -72,38 +72,38 @@ Boundaries Inlet1D ^^^^^^^ -.. autoclass:: Inlet1D(phase, name=None) +.. autoclass:: Inlet1D(phase, *, name=None) Outlet1D ^^^^^^^^ -.. autoclass:: Outlet1D(phase, name=None) +.. autoclass:: Outlet1D(phase, *, name=None) OutletReservoir1D ^^^^^^^^^^^^^^^^^ -.. autoclass:: OutletReservoir1D(phase, name=None) +.. autoclass:: OutletReservoir1D(phase, *, name=None) SymmetryPlane1D ^^^^^^^^^^^^^^^ -.. autoclass:: SymmetryPlane1D(phase, name=None) +.. autoclass:: SymmetryPlane1D(phase, *, name=None) Surface1D ^^^^^^^^^ -.. autoclass:: Surface1D(phase, name=None) +.. autoclass:: Surface1D(phase, * name=None) ReactingSurface1D ^^^^^^^^^^^^^^^^^ -.. autoclass:: ReactingSurface1D(phase, name=None) +.. autoclass:: ReactingSurface1D(phase, *, name=None) Base Classes ------------ Domain1D ^^^^^^^^ -.. autoclass:: Domain1D(name=None) +.. autoclass:: Domain1D(phase, *, name=None) Boundary1D ^^^^^^^^^^ -.. autoclass:: Boundary1D(phase, name=None) +.. autoclass:: Boundary1D(phase, *, name=None) Sim1D ^^^^^ @@ -111,4 +111,4 @@ Sim1D FlameBase ^^^^^^^^^ -.. autoclass:: FlameBase(domains, gas, grid=None) +.. autoclass:: FlameBase diff --git a/doc/sphinx/cython/thermo.rst b/doc/sphinx/cython/thermo.rst index 670713ce58..e7daad7c4a 100644 --- a/doc/sphinx/cython/thermo.rst +++ b/doc/sphinx/cython/thermo.rst @@ -14,20 +14,20 @@ These classes are used to describe the thermodynamic state of a system. ThermoPhase ^^^^^^^^^^^ -.. autoclass:: ThermoPhase(infile='', phaseid='') +.. autoclass:: ThermoPhase(infile='', name='', *, origin=None, source=None, yaml=None, thermo=None, species=(), **kwargs) InterfacePhase ^^^^^^^^^^^^^^ -.. autoclass:: InterfacePhase(infile='', phaseid='') +.. autoclass:: InterfacePhase(infile='', name='', adjacent=(), *, origin=None, source=None, yaml=None, thermo=None, species=(), **kwargs) PureFluid ^^^^^^^^^ -.. autoclass:: PureFluid(infile='', phaseid='') +.. autoclass:: PureFluid(infile='', name='') Mixture ------- -.. autoclass:: Mixture +.. autoclass:: Mixture(phases) Species ------- diff --git a/doc/sphinx/cython/transport.rst b/doc/sphinx/cython/transport.rst index d9cffe4d0c..c38f74a618 100644 --- a/doc/sphinx/cython/transport.rst +++ b/doc/sphinx/cython/transport.rst @@ -3,10 +3,10 @@ Transport Properties ==================== -.. autoclass:: Transport(infile='', phaseid='') -.. autoclass:: DustyGasTransport(infile='', phaseid='') +.. autoclass:: Transport() +.. autoclass:: DustyGasTransport() Species Transport Properties ---------------------------- -.. autoclass:: GasTransportData(geometry='', diameter=-1, well_depth=-1, dipole=0.0, polarizability=0.0, rotational_relaxation=0.0, acentric_factor=0.0) +.. autoclass:: GasTransportData(geometry='', diameter=-1, well_depth=-1, dipole=0.0, polarizability=0.0, rotational_relaxation=0.0, acentric_factor=0.0, dispersion_coefficient=0.0, quadrupole_polarizability=0.0) diff --git a/doc/sphinx/cython/zerodim.rst b/doc/sphinx/cython/zerodim.rst index 980b7349cc..89e739a162 100644 --- a/doc/sphinx/cython/zerodim.rst +++ b/doc/sphinx/cython/zerodim.rst @@ -18,16 +18,16 @@ Base Classes ReactorBase ^^^^^^^^^^^ -.. autoclass:: ReactorBase(contents=None, name=None) +.. autoclass:: ReactorBase FlowDevice ^^^^^^^^^^ -.. autoclass:: FlowDevice(upstream, downstream, *, name=None) +.. autoclass:: FlowDevice Reactor Networks ---------------- -.. autoclass:: ReactorNet(reactors=()) +.. autoclass:: ReactorNet Reactors -------- @@ -38,7 +38,7 @@ Reservoir Reactor ^^^^^^^ -.. autoclass:: Reactor(contents=None, *, name=None, energy='on') +.. autoclass:: Reactor IdealGasReactor ^^^^^^^^^^^^^^^ @@ -58,7 +58,7 @@ FlowReactor ExtensibleReactor ^^^^^^^^^^^^^^^^^ -.. autoclass:: ExtensibleReactor +.. autoclass:: ExtensibleReactor(contents=None, *, name=None, energy='on') ExtensibleIdealGasReactor ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -77,11 +77,7 @@ Walls Wall ^^^^ -.. autoclass:: Wall(left, right, *, name=None, A=None, K=None, U=None, Q=None, velocity=None, kinetics=(None,None)) - -WallSurface -^^^^^^^^^^^ -.. autoclass:: WallSurface(wall, side) +.. autoclass:: Wall(left, right, *, name=None, A=None, K=None, U=None, Q=None, velocity=None) Surfaces -------- @@ -95,15 +91,15 @@ Flow Controllers MassFlowController ^^^^^^^^^^^^^^^^^^ -.. autoclass:: MassFlowController(upstream, downstream, *, name=None, mdot=None) +.. autoclass:: MassFlowController :inherited-members: Valve ^^^^^ -.. autoclass:: Valve(upstream, downstream, *, name=None, K=None) +.. autoclass:: Valve :inherited-members: PressureController ^^^^^^^^^^^^^^^^^^ -.. autoclass:: PressureController(upstream, downstream, *, name=None, master=None, K=None) +.. autoclass:: PressureController :inherited-members: diff --git a/interfaces/cython/cantera/_cantera.pxd b/interfaces/cython/cantera/_cantera.pxd index 890b127c47..04ba9e836b 100644 --- a/interfaces/cython/cantera/_cantera.pxd +++ b/interfaces/cython/cantera/_cantera.pxd @@ -1487,16 +1487,8 @@ cdef class ReactorSurface: cdef CxxReactorSurface* surface cdef Kinetics _kinetics -cdef class WallSurface: - cdef CxxWallBase* cxxwall - cdef object wall - cdef int side - cdef Kinetics _kinetics - cdef class WallBase: cdef CxxWallBase* wall - cdef WallSurface left_surface - cdef WallSurface right_surface cdef object _velocity_func cdef object _heat_flux_func cdef ReactorBase _left_reactor diff --git a/interfaces/cython/cantera/base.pyx b/interfaces/cython/cantera/base.pyx index 20ebe1dc0a..0c0f03afbb 100644 --- a/interfaces/cython/cantera/base.pyx +++ b/interfaces/cython/cantera/base.pyx @@ -52,7 +52,7 @@ cdef object _wrap_Solution(shared_ptr[CxxSolution] cxx_soln): cdef class _SolutionBase: - def __cinit__(self, infile='', name='', adjacent=(), origin=None, + def __cinit__(self, infile='', name='', adjacent=(), *, origin=None, source=None, yaml=None, thermo=None, species=(), kinetics=None, reactions=(), init=True, **kwargs): diff --git a/interfaces/cython/cantera/composite.py b/interfaces/cython/cantera/composite.py index 7f4f421b2c..ed4a7b5e62 100644 --- a/interfaces/cython/cantera/composite.py +++ b/interfaces/cython/cantera/composite.py @@ -45,7 +45,7 @@ class Solution(Transport, Kinetics, ThermoPhase): gas = ct.Solution('gri30.yaml') If an input file defines multiple phases, the corresponding key in the - *phases* map (in YAML), *name* (in CTI), or *id* (in XML) can be used + ``phases`` map (in YAML), ``name`` (in CTI), or ``id`` (in XML) can be used to specify the desired phase via the ``name`` keyword argument of the constructor:: @@ -53,7 +53,7 @@ class Solution(Transport, Kinetics, ThermoPhase): diamond = ct.Solution('diamond.yaml', name='diamond') The name of the `Solution` object defaults to the *phase* identifier - specified in the input file. Upon initialization of a 'Solution' object, + specified in the input file. Upon initialization of a `Solution` object, a custom name can assigned via:: gas.name = 'my_custom_name' @@ -110,15 +110,14 @@ class Solution(Transport, Kinetics, ThermoPhase): class Interface(InterfaceKinetics, InterfacePhase): """ - Two-dimensional interfaces. - - Instances of class `Interface` represent reacting 2D interfaces between bulk - 3D phases. Class `Interface` defines no methods of its own. All of its - methods derive from either `InterfacePhase` or `InterfaceKinetics`. + Instances of class `Interface` represent reacting 2D surfaces between bulk 3D + phases, or 1D edges where multiple surfaces (and bulk phases) meet. Class + `Interface` defines no methods of its own. All of its methods derive from either + `InterfacePhase` or `InterfaceKinetics`. Constructing an `Interface` object also involves constructing adjacent bulk phases that participate in reactions. This is done automatically if the adjacent phases - are specified as part of the 'adjacent-phases' entry in the YAML phase definition:: + are specified as part of the ``adjacent-phases`` entry in the YAML phase definition:: diamond_surf = ct.Interface("diamond.yaml", name="diamond_100") gas = diamond_surf.adjacent["gas"] @@ -334,11 +333,21 @@ def setter(self, value): return property(getter, setter, doc=getattr(Solution, attr).__doc__) +def _method(orig): + def f(self, *args, **kwargs): + return orig(self.phase, *args, **kwargs) + f.__doc__ = orig.__doc__ + return f + for _attr in dir(Solution): if _attr.startswith('_') or _attr in Quantity.__dict__ or _attr == 'state': continue else: - setattr(Quantity, _attr, _prop(_attr)) + _orig = getattr(Solution, _attr) + if hasattr(_orig, "__call__"): + setattr(Quantity, _attr, _method(_orig)) + else: + setattr(Quantity, _attr, _prop(_attr)) class SolutionArray: @@ -348,7 +357,7 @@ class SolutionArray: array of states. `SolutionArray` can represent both 1D and multi-dimensional arrays of states, - with shapes described in the same way as Numpy arrays. All of the states + with shapes described in the same way as *NumPy* arrays. All of the states can be set in a single call:: >>> gas = ct.Solution('gri30.yaml') @@ -358,13 +367,13 @@ class SolutionArray: >>> X = 'CH4:1.0, O2:1.0, N2:3.76' >>> states.TPX = T, P, X - Similar to Numpy arrays, input with fewer non-singleton dimensions than the + Similar to *NumPy* arrays, input with fewer non-singleton dimensions than the `SolutionArray` is 'broadcast' to generate input of the appropriate shape. In the above example, the single value for the mole fraction input is applied to each input, while each row has a constant temperature and each column has a constant pressure. - Computed properties are returned as Numpy arrays with the same shape as the + Computed properties are returned as *NumPy* arrays with the same shape as the array of states, with additional dimensions appended as necessary for non- scalar output (e.g. per-species or per-reaction properties):: @@ -385,7 +394,7 @@ class SolutionArray: >>> states.equilibrate('HP') >>> states.T # -> adiabatic flame temperature at various equivalence ratios - `SolutionArray` objects can also be 'sliced' like Numpy arrays, which can be + `SolutionArray` objects can also be 'sliced' like *NumPy* arrays, which can be used both for accessing and setting properties:: >>> states = ct.SolutionArray(gas, (6, 10)) @@ -438,10 +447,10 @@ class SolutionArray: >>> states = ct.SolutionArray(gas) >>> states.read_hdf('somefile.h5', key='some_key') - For HDF export and import, the (optional) keyword argument *group* allows + For HDF export and import, the (optional) keyword argument ``group`` allows for saving and accessing of multiple solutions in a single container file. - Note that `write_hdf` and `read_hdf` require a working installation of h5py. - The package `h5py` can be installed using pip or conda. + Note that `write_hdf` and `read_hdf` require a working installation of *h5py*. + The package *h5py* can be installed using pip or conda. :param phase: The `Solution` object used to compute the thermodynamic, kinetic, and transport properties @@ -766,7 +775,7 @@ def meta(self): def sort(self, col, reverse=False): """ - Sort SolutionArray by column *col*. + Sort SolutionArray by column ``col``. :param col: Column that is used to sort the SolutionArray. :param reverse: If True, the sorted list is reversed (descending order). @@ -790,7 +799,7 @@ def equilibrate(self, *args, **kwargs): def restore_data(self, data, normalize=True): """ - Restores a `SolutionArray` based on *data* specified in an ordered + Restores a `SolutionArray` based on ``data`` specified in an ordered dictionary. Thus, this method allows to restore data exported by `collect_data`. @@ -978,8 +987,8 @@ def set_equivalence_ratio(self, phi, *args, **kwargs): """ See `ThermoPhase.set_equivalence_ratio` - Note that *phi* either needs to be a scalar value or dimensions have - to be matched to the SolutionArray. + Note that ``phi`` either needs to be a scalar value or dimensions have + to be matched to the `SolutionArray`. """ # broadcast argument shape @@ -993,14 +1002,14 @@ def set_equivalence_ratio(self, phi, *args, **kwargs): def collect_data(self, cols=None, tabular=False, threshold=0, species=None): """ - Returns the data specified by *cols* in an ordered dictionary, where - keys correspond to SolutionArray attributes to be exported. + Returns the data specified by ``cols`` in an ordered dictionary, where + keys correspond to `SolutionArray` attributes to be exported. :param cols: A list of any properties of the solution that are scalars or which have a value for each species or reaction. If species names are specified, then either the mass or mole fraction of that species - will be taken, depending on the value of *species*. *cols* may also - include any arrays which were specified as 'extra' variables when + will be taken, depending on the value of ``species``. ``cols`` may also + include any arrays which were specified as ``extra`` variables when defining the `SolutionArray` object. The special value 'extra' can be used to include all 'extra' variables. :param tabular: Split 2D data into separate 1D columns for each @@ -1088,8 +1097,8 @@ def split(c, d): def write_csv(self, filename, cols=None, *args, **kwargs): """ - Write a CSV file named *filename* containing the data specified by - *cols*. The first row of the CSV file will contain column labels. + Write a CSV file named ``filename`` containing the data specified by + ``cols``. The first row of the CSV file will contain column labels. Additional arguments are passed on to `collect_data`. This method works only with 1D `SolutionArray` objects. @@ -1105,7 +1114,7 @@ def write_csv(self, filename, cols=None, *args, **kwargs): def read_csv(self, filename, normalize=True): """ - Read a CSV file named *filename* and restore data to the `SolutionArray` + Read a CSV file named ``filename`` and restore data to the `SolutionArray` using `restore_data`. This method allows for recreation of data previously exported by `write_csv`. @@ -1132,11 +1141,11 @@ def read_csv(self, filename, normalize=True): def to_pandas(self, cols=None, *args, **kwargs): """ - Returns the data specified by *cols* in a single pandas DataFrame. + Returns the data specified by ``cols`` in a single `pandas.DataFrame`. Additional arguments are passed on to `collect_data`. This method works - only with 1D `SolutionArray` objects and requires a working pandas - installation. Use pip or conda to install `pandas` to enable this method. + only with 1D `SolutionArray` objects and requires a working *pandas* + installation. Use pip or conda to install ``pandas`` to enable this method. """ if isinstance(_pandas, ImportError): @@ -1149,11 +1158,11 @@ def to_pandas(self, cols=None, *args, **kwargs): def from_pandas(self, df, normalize=True): """ - Restores `SolutionArray` data from a pandas DataFrame *df*. + Restores `SolutionArray` data from a `pandas.DataFrame` ``df``. This method is intendend for loading of data that were previously - exported by `to_pandas`. The method requires a working pandas - installation. The package 'pandas' can be installed using pip or conda. + exported by `to_pandas`. The method requires a working *pandas* + installation. The package ``pandas`` can be installed using pip or conda. The ``normalize`` argument is passed on to `restore_data` to normalize mole or mass fractions. By default, ``normalize`` is ``True``. @@ -1171,9 +1180,9 @@ def write_hdf(self, filename, *args, cols=None, group=None, subgroup=None, attrs={}, mode='a', append=False, compression=None, compression_opts=None, **kwargs): """ - Write data specified by *cols* to a HDF container file named *filename*. + Write data specified by ``cols`` to an HDF container file named ``filename``. Note that it is possible to write multiple data entries to a single HDF - container file, where *group* is used to differentiate data. + container file, where ``group`` is used to differentiate data. An example for the default HDF file structure is::: @@ -1189,8 +1198,8 @@ def write_hdf(self, filename, *args, cols=None, group=None, subgroup=None, where ``group0`` is the default name for the top level HDF entry. In addition to datasets, information stored in `SolutionArray.meta` is - saved in form of HDF attributes. An additional intermediate layer may - be created using the *subgroup* argument. + saved in the form of HDF attributes. An additional intermediate layer may + be created using the ``subgroup`` argument. :param filename: Name of the HDF container file; typical file extensions are @@ -1210,7 +1219,7 @@ def write_hdf(self, filename, *args, cols=None, group=None, subgroup=None, Dictionary of user-defined attributes added at the group level (typically used in conjunction with a subgroup argument). :param mode: - Mode h5py uses to open the output file {'a' to read/write if file + Mode *h5py* uses to open the output file {'a' to read/write if file exists, create otherwise (default); 'w' to create file, truncate if exists; 'r+' to read/write, file must exist}. :param append: @@ -1218,21 +1227,21 @@ def write_hdf(self, filename, *args, cols=None, group=None, subgroup=None, writing the `SolutionArray` in the first position. If True, the current `SolutionArray` objects is appended to the group. :param compression: - Pre-defined h5py compression filters {None, 'gzip', 'lzf', 'szip'} + Pre-defined *h5py* compression filters {None, 'gzip', 'lzf', 'szip'} used for data compression. :param compression_opts: - Options for the h5py compression filter; for 'gzip', this + Options for the *h5py* compression filter; for 'gzip', this corresponds to the compression level {None, 0-9}. :return: Group identifier used for storing HDF data. - Arguments *compression*, and *compression_opts* are mapped to parameters - for `h5py.create_dataset`; in both cases, the choices of `None` results - in default values set by h5py. + Arguments ``compression`` and ``compression_opts`` are mapped to parameters + for `h5py.create_dataset`; in both cases, the choices of ``None`` results + in default values set by *h5py*. - Additional arguments (i.e. *args* and *kwargs*) are passed on to + Additional arguments (that is, ``*args`` and ``**kwargs``) are passed on to `collect_data`; see `collect_data` for further information. This method - requires a working installation of h5py (`h5py` can be installed using + requires a working installation of *h5py* (``h5py`` can be installed using pip or conda). """ if isinstance(_h5py, ImportError): @@ -1317,7 +1326,7 @@ def read_hdf(self, filename, group=None, subgroup=None, force=False, normalize=T the `SolutionArray` information. The method imports data using `restore_data` and requires a working - installation of h5py (`h5py` can be installed using pip or conda). + installation of *h5py* (``h5py`` can be installed using pip or conda). """ if isinstance(_h5py, ImportError): raise _h5py @@ -1566,10 +1575,24 @@ def setter(self, value): return property(getter, setter, doc=getattr(doc_source, name).__doc__) + def passthrough_method(orig): + def f(self, *args, **kwargs): + return orig(self._phase, *args, **kwargs) + f.__doc__ = orig.__doc__ + return f + for name in SolutionArray._passthrough: - setattr(SolutionArray, name, passthrough_prop(name, Solution)) + orig = getattr(Solution, name) + if hasattr(orig, "__call__"): + setattr(SolutionArray, name, passthrough_method(orig)) + else: + setattr(SolutionArray, name, passthrough_prop(name, Solution)) for name in SolutionArray._interface_passthrough: - setattr(SolutionArray, name, passthrough_prop(name, Interface)) + orig = getattr(Interface, name) + if hasattr(orig, "__call__"): + setattr(SolutionArray, name, passthrough_method(orig)) + else: + setattr(SolutionArray, name, passthrough_prop(name, Interface)) _make_functions() diff --git a/interfaces/cython/cantera/ctml2yaml.py b/interfaces/cython/cantera/ctml2yaml.py index 8024c8a876..cf6fa5f18f 100644 --- a/interfaces/cython/cantera/ctml2yaml.py +++ b/interfaces/cython/cantera/ctml2yaml.py @@ -172,11 +172,11 @@ def float2string(data: float) -> str: :param data: The floating point data to be formatted. - Uses NumPy's ``format_float_positional()`` and ``format_float_scientific()`` if they - are is available, requires NumPy >= 1.14. In that case, values with magnitude - between 0.01 and 10000 are formatted using ``format_float_positional ()`` and other - values are formatted using ``format_float_scientific()``. If those NumPy functions - are not available, returns the ``repr`` of the input. + Uses *NumPy*'s ``format_float_positional()`` and ``format_float_scientific()`` if + they are is available, requires ``numpy >= 1.14``. In that case, values with + magnitude between 0.01 and 10000 are formatted using ``format_float_positional ()`` + and other values are formatted using ``format_float_scientific()``. If those *NumPy* + functions are not available, returns the ``repr`` of the input. """ if not HAS_FMT_FLT_POS: return repr(data) diff --git a/interfaces/cython/cantera/func1.pyx b/interfaces/cython/cantera/func1.pyx index 9315576998..39ea501f1b 100644 --- a/interfaces/cython/cantera/func1.pyx +++ b/interfaces/cython/cantera/func1.pyx @@ -5,10 +5,10 @@ import sys cdef double func_callback(double t, void* obj, void** err): """ - This function is called from C/C++ to evaluate a `Func1` object *obj*, - returning the value of the function at *t*. If an exception occurs while + This function is called from C/C++ to evaluate a `Func1` object ``obj``, + returning the value of the function at ``t``. If an exception occurs while evaluating the function, the Python exception info is saved in the - two-element array *err*. + two-element array ``err``. """ try: return (obj).callable(t) diff --git a/interfaces/cython/cantera/kinetics.pyx b/interfaces/cython/cantera/kinetics.pyx index ffc60b6780..a33560537b 100644 --- a/interfaces/cython/cantera/kinetics.pyx +++ b/interfaces/cython/cantera/kinetics.pyx @@ -115,8 +115,8 @@ cdef class Kinetics(_SolutionBase): def kinetics_species_index(self, species, int phase=0): """ - The index of species *species* of phase *phase* within arrays returned - by methods of class `Kinetics`. If *species* is a string, the *phase* + The index of species ``species`` of phase ``phase`` within arrays returned + by methods of class `Kinetics`. If ``species`` is a string, the ``phase`` argument is unused. """ cdef int k @@ -130,7 +130,7 @@ cdef class Kinetics(_SolutionBase): def kinetics_species_name(self, k): """ - Name of the species with index *k* in the arrays returned by methods + Name of the species with index ``k`` in the arrays returned by methods of class `Kinetics`. """ return pystr(self.kinetics.kineticsSpeciesName(k)) @@ -176,14 +176,14 @@ cdef class Kinetics(_SolutionBase): self.kinetics.addReaction(rxn._reaction) def is_reversible(self, int i_reaction): - """True if reaction `i_reaction` is reversible.""" + """True if reaction ``i_reaction`` is reversible.""" self._check_reaction_index(i_reaction) return self.kinetics.isReversible(i_reaction) def multiplier(self, int i_reaction): """ A scaling factor applied to the rate coefficient for reaction - *i_reaction*. Can be used to carry out sensitivity analysis or to + ``i_reaction``. Can be used to carry out sensitivity analysis or to selectively disable a particular reaction. See `set_multiplier`. """ self._check_reaction_index(i_reaction) @@ -191,9 +191,9 @@ cdef class Kinetics(_SolutionBase): def set_multiplier(self, double value, int i_reaction=-1): """ - Set the multiplier for for reaction *i_reaction* to *value*. - If *i_reaction* is not specified, then the multiplier for all reactions - is set to *value*. See `multiplier`. + Set the multiplier for for reaction ``i_reaction`` to ``value``. + If ``i_reaction`` is not specified, then the multiplier for all reactions + is set to ``value``. See `multiplier`. """ if i_reaction == -1: for i_reaction in range(self.n_reactions): @@ -204,7 +204,7 @@ cdef class Kinetics(_SolutionBase): def reaction_type(self, int i_reaction): """ - Type code of reaction *i_reaction*. + Type code of reaction ``i_reaction``. .. deprecated:: 2.6 """ @@ -216,7 +216,7 @@ cdef class Kinetics(_SolutionBase): return self.kinetics.reactionType(i_reaction) def reaction_type_str(self, int i_reaction): - """Type of reaction *i_reaction*.""" + """Type of reaction ``i_reaction``.""" self._check_reaction_index(i_reaction) return pystr(self.kinetics.reactionTypeStr(i_reaction)) @@ -238,8 +238,8 @@ cdef class Kinetics(_SolutionBase): def reaction_equations(self, indices=None): """ Returns a list containing the reaction equation for all reactions in the - mechanism (if *indices* is unspecified) or the equations for each - reaction in the sequence *indices*. For example:: + mechanism if ``indices`` is unspecified, or the equations for each + reaction in the sequence ``indices``. For example:: >>> gas.reaction_equations() ['2 O + M <=> O2 + M', 'O + H + M <=> OH + M', 'O + H2 <=> H + OH', ...] @@ -400,9 +400,9 @@ cdef class Kinetics(_SolutionBase): three-body reactions are multiplied with third-body concentrations (no change to legacy behavior). After Cantera 2.6, results will no longer include third-body concentrations and be consistent with conventional - definitions (see Eq. 9.75 in Kee, Coltrin and Glarborg, 'Chemically - Reacting Flow', Wiley Interscience, 2003). - To switch to new behavior, run 'cantera.use_legacy_rate_constants(False)'. + definitions (see Eq. 9.75 in Kee, Coltrin, and Glarborg, *Chemically + Reacting Flow*, Wiley Interscience, 2003). + To switch to new behavior, run ``ct.use_legacy_rate_constants(False)``. """ def __get__(self): return get_reaction_array(self, kin_getFwdRateConstants) @@ -420,9 +420,9 @@ cdef class Kinetics(_SolutionBase): three-body reactions are multiplied with third-body concentrations (no change to legacy behavior). After Cantera 2.6, results will no longer include third-body concentrations and be consistent with conventional - definitions (see Eq. 9.75 in Kee, Coltrin and Glarborg, 'Chemically - Reacting Flow', Wiley Interscience, 2003). - To switch to new behavior, run 'cantera.use_legacy_rate_constants(False)'. + definitions (see Eq. 9.75 in Kee, Coltrin and Glarborg, *Chemically + Reacting Flow*, Wiley Interscience, 2003). + To switch to new behavior, run ``ct.use_legacy_rate_constants(False)``. """ def __get__(self): return get_reaction_array(self, kin_getRevRateConstants) @@ -851,7 +851,7 @@ cdef class InterfaceKinetics(Kinetics): def phase_index(self, phase): """ - Get the index of the phase *phase*, where *phase* may specified using + Get the index of the phase ``phase``, where ``phase`` may specified using the phase object, the name, or the index itself. """ return self._phase_indices[phase] @@ -869,7 +869,7 @@ cdef class InterfaceKinetics(Kinetics): def get_creation_rates(self, phase): """ - Creation rates for each species in phase *phase*. Use the + Creation rates for each species in phase ``phase``. Use the `creation_rates` property to get the creation rates for species in all phases. """ @@ -877,7 +877,7 @@ cdef class InterfaceKinetics(Kinetics): def get_destruction_rates(self, phase): """ - Destruction rates for each species in phase *phase*. Use the + Destruction rates for each species in phase ``phase``. Use the `destruction_rates` property to get the destruction rates for species in all phases. """ @@ -885,8 +885,8 @@ cdef class InterfaceKinetics(Kinetics): def get_net_production_rates(self, phase): """ - Net production rates for each species in phase *phase*. Use the - `net_production_rates` property to get the net_production rates for + Net production rates for each species in phase ``phase``. Use the + `net_production_rates` property to get the net production rates for species in all phases. """ return self.net_production_rates[self._phase_slice(phase)] diff --git a/interfaces/cython/cantera/liquidvapor.py b/interfaces/cython/cantera/liquidvapor.py index 48a5837263..eaec05ebf5 100644 --- a/interfaces/cython/cantera/liquidvapor.py +++ b/interfaces/cython/cantera/liquidvapor.py @@ -10,7 +10,7 @@ def Water(backend='Reynolds'): `WaterTransport` class for viscosity and thermal conductivity. The object returned by this method implements an accurate equation of state - for water, where implementations are selected using the *backend* switch. + for water, where implementations are selected using the ``backend`` switch. For the ``Reynolds`` backend, the equation of state is taken from @@ -37,8 +37,8 @@ def Water(backend='Reynolds'): the Viscosity and Thermal Conductivity of Water Substance,* J. Phys. Chem. Ref. Data, 15, 1291, 1986. - For more details, see classes :ct:PureFluid, tpx::water, - :ct:WaterSSTP and :ct:WaterTransport in the Cantera C++ source + For more details, see classes :ct:`PureFluidPhase`, :ct:`tpx::water`, + :ct:`WaterSSTP` and :ct:`WaterTransport` in the Cantera C++ source code documentation. """ class WaterWithTransport(_cantera.Transport, PureFluid): @@ -67,7 +67,7 @@ def Nitrogen(): computational equations for forty substances* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::nitrogen in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::nitrogen` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'nitrogen') @@ -86,7 +86,7 @@ def Methane(): computational equations for forty substances* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::methane in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::methane` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'methane') @@ -105,7 +105,7 @@ def Hydrogen(): computational equations for forty substances* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::hydrogen in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::hydrogen` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'hydrogen') @@ -124,7 +124,7 @@ def Oxygen(): computational equations for forty substances* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::oxygen in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::oxygen` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'oxygen') @@ -145,7 +145,7 @@ def Hfc134a(): Chem. Ref. Data, Vol. 23, No. 5, 1994. pp. 657--729. http://dx.doi.org/10.1063/1.555958 - For more details, see classes :ct:PureFluid and tpx::HFC134a in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::HFC134a` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'HFC-134a') @@ -164,7 +164,7 @@ def CarbonDioxide(): computational equations for forty substances.* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::CarbonDioxide in + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::CarbonDioxide` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'carbon-dioxide') @@ -183,7 +183,7 @@ def Heptane(): computational equations for forty substances.* Stanford: Stanford University, 1979. Print. - For more details, see classes :ct:PureFluid and tpx::Heptane in the + For more details, see classes :ct:`PureFluidPhase` and :ct:`tpx::Heptane` in the Cantera C++ source code documentation. """ return PureFluid('liquidvapor.yaml', 'heptane') diff --git a/interfaces/cython/cantera/mixture.pyx b/interfaces/cython/cantera/mixture.pyx index 5651ff44b1..b9a15ce323 100644 --- a/interfaces/cython/cantera/mixture.pyx +++ b/interfaces/cython/cantera/mixture.pyx @@ -109,7 +109,7 @@ cdef class Mixture: return self.mix.nSpecies() def species_name(self, k): - """Name of the species with index *k*. Note that index numbers + """Name of the species with index ``k``. Note that index numbers are assigned in order as phases are added.""" return pystr(self.mix.speciesName(k)) @@ -124,7 +124,7 @@ cdef class Mixture: :param species: Species name or index - Returns the global index of species *species* in phase *phase*. + Returns the global index of species ``species`` in phase ``phase``. """ p = self.phase_index(phase) @@ -141,7 +141,7 @@ cdef class Mixture: def n_atoms(self, k, m): """ - Number of atoms of element *m* in the species with global index *k*. + Number of atoms of element ``m`` in the species with global index ``k``. The element may be referenced either by name or by index. >>> n = mix.n_atoms(3, 'H') @@ -160,7 +160,7 @@ cdef class Mixture: return self._phases[n] def phase_index(self, p): - """Index of the phase named *p*.""" + """Index of the phase named ``p``.""" if isinstance(p, ThermoPhase): p = p.name @@ -222,12 +222,12 @@ cdef class Mixture: return self.mix.charge() def phase_charge(self, p): - """The charge of phase *p* in Coulombs.""" + """The charge of phase ``p`` in Coulombs.""" return self.mix.phaseCharge(self.phase_index(p)) def phase_moles(self, p=None): """ - Moles in phase *p*, if *p* is specified, otherwise the number of + Moles in phase ``p``, if ``p`` is specified, otherwise the number of moles in all phases. """ if p is None: @@ -237,7 +237,7 @@ cdef class Mixture: def set_phase_moles(self, p, moles): """ - Set the number of moles of phase *p* to *moles* + Set the number of moles of phase ``p`` to ``moles``. """ self.mix.setPhaseMoles(self.phase_index(p), moles) @@ -271,7 +271,7 @@ cdef class Mixture: def element_moles(self, e): """ - Total number of moles of element *e*, summed over all species. + Total number of moles of element ``e``, summed over all species. The element may be referenced either by index number or by name. """ return self.mix.elementMoles(self.element_index(e)) @@ -286,7 +286,7 @@ cdef class Mixture: def equilibrate(self, XY, solver='auto', rtol=1e-9, max_steps=1000, max_iter=100, estimate_equil=0, log_level=0): """ - Set to a state of chemical equilibrium holding property pair *XY* + Set to a state of chemical equilibrium holding property pair ``XY`` constant. This method uses a version of the VCS algorithm to find the composition that minimizes the total Gibbs free energy of the mixture, subject to element conservation constraints. For a description of the diff --git a/interfaces/cython/cantera/onedim.py b/interfaces/cython/cantera/onedim.py index 04ed26ce1e..5864108e6d 100644 --- a/interfaces/cython/cantera/onedim.py +++ b/interfaces/cython/cantera/onedim.py @@ -33,7 +33,7 @@ def __init__(self, domains, gas, grid=None): def other_components(self, domain=None): """ The method returns simulation components that are specific to a class - derived from `FlameBase` or a specific *domain* within the `FlameBase` + derived from `FlameBase` or a specific ``domain`` within the `FlameBase` simulation object. Entries may include: * ``grid``: grid point positions along the flame [m] @@ -104,11 +104,11 @@ def set_initial_guess(self, *args, data=None, group=None, **kwargs): :param data: Restart data, which are typically based on an earlier simulation result. Restart data may be specified using a `SolutionArray`, - pandas' DataFrame, or previously saved CSV or HDF container files. + `pandas.DataFrame`, or previously saved CSV or HDF container files. Note that restart data do not overwrite boundary conditions. - DataFrame input requires a working installation of pandas, whereas - HDF input requires an installation of h5py. These packages can be - installed using pip or conda (`pandas` and `h5py`, respectively). + DataFrame input requires a working installation of *pandas*, whereas + HDF input requires an installation of *h5py*. These packages can be + installed using pip or conda (``pandas`` and ``h5py``, respectively). :param key: Group identifier within a HDF container file (only used in combination with HDF restart data). @@ -190,7 +190,7 @@ def set_profile(self, component, positions, values): :param positions: sequence of relative positions, from 0 on the left to 1 on the right :param values: - sequence of values at the relative positions specified in *positions* + sequence of values at the relative positions specified in ``positions`` >>> f.set_profile('T', [0.0, 0.2, 1.0], [400.0, 800.0, 1500.0]) """ @@ -357,7 +357,7 @@ def elemental_mole_fraction(self, m): def solution(self, component, point=None): """ Get the solution at one point or for the full flame domain (if - `point=None`) for the specified *component*. The *component* can be + ``point=None``) for the specified ``component``. The ``component`` can be specified by name or index. """ if point is None: @@ -367,9 +367,9 @@ def solution(self, component, point=None): def set_gas_state(self, point): """ - Set the state of the the Solution object used for calculations, - `self.gas`, to the temperature and composition at the point with index - *point*. + Set the state of the the `Solution` object used for calculations + to the temperature and composition at the point with index + ``point``. """ k0 = self.flame.component_index(self.gas.species_name(0)) Y = [self.solution(k, point) @@ -463,8 +463,8 @@ def to_pandas(self, species='X', normalize=True): Boolean flag to indicate whether the mole/mass fractions should be normalized (default is ``True``) - This method uses `to_solution_array` and requires a working pandas - installation. Use pip or conda to install `pandas` to enable this + This method uses `to_solution_array` and requires a working *pandas* + installation. Use pip or conda to install ``pandas`` to enable this method. """ cols = ('extra', 'T', 'D', species) @@ -485,7 +485,7 @@ def from_pandas(self, df, restore_boundaries=True, settings=None): This method is intendend for loading of data that were previously exported by `to_pandas`. The method uses `from_solution_array` and - requires a working pandas installation. The package 'pandas' can be + requires a working *pandas* installation. The package ``pandas`` can be installed using pip or conda. """ arr = SolutionArray(self.gas, extra=self.other_components()) @@ -543,16 +543,16 @@ def write_hdf(self, filename, *args, group=None, species='X', mode='a', Attribute to use obtaining species profiles, e.g. ``X`` for mole fractions or ``Y`` for mass fractions. :param mode: - Mode h5py uses to open the output file {'a' to read/write if file + Mode *h5py* uses to open the output file {'a' to read/write if file exists, create otherwise (default); 'w' to create file, truncate if exists; 'r+' to read/write, file must exist}. :param description: Custom comment describing the dataset to be stored. :param compression: - Pre-defined h5py compression filters {None, 'gzip', 'lzf', 'szip'} + Pre-defined *h5py* compression filters {None, 'gzip', 'lzf', 'szip'} used for data compression. :param compression_opts: - Options for the h5py compression filter; for 'gzip', this + Options for the *h5py* compression filter; for 'gzip', this corresponds to the compression level {None, 0-9}. :param quiet: Suppress message confirming successful file output. @@ -560,10 +560,10 @@ def write_hdf(self, filename, *args, group=None, species='X', mode='a', Boolean flag to indicate whether the mole/mass fractions should be normalized (default is ``True``) - Additional arguments (i.e. *args* and *kwargs*) are passed on to + Additional arguments (that is, ``*args`` and ``**kwargs``) are passed on to `SolutionArray.collect_data`. The method exports data using `SolutionArray.write_hdf` via `to_solution_array` and requires a working - installation of h5py (`h5py` can be installed using pip or conda). + installation of *h5py* (``h5py`` can be installed using pip or conda). """ cols = ('extra', 'T', 'D', species) meta = self.settings @@ -603,8 +603,8 @@ def read_hdf(self, filename, group=None, restore_boundaries=True, normalize=True be normalized (default is ``True``) The method imports data using `SolutionArray.read_hdf` via - `from_solution_array` and requires a working installation of h5py - (`h5py` can be installed using pip or conda). + `from_solution_array` and requires a working installation of *h5py* + (``h5py`` can be installed using pip or conda). """ if restore_boundaries: domains = range(3) @@ -1286,15 +1286,15 @@ def strain_rate(self, definition, fuel=None, oxidizer='O2', stoich=None): The definition of the strain rate to be calculated. Options are: ``mean``, ``max``, ``stoichiometric``, ``potential_flow_fuel``, and ``potential_flow_oxidizer``. - :param fuel: The fuel species. Used only if *definition* is + :param fuel: The fuel species. Used only if ``definition`` is ``stoichiometric``. :param oxidizer: The oxidizer species, default ``O2``. Used only if - *definition* is ``stoichiometric``. + ``definition`` is ``stoichiometric``. :param stoich: The molar stoichiometric oxidizer-to-fuel ratio. - Can be omitted if the oxidizer is ``O2``. Used only if *definition* + Can be omitted if the oxidizer is ``O2``. Used only if ``definition`` is ``stoichiometric``. - The parameter *definition* sets the method to compute the strain rate. + The parameter ``definition`` sets the method to compute the strain rate. Possible options are: ``mean``: @@ -1315,8 +1315,8 @@ def strain_rate(self, definition, fuel=None, oxidizer='O2', stoich=None): a_{stoichiometric} = \left| \left. \frac{du}{dz} \right|_{\phi=1} \right| - This method uses the additional keyword arguments *fuel*, - *oxidizer*, and *stoich*. + This method uses the additional keyword arguments ``fuel``, + ``oxidizer``, and ``stoich``. >>> f.strain_rate('stoichiometric', fuel='H2', oxidizer='O2', stoich=0.5) @@ -1370,11 +1370,11 @@ def strain_rate(self, definition, fuel=None, oxidizer='O2', stoich=None): def mixture_fraction(self, m): r""" - Compute the mixture fraction based on element *m* or from the - Bilger mixture fraction (m="Bilger") + Compute the mixture fraction based on element ``m`` or from the + Bilger mixture fraction by setting ``m="Bilger"`` The mixture fraction is computed from the elemental mass fraction of - element *m*, normalized by its values on the fuel and oxidizer + element ``m``, normalized by its values on the fuel and oxidizer inlets: .. math:: Z = \frac{Z_{\mathrm{mass},m}(z) - diff --git a/interfaces/cython/cantera/onedim.pyx b/interfaces/cython/cantera/onedim.pyx index e2be28cc0a..7b9282b3f0 100644 --- a/interfaces/cython/cantera/onedim.pyx +++ b/interfaces/cython/cantera/onedim.pyx @@ -13,7 +13,6 @@ cdef class Domain1D: def __cinit__(self, *args, **kwargs): self.domain = NULL - # The signature of this function causes warnings for Sphinx documentation def __init__(self, _SolutionBase phase, *args, name=None, **kwargs): self._weakref_proxy = _WeakrefProxy() if self.domain is NULL: @@ -69,9 +68,9 @@ cdef class Domain1D: Set the lower and upper bounds on the solution. The argument list should consist of keyword/value pairs, with - component names as keywords and (lower_bound, upper_bound) tuples as - the values. The keyword *default* may be used to specify default - bounds for all unspecified components. The keyword *Y* can be used to + component names as keywords and (lower bound, upper bound) tuples as + the values. The keyword ``default`` may be used to specify default + bounds for all unspecified components. The keyword ``Y`` can be used to stand for all species mass fractions in flow domains. >>> d.set_bounds(default=(0, 1), Y=(-1.0e-5, 2.0)) @@ -93,12 +92,12 @@ cdef class Domain1D: """ Set the error tolerances for the steady-state problem. - The argument list should consist of keyword/value pairs, with - component names as keywords and (rtol, atol) tuples as the values. - The keyword *default* may be used to specify default bounds for all - unspecified components. The keyword *Y* can be used to stand for all + The argument list should consist of keyword/value pairs, with component names as + keywords and (relative tolerance, absolute tolerance) tuples as the values. + The keyword ``default`` may be used to specify default bounds for all + unspecified components. The keyword ``Y`` can be used to stand for all species mass fractions in flow domains. Alternatively, the keywords - *abs* and *rel* can be used to specify arrays for the absolute and + ``abs`` and ``rel`` can be used to specify arrays for the absolute and relative tolerances for each solution component. """ self.have_user_tolerances = True @@ -128,12 +127,12 @@ cdef class Domain1D: """ Set the error tolerances for the steady-state problem. - The argument list should consist of keyword/value pairs, with - component names as keywords and (rtol, atol) tuples as the values. - The keyword *default* may be used to specify default bounds for all - unspecified components. The keyword *Y* can be used to stand for all + The argument list should consist of keyword/value pairs, with component names as + keywords and (relative tolerance, absolute tolerance) tuples as the values. + The keyword ``default`` may be used to specify default bounds for all + unspecified components. The keyword ``Y`` can be used to stand for all species mass fractions in flow domains. Alternatively, the keywords - *abs* and *rel* can be used to specify arrays for the absolute and + ``abs`` and ``rel`` can be used to specify arrays for the absolute and relative tolerances for each solution component. """ self.have_user_tolerances = True @@ -280,7 +279,6 @@ cdef class Boundary1D(Domain1D): def __cinit__(self, *args, **kwargs): self.boundary = NULL - # The signature of this function causes warnings for Sphinx documentation def __init__(self, *args, **kwargs): if self.boundary is NULL: raise TypeError("Can't instantiate abstract class Boundary1D.") @@ -708,7 +706,6 @@ cdef class Sim1D: def __cinit__(self, *args, **kwargs): self.sim = NULL - # The signature of this function causes warnings for Sphinx documentation def __init__(self, domains, *args, **kwargs): cdef vector[CxxDomain1D*] D cdef Domain1D d @@ -737,10 +734,10 @@ cdef class Sim1D: def set_interrupt(self, f): """ - Set an interrupt function to be called each time that OneDim::eval is - called. The signature of *f* is `float f(float)`. The default - interrupt function is used to trap KeyboardInterrupt exceptions so - that `ctrl-c` can be used to break out of the C++ solver loop. + Set an interrupt function to be called each time that :ct:`OneDim::eval` is + called. The signature of ``f`` is ``float f(float)``. The default + interrupt function is used to trap `KeyboardInterrupt` exceptions so + that ``ctrl-c`` can be used to break out of the C++ solver loop. """ if f is None: self.sim.setInterrupt(NULL) @@ -755,7 +752,7 @@ cdef class Sim1D: def set_time_step_callback(self, f): """ Set a callback function to be called after each successful timestep. - The signature of *f* is `float f(float)`. The argument passed to *f* is + The signature of ``f`` is ``float f(float)``. The argument passed to ``f`` is the size of the timestep. The output is ignored. """ if f is None: @@ -771,8 +768,8 @@ cdef class Sim1D: def set_steady_callback(self, f): """ Set a callback function to be called after each successful steady-state - solve, before regridding. The signature of *f* is `float f(float)`. The - argument passed to *f* is "0" and the output is ignored. + solve, before regridding. The signature of ``f`` is ``float f(float)``. The + argument passed to ``f`` is 0.0 and the output is ignored. """ if f is None: self.sim.setSteadyCallback(NULL) @@ -826,7 +823,7 @@ cdef class Sim1D: :param component: component name or index :param point: - grid point number within *domain* starting with 0 on the left + grid point number within ``domain`` starting with 0 on the left >>> t = s.value('flow', 'T', 6) """ @@ -842,7 +839,7 @@ cdef class Sim1D: :param component: component name or index :param point: - grid point number within *domain* starting with 0 on the left + grid point number within ``domain`` starting with 0 on the left :param value: numerical value @@ -911,7 +908,7 @@ cdef class Sim1D: :param positions: sequence of relative positions, from 0 on the left to 1 on the right :param values: - sequence of values at the relative positions specified in *positions* + sequence of values at the relative positions specified in ``positions`` >>> s.set_profile(d, 'T', [0.0, 0.2, 1.0], [400.0, 800.0, 1500.0]) """ @@ -942,14 +939,13 @@ cdef class Sim1D: def collect_data(self, domain, other): """ - Return underlying data specifying a *domain*. Method is used as + Return the underlying data specifying a ``domain``. This method is used as a service function for export via `FlameBase.to_solution_array`. - Derived classes set default values for *domain* and *other*, where - defaults describe flow domain and essential non-thermodynamic solution - components of the configuration, respectively. An alternative *domain* - (e.g. inlet, outlet, etc.), can be specified either by name or the - corresponding `Domain1D` object itself. + Derived classes call this function with the flow domain as the ``domain`` and a + list of essential non-thermodynamic solution components of the configuration as + the ``components``. A different domain (for example, inlet or outlet) can be + specified either by name or as the corresponding Domain1D object itself. """ idom = self.domain_index(domain) dom = self.domains[idom] @@ -998,12 +994,12 @@ cdef class Sim1D: def restore_data(self, domain, states, other_cols, meta): """ - Restore a *domain* from underlying data. Method is used as + Restore a ``domain`` from underlying data. This method is used as a service function for import via `FlameBase.from_solution_array`. - Derived classes set default values for *domain* and *other*, where + Derived classes set default values for ``domain`` and ``other``, where defaults describe flow domain and essential non-thermodynamic solution - components of the configuration, respectively. An alternative *domain* + components of the configuration, respectively. An alternative ``domain`` (e.g. inlet, outlet, etc.), can be specified either by name or the corresponding Domain1D object itself. """ @@ -1354,7 +1350,7 @@ cdef class Sim1D: def set_grid_min(self, dz, domain=None): """ - Set the minimum grid spacing on *domain*. If *domain* is None, then + Set the minimum grid spacing on ``domain``. If ``domain`` is `None`, then set the grid spacing for all domains. """ if domain is None: diff --git a/interfaces/cython/cantera/reaction.pyx b/interfaces/cython/cantera/reaction.pyx index ae25faa160..c5bf12dfa8 100644 --- a/interfaces/cython/cantera/reaction.pyx +++ b/interfaces/cython/cantera/reaction.pyx @@ -194,7 +194,7 @@ cdef class ArrheniusRate(ArrheniusTypeRate): .. math:: - k_f = A T^b \exp{-\tfrac{E}{RT}} + k_f = A T^b \exp(-\tfrac{E}{RT}) where ``A`` is the `pre_exponential_factor`, ``b`` is the `temperature_exponent`, and ``Ea`` is the `activation_energy`. @@ -277,7 +277,7 @@ cdef class TwoTempPlasmaRate(ArrheniusTypeRate): .. math:: - k_f = A T_e^b \exp{-\tfrac{E_{a,g}}{RT}} \exp{-\tfrac{E_{a,e}}{RT_e}} + k_f = A T_e^b \exp(-\tfrac{E_{a,g}}{RT}) \exp(-\tfrac{E_{a,e}}{RT_e}) where :math:`A` is the `pre_exponential_factor`, :math:`b` is the `temperature_exponent`, :math:`E_{a,g}` is the `activation_energy`, and @@ -751,7 +751,7 @@ cdef class Reaction: _has_legacy = False _hybrid = False # indicate whether legacy implementations are separate or merged - def __cinit__(self, reactants="", products="", rate=None, *, legacy=False, + def __cinit__(self, reactants=None, products=None, rate=None, *, legacy=False, init=True, **kwargs): if init: rxn_type = self._reaction_type @@ -1202,8 +1202,8 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `PlogReaction` class. Replaced by `Reaction.rate.rates` for reactions where - the rate is a `PlogRate`. + `PlogReaction` class. Replaced by ``Reaction.rate.rates`` for reactions + where the rate is a `PlogRate`. """ def __get__(self): if isinstance(self.rate, PlogRate): @@ -1227,7 +1227,7 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.temperature_range[0]` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.temperature_range[0]`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1246,7 +1246,7 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.temperature_range[1]` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.temperature_range[1]`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1265,7 +1265,7 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.pressure_range[0]` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.pressure_range[0]`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1284,7 +1284,7 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.pressure_range[1]` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.pressure_range[1]`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1322,7 +1322,7 @@ cdef class Reaction: .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.n_temperature` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.n_temperature`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1337,11 +1337,11 @@ cdef class Reaction: property coeffs: """ - 2D array of Chebyshev coefficients of size `(n_temperature, n_pressure)`. + 2D array of Chebyshev coefficients of size ``(n_temperature, n_pressure)``. .. deprecated:: 2.6 This property is for temporary backwards-compatibility with the deprecated - `ChebyshevReaction` class. Replaced by `Reaction.rate.data` + `ChebyshevReaction` class. Replaced by ``Reaction.rate.data`` for reactions where the rate is a a `ChebyshevRate`. """ def __get__(self): @@ -1446,7 +1446,7 @@ cdef class Arrhenius: .. math:: - k_f = A T^b \exp{-\tfrac{E}{RT}} + k_f = A T^b \exp(-\tfrac{E}{RT}) where ``A`` is the `pre_exponential_factor`, ``b`` is the `temperature_exponent`, and ``E`` is the `activation_energy`. @@ -1644,7 +1644,6 @@ cdef class ThreeBodyReaction(ElementaryReaction): rxn = ThreeBodyReaction( equation="2 O + M <=> O2 + M", - type="three-body", rate={"A": 1.2e+17, "b": -1.0, "Ea": 0.0}, efficiencies={"H2": 2.4, "H2O": 15.4, "AR": 0.83}, kinetics=gas) @@ -1675,7 +1674,7 @@ cdef class ThreeBodyReaction(ElementaryReaction): return &(self.cxx_threebody2().third_body) return (self.cxx_threebody().thirdBody().get()) - def __init__(self, reactants="", products="", rate=None, *, equation=None, + def __init__(self, reactants=None, products=None, rate=None, *, equation=None, efficiencies=None, Kinetics kinetics=None, legacy=False, init=True, **kwargs): @@ -1851,17 +1850,16 @@ cdef class FalloffReaction(Reaction): rxn = FalloffReaction( equation="2 OH (+ M) <=> H2O2 (+ M)", - type="falloff", rate=ct.TroeRate(low=ct.Arrhenius(2.3e+12, -0.9, -7112800.0), high=ct.Arrhenius(7.4e+10, -0.37, 0), - data=[0.7346, 94.0, 1756.0, 5182.0]) + falloff_coeffs=[0.7346, 94.0, 1756.0, 5182.0]), efficiencies={"AR": 0.7, "H2": 2.0, "H2O": 6.0}, kinetics=gas) The YAML description corresponding to this reaction is:: equation: 2 OH (+ M) <=> H2O2 (+ M) # Reaction 3 - type: falloff-legacy + type: falloff low-P-rate-constant: {A: 2.3e+12, b: -0.9, Ea: -1700.0 cal/mol} high-P-rate-constant: {A: 7.4e+10, b: -0.37, Ea: 0.0 cal/mol} Troe: {A: 0.7346, T3: 94.0, T1: 1756.0, T2: 5182.0} @@ -1886,7 +1884,7 @@ cdef class FalloffReaction(Reaction): return &(self.cxx_object2().third_body) return (self.cxx_object().thirdBody().get()) - def __init__(self, reactants="", products="", rate=None, *, equation=None, + def __init__(self, reactants=None, products=None, rate=None, *, equation=None, efficiencies=None, Kinetics kinetics=None, init=True, legacy=False, **kwargs): @@ -2089,8 +2087,8 @@ cdef class PlogReaction(Reaction): raise AttributeError("Incorrect accessor for legacy implementation") return self.reaction - def __init__(self, equation=None, rate=None, Kinetics kinetics=None, - init=True, **kwargs): + def __init__(self, reactants=None, products=None, rate=None, *, equation=None, + Kinetics kinetics=None, init=True, **kwargs): if init and equation and kinetics: rxn_type = self._reaction_type + "-legacy" @@ -2204,8 +2202,8 @@ cdef class ChebyshevReaction(Reaction): cdef CxxChebyshevReaction2* cxx_object2(self): return self.reaction - def __init__(self, equation=None, rate=None, Kinetics kinetics=None, - init=True, **kwargs): + def __init__(self, reactants=None, products=None, rate=None, *, equation=None, + Kinetics kinetics=None, init=True, **kwargs): if init and equation and kinetics: warnings.warn("Class 'ChebyshevReaction' to be removed after Cantera 2.6.\n" diff --git a/interfaces/cython/cantera/reactionpath.pyx b/interfaces/cython/cantera/reactionpath.pyx index d23f178984..0cce9fafbb 100644 --- a/interfaces/cython/cantera/reactionpath.pyx +++ b/interfaces/cython/cantera/reactionpath.pyx @@ -12,9 +12,9 @@ cdef class ReactionPathDiagram: def __init__(self, Kinetics kin, str element): """ - Create a reaction path diagram for the fluxes of the element *element* - according the the net reaction rates determined by the Kinetics object - *kin*. + Create a reaction path diagram for the fluxes of the element ``element`` + according the the net reaction rates determined by the `Kinetics` object + ``kin``. """ self.kinetics = kin self.builder.init(deref(self._log), deref(kin.kinetics)) @@ -158,7 +158,7 @@ cdef class ReactionPathDiagram: def write_dot(self, filename): """ Write the reaction path diagram formatted for use by Graphviz's 'dot' - program to the file named *filename*. + program to the file named ``filename``. """ Path(filename).write_text(self.get_dot()) diff --git a/interfaces/cython/cantera/reactor.pyx b/interfaces/cython/cantera/reactor.pyx index a18a107992..a9caf4f517 100644 --- a/interfaces/cython/cantera/reactor.pyx +++ b/interfaces/cython/cantera/reactor.pyx @@ -19,7 +19,6 @@ cdef class ReactorBase: def __cinit__(self, *args, **kwargs): self.rbase = newReactor(stringify(self.reactor_type)) - # The signature of this function causes warnings for Sphinx documentation def __init__(self, ThermoPhase contents=None, name=None, *, volume=None): self._weakref_proxy = _WeakrefProxy() self._inlets = [] @@ -44,7 +43,7 @@ cdef class ReactorBase: def insert(self, _SolutionBase solution): """ - Set *solution* to be the object used to compute thermodynamic + Set ``solution`` to be the object used to compute thermodynamic properties and kinetic rates for this reactor. """ self._thermo = solution @@ -129,21 +128,21 @@ cdef class ReactorBase: def _add_inlet(self, inlet): """ - Store a reference to *inlet* to prevent it from being prematurely + Store a reference to ``inlet`` to prevent it from being prematurely garbage collected. """ self._inlets.append(inlet) def _add_outlet(self, outlet): """ - Store a reference to *outlet* to prevent it from being prematurely + Store a reference to ``outlet`` to prevent it from being prematurely garbage collected. """ self._outlets.append(outlet) def _add_wall(self, wall): """ - Store a reference to *wall* to prevent it from being prematurely + Store a reference to ``wall`` to prevent it from being prematurely garbage collected. """ self._walls.append(wall) @@ -167,7 +166,6 @@ cdef class Reactor(ReactorBase): def __cinit__(self, *args, **kwargs): self.reactor = (self.rbase) - # The signature of this function causes warnings for Sphinx documentation def __init__(self, contents=None, *, name=None, energy='on', **kwargs): """ :param contents: @@ -224,8 +222,8 @@ cdef class Reactor(ReactorBase): property chemistry_enabled: """ - *True* when the reactor composition is allowed to change due to - chemical reactions in this reactor. When this is *False*, the + `True` when the reactor composition is allowed to change due to + chemical reactions in this reactor. When this is `False`, the reactor composition is held constant. """ def __get__(self): @@ -236,8 +234,8 @@ cdef class Reactor(ReactorBase): property energy_enabled: """ - *True* when the energy equation is being solved for this reactor. - When this is *False*, the reactor temperature is held constant. + `True` when the energy equation is being solved for this reactor. + When this is `False`, the reactor temperature is held constant. """ def __get__(self): return self.reactor.energyEnabled() @@ -248,7 +246,7 @@ cdef class Reactor(ReactorBase): def add_sensitivity_reaction(self, m): """ Specifies that the sensitivity of the state variables with respect to - reaction *m* should be computed. *m* is the 0-based reaction index. + reaction ``m`` should be computed. ``m`` is the 0-based reaction index. The reactor must be part of a network first. Specifying the same reaction more than one time raises an exception. """ @@ -257,20 +255,18 @@ cdef class Reactor(ReactorBase): def add_sensitivity_species_enthalpy(self, k): """ Specifies that the sensitivity of the state variables with respect to - species *k* should be computed. The reactor must be part of a network + species ``k`` should be computed. The reactor must be part of a network first. """ self.reactor.addSensitivitySpeciesEnthalpy(self.thermo.species_index(k)) def component_index(self, name): """ - Returns the index of the component named *name* in the system. This - determines the (relative) index of the component in the vector of - sensitivity coefficients. *name* is either a species name or the name of - a reactor state variable, e.g. 'int_energy', 'temperature', depending on - the reactor's equations. + Returns the index of the component named ``name`` in the system. This determines + the index of the component in the vector of sensitivity coefficients. ``name`` + is either a species name or the name of a reactor state variable, for example + ``'int_energy'`` or ``'temperature'``, depending on the reactor's equations. """ - k = self.reactor.componentIndex(stringify(name)) if k == CxxNpos: raise IndexError('No such component: {!r}'.format(name)) @@ -278,7 +274,7 @@ cdef class Reactor(ReactorBase): def component_name(self, int i): """ - Returns the name of the component with index *i* within the array of + Returns the name of the component with index ``i`` within the array of variables returned by `get_state`. This is the inverse of `component_index`. """ @@ -329,8 +325,8 @@ cdef class Reactor(ReactorBase): def set_advance_limit(self, name, limit): """ - Limit absolute change of component *name* during `ReactorNet.advance`. - (positive *limit* values are considered; negative values disable a + Limit absolute change of component ``name`` during `ReactorNet.advance`. + (positive ``limit`` values are considered; negative values disable a previously set advance limit for a solution component). Note that limits are disabled by default (with individual values set to -1.). """ @@ -536,7 +532,7 @@ cdef class ExtensibleReactor(Reactor): def restore_surface_state(self, n): """ - Set the state of the thermo object for surface *n* to correspond to the + Set the state of the thermo object for surface ``n`` to correspond to the state of that surface """ self.accessor.restoreSurfaceState(n) @@ -641,7 +637,7 @@ cdef class ReactorSurface: def add_sensitivity_reaction(self, int m): """ Specifies that the sensitivity of the state variables with respect to - reaction *m* should be computed. *m* is the 0-based reaction index. + reaction ``m`` should be computed. ``m`` is the 0-based reaction index. The Surface must be installed on a reactor and part of a network first. """ self.surface.addSensitivityReaction(m) @@ -655,7 +651,6 @@ cdef class WallBase: def __cinit__(self, *args, **kwargs): self.wall = newWall(stringify(self.wall_type)) - # The signature of this function causes warnings for Sphinx documentation def __init__(self, left, right, *, name=None, A=None, K=None, U=None, Q=None, velocity=None): """ @@ -680,9 +675,6 @@ cdef class WallBase: Wall velocity function :math:`v_0(t)` [m/s]. Default: :math:`v_0(t) = 0.0`. """ - self.left_surface = WallSurface(self, 0) - self.right_surface = WallSurface(self, 1) - self._velocity_func = None self._heat_flux_func = None @@ -722,16 +714,6 @@ cdef class WallBase: def __get__(self): return pystr(self.wall.type()) - property left: - """ The left surface of this wall. """ - def __get__(self): - return self.left_surface - - property right: - """ The right surface of this wall. """ - def __get__(self): - return self.right_surface - property area: """ The wall area [m^2]. """ def __get__(self): @@ -742,14 +724,14 @@ cdef class WallBase: def vdot(self, double t): """ The rate of volumetric change [m^3/s] associated with the wall - at time *t*. A positive value corresponds to the left-hand reactor + at time ``t``. A positive value corresponds to the left-hand reactor volume increasing, and the right-hand reactor volume decreasing. """ return self.wall.vdot(t) def qdot(self, double t): """ - Total heat flux [W] through the wall at time *t*. A positive value + Total heat flux [W] through the wall at time ``t``. A positive value corresponds to heat flowing from the left-hand reactor to the right-hand one. """ @@ -853,7 +835,6 @@ cdef class FlowDevice: def __cinit__(self, *args, **kwargs): self.dev = newFlowDevice(stringify(self.flowdevice_type)) - # The signature of this function causes warnings for Sphinx documentation def __init__(self, upstream, downstream, *, name=None): assert self.dev != NULL self._rate_func = None @@ -877,7 +858,7 @@ cdef class FlowDevice: def _install(self, ReactorBase upstream, ReactorBase downstream): """ - Install the device between the *upstream* (source) and *downstream* + Install the device between the ``upstream`` (source) and ``downstream`` (destination) reactors or reservoirs. """ upstream._add_outlet(self) @@ -959,7 +940,6 @@ cdef class MassFlowController(FlowDevice): """ flowdevice_type = "MassFlowController" - # The signature of this function causes warnings for Sphinx documentation def __init__(self, upstream, downstream, *, name=None, mdot=1.): super().__init__(upstream, downstream, name=name) self.mass_flow_rate = mdot @@ -1034,7 +1014,6 @@ cdef class Valve(FlowDevice): """ flowdevice_type = "Valve" - # The signature of this function causes warnings for Sphinx documentation def __init__(self, upstream, downstream, *, name=None, K=1.): super().__init__(upstream, downstream, name=name) if isinstance(K, _numbers.Real): @@ -1078,7 +1057,6 @@ cdef class PressureController(FlowDevice): """ flowdevice_type = "PressureController" - # The signature of this function causes warnings for Sphinx documentation def __init__(self, upstream, downstream, *, name=None, master=None, K=1.): super().__init__(upstream, downstream, name=name) if master is not None: @@ -1134,8 +1112,8 @@ cdef class ReactorNet: def advance(self, double t, pybool apply_limit=True): """ Advance the state of the reactor network in time from the current time - towards time *t* [s], taking as many integrator timesteps as necessary. - If *apply_limit* is true and an advance limit is specified, the reactor + towards time ``t`` in seconds, taking as many integrator time steps as necessary. + If ``apply_limit`` is true and an advance limit is specified, the reactor state at the end of the timestep is estimated prior to advancing. If the difference exceed limits, the end time is reduced by half until the projected end state remains within specified limits. @@ -1246,8 +1224,8 @@ cdef class ReactorNet: property verbose: """ - If *True*, verbose debug information will be printed during - integration. The default is *False*. + If `True`, verbose debug information will be printed during + integration. The default is `False`. """ def __get__(self): return pybool(self.net.verbose()) @@ -1256,11 +1234,11 @@ cdef class ReactorNet: def global_component_index(self, name, int reactor): """ - Returns the index of a component named *name* of a reactor with index - *reactor* within the global state vector. I.e. this determines the - (absolute) index of the component, where *reactor* is the index of the - reactor that holds the component. *name* is either a species name or the - name of a reactor state variable, e.g. 'int_energy', 'temperature', etc. + Returns the index of a component named ``name`` of a reactor with index + ``reactor`` within the global state vector. That is, this determines the + absolute index of the component, where ``reactor`` is the index of the + reactor that holds the component. ``name`` is either a species name or the + name of a reactor state variable, for example, ``'int_energy'``, ``'temperature'``, etc. depending on the reactor's equations. """ return self.net.globalComponentIndex(stringify(name), reactor) @@ -1275,11 +1253,11 @@ cdef class ReactorNet: def sensitivity(self, component, int p, int r=0): """ - Returns the sensitivity of the solution variable *component* in - reactor *r* with respect to the parameter *p*. *component* can be a + Returns the sensitivity of the solution variable ``component`` in + reactor ``r`` with respect to the parameter ``p``. ``component`` can be a string or an integer. See `component_index` and `sensitivities` to determine the integer index for the variables and the definition of the - resulting sensitivity coefficient. If it is not given, *r* defaults to + resulting sensitivity coefficient. If it is not given, ``r`` defaults to the first reactor. Returns an empty array until the first time step is taken. """ @@ -1329,7 +1307,7 @@ cdef class ReactorNet: def sensitivity_parameter_name(self, int p): """ - Name of the sensitivity parameter with index *p*. + Name of the sensitivity parameter with index ``p``. """ return pystr(self.net.sensitivityParameterName(p)) diff --git a/interfaces/cython/cantera/thermo.pyx b/interfaces/cython/cantera/thermo.pyx index 7e344d2a83..de8791fe69 100644 --- a/interfaces/cython/cantera/thermo.pyx +++ b/interfaces/cython/cantera/thermo.pyx @@ -150,7 +150,7 @@ cdef class Species: """ Create a list of Species objects from all of the species defined in a YAML, CTI or XML file. For YAML files, return species from the section - *section*. + ``section``. Directories on Cantera's input file path will be searched for the specified file. @@ -188,7 +188,7 @@ cdef class Species: def list_from_file(filename, section="species"): """ Create a list of Species objects from all of the species defined in the section - *section* of a YAML file. Directories on Cantera's input file path will be + ``section`` of a YAML file. Directories on Cantera's input file path will be searched for the specified file. """ root = AnyMapFromYamlFile(stringify(filename)) @@ -362,7 +362,6 @@ cdef class ThermoPhase(_SolutionBase): as a base class for classes `Solution` and `Interface`. """ - # The signature of this function causes warnings for Sphinx documentation def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) if 'source' not in kwargs: @@ -491,7 +490,7 @@ cdef class ThermoPhase(_SolutionBase): int log_level=0): """ Set to a state of chemical equilibrium holding property pair - *XY* constant. + ``XY`` constant. :param XY: A two-letter string, which must be one of the set:: @@ -538,7 +537,7 @@ cdef class ThermoPhase(_SolutionBase): cpdef int element_index(self, element) except *: """ - The index of element *element*, which may be specified as a string or + The index of element ``element``, which may be specified as a string or an integer. In the latter case, the index is checked for validity and returned. If no such element is present, an exception is thrown. """ @@ -556,7 +555,7 @@ cdef class ThermoPhase(_SolutionBase): return index def element_name(self, m): - """Name of the element with index *m*.""" + """Name of the element with index ``m``.""" return pystr(self.thermo.elementName(m)) property element_names: @@ -565,7 +564,7 @@ cdef class ThermoPhase(_SolutionBase): return [self.element_name(m) for m in range(self.n_elements)] def atomic_weight(self, m): - """Atomic weight [kg/kmol] of element *m*""" + """Atomic weight [kg/kmol] of element ``m``""" return self.thermo.atomicWeight(self.element_index(m)) property atomic_weights: @@ -586,7 +585,7 @@ cdef class ThermoPhase(_SolutionBase): return self._selected_species.size or self.n_species def species_name(self, k): - """Name of the species with index *k*.""" + """Name of the species with index ``k``.""" return pystr(self.thermo.speciesName(k)) property species_names: @@ -600,7 +599,7 @@ cdef class ThermoPhase(_SolutionBase): cpdef int species_index(self, species) except *: """ - The index of species *species*, which may be specified as a string or + The index of species ``species``, which may be specified as a string or an integer. In the latter case, the index is checked for validity and returned. If no such species is present, an exception is thrown. """ @@ -626,8 +625,8 @@ cdef class ThermoPhase(_SolutionBase): def species(self, k=None): """ - Return the `Species` object for species *k*, where *k* is either the - species index or the species name. If *k* is not specified, a list of + Return the `Species` object for species ``k``, where ``k`` is either the + species index or the species name. If ``k`` is not specified, a list of all species objects is returned. Changes to this object do not affect the `ThermoPhase` or `Solution` object until the `modify_species` function is called. @@ -668,13 +667,13 @@ cdef class ThermoPhase(_SolutionBase): def add_species_alias(self, name, alias): """ - Add the alternate species name *alias* for an original species *name*. + Add the alternate species name ``alias`` for an original species ``name``. """ self.thermo.addSpeciesAlias(stringify(name), stringify(alias)) def find_isomers(self, comp): """ - Find species/isomers matching a composition specified by *comp*. + Find species/isomers matching a composition specified by ``comp``. """ if isinstance(comp, dict): @@ -688,7 +687,7 @@ cdef class ThermoPhase(_SolutionBase): def n_atoms(self, species, element): """ - Number of atoms of element *element* in species *species*. The element + Number of atoms of element ``element`` in species ``species``. The element and species may be specified by name or by index. >>> phase.n_atoms('CH4','H') @@ -848,7 +847,7 @@ cdef class ThermoPhase(_SolutionBase): def set_mixture_fraction(self, mixture_fraction, fuel, oxidizer, basis='mole'): """ Set the composition to a mixture of ``fuel`` and ``oxidizer`` at the - specified mixture fraction *mixture_fraction* (kg fuel / kg mixture), holding + specified mixture fraction ``mixture_fraction`` (kg fuel / kg mixture), holding temperature and pressure constant. 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 @@ -1026,8 +1025,8 @@ cdef class ThermoPhase(_SolutionBase): def set_unnormalized_mass_fractions(self, Y): """ - Set the mass fractions without normalizing to force sum(Y) == 1.0. - Useful primarily when calculating derivatives with respect to Y[k] by + Set the mass fractions without normalizing to force ``sum(Y) == 1.0``. + Useful primarily when calculating derivatives with respect to ``Y[k]`` by finite difference. """ cdef np.ndarray[np.double_t, ndim=1] data @@ -1040,8 +1039,8 @@ cdef class ThermoPhase(_SolutionBase): def set_unnormalized_mole_fractions(self, X): """ - Set the mole fractions without normalizing to force sum(X) == 1.0. - Useful primarily when calculating derivatives with respect to X[k] + Set the mole fractions without normalizing to force ``sum(X) == 1.0``. + Useful primarily when calculating derivatives with respect to ``X[k]`` by finite difference. """ cdef np.ndarray[np.double_t, ndim=1] data diff --git a/interfaces/cython/cantera/transport.pyx b/interfaces/cython/cantera/transport.pyx index 932197f558..83b9c4c328 100644 --- a/interfaces/cython/cantera/transport.pyx +++ b/interfaces/cython/cantera/transport.pyx @@ -165,7 +165,6 @@ cdef class Transport(_SolutionBase): Not all transport properties are implemented in all transport models. """ - # The signature of this function causes warnings for Sphinx documentation def __init__(self, *args, **kwargs): if self.transport == NULL and kwargs.get("init", True): # @todo ... after removal of CTI/XML, this should be handled by base.pyx @@ -280,27 +279,27 @@ cdef class Transport(_SolutionBase): def get_viscosity_polynomial(self, i): """Get the polynomial fit to the logarithm of temperature for - the viscosity of species i.""" + the viscosity of species ``i``.""" n_values = 4 if self.transport.CKMode() else 5 return get_transport_polynomial(self, tran_getViscosityPolynomial, i, n_values) def get_thermal_conductivity_polynomial(self, i): """Get the polynomial fit to the logarithm of temperature for - the thermal conductivity of species i.""" + the thermal conductivity of species ``i``.""" n_values = 4 if self.transport.CKMode() else 5 return get_transport_polynomial(self, tran_getConductivityPolynomial, i, n_values) def get_binary_diff_coeffs_polynomial(self, i, j): """Get the polynomial fit to the logarithm of temperature for - the binary diffusion coefficient of species i and j.""" + the binary diffusion coefficient of species ``i`` and ``j``.""" n_values = 4 if self.transport.CKMode() else 5 return get_binary_transport_polynomial(self, tran_getBinDiffusivityPolynomial, i, j, n_values) def get_collision_integral_polynomials(self, i, j): """Get the polynomial fit to the logarithm of temperature for - the collision integral of species i and j.""" + the collision integral of species ``i`` and ``j``.""" n_values = 7 if self.transport.CKMode() else 9 cdef np.ndarray[np.double_t, ndim=1] adata = np.empty(n_values) cdef np.ndarray[np.double_t, ndim=1] bdata = np.empty(n_values) @@ -311,7 +310,7 @@ cdef class Transport(_SolutionBase): def set_viscosity_polynomial(self, i, values): """Set the polynomial fit to the logarithm of temperature for - the viscosity of species i.""" + the viscosity of species ``i``.""" n_values = 4 if self.transport.CKMode() else 5 if len(values) != n_values: raise ValueError( @@ -323,7 +322,7 @@ cdef class Transport(_SolutionBase): def set_thermal_conductivity_polynomial(self, i, values): """Set the polynomial fit to the logarithm of temperature for - the thermal conductivity of species i.""" + the thermal conductivity of species ``i``.""" n_values = 4 if self.transport.CKMode() else 5 if len(values) != n_values: raise ValueError( @@ -335,7 +334,7 @@ cdef class Transport(_SolutionBase): def set_binary_diff_coeffs_polynomial(self, i, j, values): """Set the polynomial fit to the logarithm of temperature for - the binary diffusion coefficient of species i and j.""" + the binary diffusion coefficient of species ``i`` and ``j``.""" n_values = 4 if self.transport.CKMode() else 5 if len(values) != n_values: raise ValueError( @@ -348,7 +347,7 @@ cdef class Transport(_SolutionBase): def set_collision_integral_polynomial(self, i, j, avalues, bvalues, cvalues, actualT=True): """Get the polynomial fit to the logarithm of temperature for - the collision integral of species i and j.""" + the collision integral of species ``i`` and ``j``.""" n_values = 7 if self.transport.CKMode() else 9 if len(avalues) != n_values: raise ValueError( @@ -379,7 +378,6 @@ cdef class DustyGasTransport(Transport): is handled. The viscosity, thermal conductivity, and thermal diffusion coefficients are not implemented. """ - # The signature of this function causes warnings for Sphinx documentation def __init__(self, *args, **kwargs): self.base.setTransport(newTransport(self.thermo, stringify("DustyGas"))) self.transport = self.base.transport().get() diff --git a/interfaces/cython/cantera/utils.pyx b/interfaces/cython/cantera/utils.pyx index 2da49172bf..0298d3f472 100644 --- a/interfaces/cython/cantera/utils.pyx +++ b/interfaces/cython/cantera/utils.pyx @@ -56,7 +56,7 @@ def appdelete(): def use_sparse(sparse=True): """ Enable sparse output using `scipy.sparse`. Sparse output requires a working - `scipy` installation. Use pip or conda to install `scipy` to enable this method. + *SciPy* installation. Use pip or conda to install ``scipy`` to enable this method. """ global _USE_SPARSE if sparse and isinstance(_scipy_sparse, ImportError):