diff --git a/doc/sphinx/python/importing.rst b/doc/sphinx/python/importing.rst index 4f31bf419..8eef865ef 100644 --- a/doc/sphinx/python/importing.rst +++ b/doc/sphinx/python/importing.rst @@ -20,6 +20,8 @@ thermodynamic, chemical kinetic, and (optionally) transport properties. .. autoclass:: DustyGas(infile, name='') +.. _sec-python-purefluid: + Pure Fluid Phases ----------------- diff --git a/doc/sphinx/python/index.md b/doc/sphinx/python/index.md new file mode 100644 index 000000000..abc270913 --- /dev/null +++ b/doc/sphinx/python/index.md @@ -0,0 +1,146 @@ +```{py:currentmodule} cantera +``` + +(sec-python-documentation)= + +# Python Module Documentation + +## [Objects Representing Phases](./importing) + +The most frequently used class in Cantera is the {py:class}`Solution`. It can represent +a mixture of gases, a liquid solution, or a solid solution and provides access to the +solution's thermodynamic, kinetic, and transport properties. The {py:class}`Interface` +class represents surfaces formed by two adjacent phases or edges where three phases +meet. Several [special constructors](sec-python-purefluid) are provided to instantiate +{py:class}`Solution` objects that implement pure fluid equations of state for certain +substances. + +The {py:class}`Quantity` class represents a specific quantity (mass) of a +{py:class}`Solution`. It provides methods for accessing the extensive properties of the +quantity and computing the state resulting from mixing two substances. + +The {py:class}`SolutionArray` class provides a convenient interface for representing a +multidimensional array of states and accessing properties of those states as arrays. + +## [Thermodynamic Properties](./thermo) + +Class {py:class}`ThermoPhase` is one of the base classes for {py:class}`Solution` +objects. It represents the intensive thermodynamic state using one of the [phase +thermodynamic models](/reference/thermo/phase-thermo) implemented by Cantera and +provides methods for computing thermodynamic properties. + +A phase is composed of a number of {py:class}`Species` objects. Each species has a +{py:class}`SpeciesThermo` object that implements a particular [species thermodynamic +model](/reference/thermo/species-thermo). {py:class}`Element` objects can be used to +access information about the elements comprising each species or to define custom +isotopes. + +The {py:class}`Mixture` class provides an interface for computing equilibrium properties +of mixtures composed of multiple phases. + +## [Chemical Kinetics](./kinetics) + +Class {py:class}`Kinetics` is a base class of {py:class}`Solution` that provides access +to [reaction rates](/reference/kinetics/reaction-rates) of progress, species production +rates, and other quantities pertaining to a reaction mechanism. +{py:class}`InterfaceKinetics` provides this information for {py:class}`Interface` +objects. + +A reaction mechanism consists of a set of {py:class}`Reaction` objects. The +{py:class}`Reaction` object specifies the reactants and products of the reaction and +has a {py:class}`ReactionRate` object that handles the evaluation of the rate constant +as a function of the mixture composition, using one of the [rate +parameterizations](/reference/kinetics/rate-constants) implemented by Cantera or a +user-defined rate implemented using the {py:class}`ExtensibleRate` class. + +The {py:class}`ReactionPathDiagram` class can be used to analyze reaction pathways. + +## [Transport Properties](./transport) + +Class {py:class}`Transport` is a base class of {py:class}`Solution` that provides access +to transport properties such as viscosity and species diffusivities, using one of the +available [transport models](sec-phase-transport-models). The +{py:class}`DustyGasTransport` provides a special transport model applicable to porous +media. Species properties needed to compute transport properties are handled by the +{py:class}`GasTransportData` class. + +## [Zero-Dimensional Reactor Networks](./zerodim) + +A reactor network consists of one or more interconnected reactors. Several reactor types +are implemented by [classes derived from `Reactor`](sec-python-reactors), each with its +own set of [governing equations](sec-homogenous-reactor-types). + +Reactors can be connected to each other and upstream or downstream +{py:class}`Reservoir`s using {py:class}`Valve`s, {py:class}`MassFlowController`s, +{py:class}`PressureController`s, and {py:class}`Wall`s, which introduce [additional +terms to the governing equations](sec-reactor-interactions). Heterogeneous reactions are +handled by {py:class}`ReactorSurface`. User-defined reactor governing equations can be +implemented using the {py:class}`ExtensibleReactor` class or any of the classes derived +from it. + +Time integration of reactor networks is handled by the {py:class}`ReactorNet` class. For +[certain types of networks](sec-reactor-preconditioning), integration can be accelerated +by using the {py:class}`AdaptivePreconditioner` class. + +## [One-dimensional Reacting Flows](./onedim) + +The main way of setting up a [1D simulation](/reference/onedim/index) in Cantera is +through one of the specializations of the {py:class}`FlameBase` class: +{py:class}`FreeFlame`, {py:class}`BurnerFlame`, {py:class}`CounterflowDiffusionFlame`, +{py:class}`CounterflowPremixedFlame`, {py:class}`CounterflowTwinPremixedFlame`, or +{py:class}`ImpingingJet`. These classes all consist of a [flow +domain](sec-python-flow-domains) with two [boundaries](sec-python-boundary-domains) +defining inlet/outlet boundary conditions. + +## [Mechanism Conversion](./scripts) + +Cantera includes modules implementing conversion of mechanisms between the YAML and +Chemkin formats, conversion from the LXCat format, and conversion from the legacy CTI +and CTML (XML) formats that were used prior to Cantera 3.0. The preferred interfaces for +these conversions are the executable scripts [`ck2yaml`](/yaml/ck2yaml), +[`yaml2ck`](/yaml/yaml2ck), [`lxcat2yaml`](/yaml/lxcat2yaml), +[`cti2yaml`](/yaml/cti2yaml), and [`ctml2yaml`](/yaml/ctml2yaml). + +## [Python Interface With Units](./units.rst) + +This subpackage provides an alternative interface to thermodynamic properties where +physical units are associated with all values, using the +[pint](https://pint.readthedocs.io/en/stable/) library. This capability is implemented by the {py:class}`with_units.Solution` and {py:class}`with_units.PureFluid` classes. + +## [Physical Constants](./constants.rst) + +Cantera provides definitions for a number of frequently used physical constants. The +values are consistent with the 2018 CODATA recommendations. + +## [Utilities](./utilities.rst) + +Classes {py:class}`AnyMap` and {py:class}`YamlWriter` provide functionality for +interacting with input data defined using Cantera's [YAML input format](/yaml/index). +Classes {py:class}`UnitSystem` and {py:class}`Units` are used for expressing dimensional +quantities in input files. + +A number of [global functions](sec-python-global-funcs) are provided for managing +locations where Cantera looks for data files, for setting how Cantera handles warnings +and errors, and how some transitional/legacy features are handled. + +The {py:func}`extension` function is used as a decorator for implementations of +{py:class}`ExtensibleRate` to allow user-defined rate types to be specified from YAML +input files. + +Classes {py:class}`CanteraError` and {py:class}`ThermoModelMethodError` are raised for +types of errors that are not mapped onto a built-in Python exception type. + +```{toctree} +:hidden: + +importing +thermo +kinetics +transport +zerodim +onedim +scripts +units +constants +utilities +``` diff --git a/doc/sphinx/python/index.rst b/doc/sphinx/python/index.rst deleted file mode 100644 index 557445f69..000000000 --- a/doc/sphinx/python/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _sec-python-documentation: - -Python Module Documentation -=========================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - importing - thermo - kinetics - transport - zerodim - onedim - constants - units - utilities - scripts diff --git a/doc/sphinx/python/onedim.rst b/doc/sphinx/python/onedim.rst index bd14b9608..a4d11985e 100644 --- a/doc/sphinx/python/onedim.rst +++ b/doc/sphinx/python/onedim.rst @@ -36,6 +36,8 @@ ImpingingJet .. autoclass:: ImpingingJet +.. _sec-python-flow-domains: + Flow Domains ------------ @@ -47,6 +49,7 @@ AxisymmetricFlow ^^^^^^^^^^^^^^^^ .. autoclass:: AxisymmetricFlow(thermo) +.. _sec-python-boundary-domains: Boundaries ---------- diff --git a/doc/sphinx/python/utilities.rst b/doc/sphinx/python/utilities.rst index 55f3f6338..8154c394f 100644 --- a/doc/sphinx/python/utilities.rst +++ b/doc/sphinx/python/utilities.rst @@ -31,6 +31,7 @@ Units .. autoclass:: Units :no-undoc-members: +.. _sec-python-global-funcs: Global Functions ---------------- diff --git a/doc/sphinx/python/zerodim.rst b/doc/sphinx/python/zerodim.rst index fe182746e..29a3d4d8c 100644 --- a/doc/sphinx/python/zerodim.rst +++ b/doc/sphinx/python/zerodim.rst @@ -31,6 +31,8 @@ Reactor Networks .. autoclass:: ReactorNet +.. _sec-python-reactors: + Reactors -------- diff --git a/doc/sphinx/reference/reactors/index.md b/doc/sphinx/reference/reactors/index.md index 0a1ca8627..4403f452e 100644 --- a/doc/sphinx/reference/reactors/index.md +++ b/doc/sphinx/reference/reactors/index.md @@ -9,6 +9,7 @@ devices representing mass flow, heat transfer, and moving walls. The system is g unsteady -- that is, all states are functions of time. In particular, transient state changes due to chemical reactions are possible. +(sec-homogenous-reactor-types)= ## Homogeneous Reactor Types and Governing Equations A Cantera *reactor* represents the simplest form of a chemically reacting system. It @@ -128,6 +129,7 @@ Cantera uses the CVODES and IDAS solvers from the [SUNDIALS](https://computing.llnl.gov/projects/sundials) package to integrate the governing equations for the reactor network, which are a system of stiff ODEs or DAEs. +(sec-reactor-preconditioning)= ### Preconditioning Some of Cantera's reactor formulations (specifically, the