Skip to main content

# Thermodynamic Properties

- Phases

  - ThermoPhase

  - InterfacePhase

  - PureFluid

- Mixture

- Species

- Species Thermodynamic Properties

  - SpeciesThermo

  - ConstantCp

  - Mu0Poly

  - NasaPoly2

  - Nasa9PolyMultiTempRegion

  - ShomatePoly2

- Element

## Phases

These classes are used to describe the thermodynamic state of a system.

### ThermoPhase

class cantera.ThermoPhase(infile='', name='', *, origin=None, source=None, yaml=None, thermo=None, species=(), **kwargs)

  Bases: `_SolutionBase`

  ThermoPhase(*args, **kwargs)

  A phase with an equation of state.

  Class `ThermoPhase` may be used to represent the intensive thermodynamic state of a phase of matter, which might be a gas, liquid, or solid.

  Class `ThermoPhase` is not usually instantiated directly. It is used as a base class for classes `Solution` and `Interface`.

  DP

    Get/Set density [kg/m^3] and pressure [Pa].

  DPX

    Get/Set density [kg/m^3], pressure [Pa], and mole fractions.

  DPY

    Get/Set density [kg/m^3], pressure [Pa], and mass fractions.

  HP

    Get/Set enthalpy [J/kg or J/kmol] and pressure [Pa].

  HPX

    Get/Set enthalpy [J/kg or J/kmol], pressure [Pa] and mole fractions.

  HPY

    Get/Set enthalpy [J/kg or J/kmol], pressure [Pa] and mass fractions.

  P

    Pressure [Pa].

  P_sat

    Saturation pressure [Pa] at the current temperature.

  SP

    Get/Set entropy [J/kg/K or J/kmol/K] and pressure [Pa].

  SPX

    Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mole fractions.

  SPY

    Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mass fractions.

  SV

    Get/Set entropy [J/kg/K or J/kmol/K] and specific volume [m^3/kg or m^3/kmol].

  SVX

    Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m^3/kg or m^3/kmol], and mole fractions.

  SVY

    Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m^3/kg or m^3/kmol], and mass fractions.

  T

    Temperature [K].

  TD

    Get/Set temperature [K] and density [kg/m^3 or kmol/m^3].

  TDX

    Get/Set temperature [K], density [kg/m^3 or kmol/m^3], and mole fractions.

  TDY

    Get/Set temperature [K] and density [kg/m^3 or kmol/m^3], and mass fractions.

  TP

    Get/Set temperature [K] and pressure [Pa].

  TPX

    Get/Set temperature [K], pressure [Pa], and mole fractions.

  TPY

    Get/Set temperature [K], pressure [Pa], and mass fractions.

  T_sat

    Saturation temperature [K] at the current pressure.

  Te

    Get/Set electron Temperature [K].

  UV

    Get/Set internal energy [J/kg or J/kmol] and specific volume [m^3/kg or m^3/kmol].

  UVX

    Get/Set internal energy [J/kg or J/kmol], specific volume [m^3/kg or m^3/kmol], and mole fractions.

  UVY

    Get/Set internal energy [J/kg or J/kmol], specific volume [m^3/kg or m^3/kmol], and mass fractions.

  X

    Get/Set the species mole fractions. Can be set as an array, as a dictionary, or as a string. Always returns an array:

        >>> phase.X = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]
        >>> phase.X = {'H2':0.1, 'O2':0.4, 'AR':0.5}
        >>> phase.X = 'H2:0.1, O2:0.4, AR:0.5'
        >>> phase.X
        array([0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5])

  Y

    Get/Set the species mass fractions. Can be set as an array, as a dictionary, or as a string. Always returns an array:

        >>> phase.Y = [0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5]
        >>> phase.Y = {'H2':0.1, 'O2':0.4, 'AR':0.5}
        >>> phase.Y = 'H2:0.1, O2:0.4, AR:0.5'
        >>> phase.Y
        array([0.1, 0, 0, 0.4, 0, 0, 0, 0, 0.5])

  activities

    Array of nondimensional activities. Returns either molar or molal activities depending on the convention of the thermodynamic model.

  activity_coefficients

    Array of nondimensional, molar activity coefficients.

  add_species(self, Species species)

    Add a new species to this phase. Missing elements will be added automatically.

  add_species_alias(self, name, alias)

    Add the alternate species name `alias` for an original species `name`.

  atomic_weight(self, m)

    Atomic weight [kg/kmol] of element `m`

  atomic_weights

    Array of atomic weight [kg/kmol] for each element in the mixture.

  basis

    Determines whether intensive thermodynamic properties are treated on a `mass` (per kg) or `molar` (per kmol) basis. This affects the values returned by the properties `h`, `u`, `s`, `g`, `v`, `density`, `cv`, and `cp`, as well as the values used with the state-setting properties such as `HPX` and `UV`.

  case_sensitive_species_names

    Enforce case-sensitivity for look up of species names

  charges

    Array of species charges [elem. charge].

  chemical_potentials

    Array of species chemical potentials [J/kmol].

  concentrations

    Get/Set the species concentrations [kmol/m^3].

  cp

    Heat capacity at constant pressure [J/kg/K or J/kmol/K] depending on `basis`.

  cp_mass

    Specific heat capacity at constant pressure [J/kg/K].

  cp_mole

    Molar heat capacity at constant pressure [J/kmol/K].

  critical_density

    Critical density [kg/m^3 or kmol/m^3] depending on `basis`.

  critical_pressure

    Critical pressure [Pa].

  critical_temperature

    Critical temperature [K].

  cv

    Heat capacity at constant volume [J/kg/K or J/kmol/K] depending on `basis`.

  cv_mass

    Specific heat capacity at constant volume [J/kg/K].

  cv_mole

    Molar heat capacity at constant volume [J/kmol/K].

  density

    Density [kg/m^3 or kmol/m^3] depending on `basis`.

  density_mass

    (Mass) density [kg/m^3].

  density_mole

    Molar density [kmol/m^3].

  electric_potential

    Get/Set the electric potential [V] for this phase.

  electrochemical_potentials

    Array of species electrochemical potentials [J/kmol].

  electron_energy_distribution

    Electron energy distribution

  electron_energy_distribution_type

    Electron energy distribution type

  electron_energy_levels

    Electron energy levels [eV]

  element_index(self, element) → int

    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.

  element_name(self, m)

    Name of the element with index `m`.

  element_names

    A list of all the element names.

  elemental_mass_fraction(self, m)

    Get the elemental mass fraction \(Z_{\mathrm{mass},m}\) of element \(m\) as defined by:

    \[Z_{\mathrm{mass},m} = \sum_k \frac{a_{m,k} M_m}{M_k} Y_k \]

    with \(a_{m,k}\) being the number of atoms of element \(m\) in species \(k\), \(M_m\) the atomic weight of element \(m\), \(M_k\) the molecular weight of species \(k\), and \(Y_k\) the mass fraction of species \(k\):

        >>> phase.elemental_mass_fraction('H')
        1.0

    Parameters

      m – Base element, may be specified by name or by index.

  elemental_mole_fraction(self, m)

    Get the elemental mole fraction \(Z_{\mathrm{mole},m}\) of element \(m\) (the number of atoms of element m divided by the total number of atoms) as defined by:

    \[Z_{\mathrm{mole},m} = \frac{\sum_k a_{m,k} X_k} {\sum_k \sum_j a_{j,k} X_k} \]

    with \(a_{m,k}\) being the number of atoms of element \(m\) in species \(k\), \(\sum_j\) being a sum over all elements, and \(X_k\) being the mole fraction of species \(k\):

        >>> phase.elemental_mole_fraction('H')
        1.0

    Parameters

      m – Base element, may be specified by name or by index.

  enthalpy_mass

    Specific enthalpy [J/kg].

  enthalpy_mole

    Molar enthalpy [J/kmol].

  entropy_mass

    Specific entropy [J/kg/K].

  entropy_mole

    Molar entropy [J/kmol/K].

  equilibrate(self, XY, solver=u'auto', double rtol=1e-9, int max_steps=1000, int max_iter=100, int estimate_equil=0, int log_level=0)

    Set to a state of chemical equilibrium holding property pair `XY` constant.

    Parameters

      - XY –

        A two-letter string, which must be one of the set:

            ['TP','TV','HP','SP','SV','UV']

      - solver –

        Specifies the equilibrium solver to use. May be one of the following:

        - `'element_potential'` - a fast solver using the element potential method

        - `'gibbs'` - a slower but more robust Gibbs minimization solver

        - `'vcs'` - the VCS non-ideal equilibrium solver

        - `'auto'` - The element potential solver will be tried first, then if it fails the Gibbs solver will be tried.

      - rtol – The relative error tolerance.

      - max_steps – The maximum number of steps in composition to take to find a converged solution.

      - max_iter – For the Gibbs minimization solver, this specifies the number of outer iterations on T or P when some property pair other than TP is specified.

      - estimate_equil – Integer indicating whether the solver should estimate its own initial condition. If 0, the initial mole fraction vector in the `ThermoPhase` object is used as the initial condition. If 1, the initial mole fraction vector is used if the element abundances are satisfied. If -1, the initial mole fraction vector is thrown out, and an estimate is formulated.

      - log_level – Set to a value greater than 0 to write diagnostic output.

  equivalence_ratio(self, fuel=None, oxidizer=None, basis='mole', include_species=None)

    Get the equivalence ratio of the current mixture, which is a conserved quantity. Considers the oxidation of C to CO2, H to H2O and S to SO2. Other elements are assumed not to participate in oxidation (that is, N ends up as N2). If fuel and oxidizer are not specified, the equivalence ratio is computed from the available oxygen and the required oxygen for complete oxidation. The `basis` determines the composition of fuel and oxidizer: `basis='mole'` (default) means mole fractions, `basis='mass'` means mass fractions. Additionally, a list of species can be provided with `include_species`. This means that only these species are considered for the computation of the equivalence ratio. For more information, see Python example

        >>> gas.set_equivalence_ratio(0.5, fuel='CH3:0.5, CH3OH:.5, N2:0.125', oxidizer='O2:0.21, N2:0.79, NO:0.01')
        >>> gas.equivalence_ratio(fuel='CH3:0.5, CH3OH:.5, N2:0.125', oxidizer='O2:0.21, N2:0.79, NO:0.01')
        0.5

    Parameters

      - fuel – Fuel species name or mole/mass fractions as string, array, or dict.

      - oxidizer – Oxidizer species name or mole/mass fractions as a string, array, or dict.

      - basis – Determines if `fuel` and `oxidizer` are given in mole fractions (`basis="mole"`) or mass fractions (`basis="mass"`)

      - include_species – List of species names (optional). Only these species are considered for the computation of the equivalence ratio. By default, all species are considered

  find_isomers(self, comp)

    Find species/isomers matching a composition specified by `comp`.

  g

    Gibbs free energy [J/kg or J/kmol] depending on `basis`.

  gibbs_mass

    Specific Gibbs free energy [J/kg].

  gibbs_mole

    Molar Gibbs free energy [J/kmol].

  h

    Enthalpy [J/kg or J/kmol] depending on `basis`.

  has_phase_transition

    Returns true if the phase represents a substance with phase transitions

  int_energy_mass

    Specific internal energy [J/kg].

  int_energy_mole

    Molar internal energy [J/kmol].

  is_compressible

    Returns true if the density of the phase is an independent variable defining the thermodynamic state of a substance

  is_pure

    Returns true if the phase represents a pure (fixed composition) substance

  isothermal_compressibility

    Isothermal compressibility [1/Pa].

  isotropic_shape_factor

    Shape factor of isotropic-velocity distribution for electron energy

  mass_fraction_dict(self, double threshold=0.0)

    Return a dictionary giving the mass fraction for each species by name where the mass fraction is greater than `threshold`.

  max_temp

    Maximum temperature for which the thermodynamic data for the phase are valid.

  mean_electron_energy

    Mean electron energy [eV]

  mean_molecular_weight

    The mean molecular weight (molar mass) [kg/kmol].

  min_temp

    Minimum temperature for which the thermodynamic data for the phase are valid.

  mixture_fraction(self, fuel, oxidizer, basis='mole', element='Bilger')

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

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

    Parameters

      - fuel – Fuel species name or mole/mass fractions as string, array, or dict.

      - oxidizer – Oxidizer species name or mole/mass fractions as a string, array, or dict.

      - basis – Determines if `fuel` and `oxidizer` are given in mole fractions (`basis='mole'`) or mass fractions (`basis='mass'`)

      - element – Computes the mixture fraction from the specified elemental mass fraction (given by element name or element index) or as the Bilger mixture fraction (default)

  modify_species(self, k, Species species)

    Modify the thermodynamic data associated with a species. The species name, elemental composition, and type of thermo parameterization must be unchanged.

  mole_fraction_dict(self, double threshold=0.0)

    Return a dictionary giving the mole fraction for each species by name where the mole fraction is greater than `threshold`.

  molecular_weights

    Array of species molecular weights (molar masses) [kg/kmol].

  n_atoms(self, species, 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')
        4

  n_electron_energy_levels

    Number of electron energy levels

  n_elements

    Number of elements.

  n_selected_species

    Number of species selected for output (by slicing of Solution object)

  n_species

    Number of species.

  normalize_electron_energy_distribution_enabled

    Automatically normalize electron energy distribuion

  partial_molar_cp

    Array of species partial molar specific heat capacities at constant pressure [J/kmol/K].

  partial_molar_enthalpies

    Array of species partial molar enthalpies [J/kmol].

  partial_molar_entropies

    Array of species partial molar entropies [J/kmol/K].

  partial_molar_int_energies

    Array of species partial molar internal energies [J/kmol].

  partial_molar_volumes

    Array of species partial molar volumes [m^3/kmol].

  phase_of_matter

    Get the thermodynamic phase (gas, liquid, etc.) at the current conditions.

  quadrature_method

    Quadrature method

  reference_pressure

    Reference state pressure [Pa].

  report(self, show_thermo=True, float threshold=1e-14)

    Generate a report describing the thermodynamic state of this phase. To print the report to the terminal, simply call the phase object. The following two statements are equivalent:

        >>> phase()
        >>> print(phase.report())

  s

    Entropy [J/kg/K or J/kmol/K] depending on `basis`.

  set_discretized_electron_energy_distribution(self, levels, distribution)

    Set electron energy distribution. When this method is used, electron temperature is calculated from the distribution.

    Parameters

      - levels – vector of electron energy levels [eV]

      - distribution – vector of distribution

  set_equivalence_ratio(self, phi, fuel, oxidizer, basis='mole', *, diluent=None, fraction=None)

    Set the composition to a mixture of `fuel` and `oxidizer` at the specified equivalence ratio `phi`, 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 fuel and oxidizer compositions: `basis='mole'` means mole fractions (default), `basis='mass'` means mass fractions. The fuel/oxidizer mixture can be be diluted by a `diluent` based on a mixing `fraction`. The amount of diluent is quantified as a fraction of fuel, oxidizer or the fuel/oxidizer mixture. For more information, see Python example

        >>> gas.set_equivalence_ratio(0.5, 'CH4', 'O2:1.0, N2:3.76', basis='mole')
        >>> gas.mass_fraction_dict()
        {'CH4': 0.02837633052851681, 'N2': 0.7452356312613029, 'O2': 0.22638803821018036}
        >>> gas.set_equivalence_ratio(1.2, {'NH3':0.8, 'CO':0.2}, 'O2:1.0', basis='mole')
        >>> gas.mass_fraction_dict()
        {'CO': 0.14784006249290754, 'NH3': 0.35956645545401045, 'O2': 0.49259348205308207}

    Parameters

      - phi – Equivalence ratio

      - fuel – Fuel species name or mole/mass fractions as string, array, or dict.

      - oxidizer – Oxidizer species name or mole/mass fractions as a string, array, or dict.

      - basis – Determines if `fuel` and `oxidizer` are given in mole fractions (`basis='mole'`) or mass fractions (`basis='mass'`)

    Param

      diluent: Optional parameter. Required if dilution is used. Specifies the composition of the diluent in mole/mass fractions as a string, array or dict

    Param

      fraction: Optional parameter. Dilutes the fuel/oxidizer mixture with the diluent according to `fraction`. Fraction can refer to the fraction of diluent in the mixture (for example `fraction="diluent:0.7` will create a mixture with 30 % fuel/oxidizer and 70 % diluent), the fraction of fuel in the mixture (for example `fraction="fuel:0.1" means that the mixture contains 10 % fuel. The amount of oxidizer is determined from the equivalence ratio and the remaining mixture is the diluent) or fraction of oxidizer in the mixture (for example ``fraction="oxidizer:0.1")`. The fraction itself is interpreted as mole or mass fraction based on `basis`. The diluent is not considered in the computation of the equivalence ratio. Default is no dilution or `fraction=None`. May be given as string or dictionary (for example `fraction={"fuel":0.7})`

  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 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 of fuel and oxidizer: `basis='mole'` (default) means mole fractions, `basis='mass'` means mass fractions:

        >>> gas.set_mixture_fraction(0.5, 'CH4', 'O2:1.0, N2:3.76')
        >>> gas.mass_fraction_dict()
        {'CH4': 0.5, 'N2': 0.38350014242997776, 'O2': 0.11649985757002226}
        >>> gas.set_mixture_fraction(0.5, {'NH3':0.8, 'CO':0.2}, 'O2:1.0')
        >>> gas.mass_fraction_dict()
        {'CO': 0.145682068778996, 'NH3': 0.354317931221004, 'O2': 0.5}

    Parameters

      - mixture_fraction – Mixture fraction (kg fuel / kg mixture)

      - fuel – Fuel species name or mole/mass fractions as string, array, or dict.

      - oxidizer – Oxidizer species name or mole/mass fractions as a string, array, or dict.

      - basis – determines if `fuel` and `oxidizer` are given in mole fractions (`basis='mole'`) or mass fractions (`basis='mass'`)

  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 finite difference.

  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]` by finite difference.

  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 all species objects is returned. Changes to this object do not affect the `ThermoPhase` or `Solution` object until the `modify_species` function is called.

  species_index(self, species) → int

    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.

  species_name(self, k)

    Name of the species with index `k`.

  species_names

    A list of all the species names.

  standard_concentration_units

    Get standard concentration units for this phase.

  standard_cp_R

    Array of nondimensional species standard-state specific heat capacities at constant pressure at the current temperature and pressure.

  standard_enthalpies_RT

    Array of nondimensional species standard-state enthalpies at the current temperature and pressure.

  standard_entropies_R

    Array of nondimensional species standard-state entropies at the current temperature and pressure.

  standard_gibbs_RT

    Array of nondimensional species standard-state Gibbs free energies at the current temperature and pressure.

  standard_int_energies_RT

    Array of nondimensional species standard-state internal energies at the current temperature and pressure.

  state

    Get/Set the full thermodynamic state as a single array, arranged as [temperature, density, mass fractions] for most phases. Useful mainly in cases where it is desired to store many states in a multidimensional array.

  state_size

    Return size of vector defining internal state of the phase.

  stoich_air_fuel_ratio(self, fuel, oxidizer, basis='mole')

    Get the stoichiometric air to fuel ratio (kg oxidizer / kg fuel). Considers the oxidation of C to CO2, H to H2O and S to SO2. Other elements are assumed not to participate in oxidation (that is, N ends up as N2). The `basis` determines the composition of fuel and oxidizer: `basis='mole'` (default) means mole fractions, `basis='mass'` means mass fractions:

        >>> gas.set_mixture_fraction(0.5, 'CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
        >>> gas.stoich_air_fuel_ratio('CH3:0.5, CH3OH:.5, N2:0.125', 'O2:0.21, N2:0.79, NO:0.01')
        8.148040722239438

    Parameters

      - fuel – Fuel species name or mole/mass fractions as string, array, or dict.

      - oxidizer – Oxidizer species name or mole/mass fractions as a string, array, or dict.

      - basis – Determines if `fuel` and `oxidizer` are given in mole fractions (`basis='mole'`) or mass fractions (`basis='mass'`)

  thermal_expansion_coeff

    Thermal expansion coefficient [1/K].

  thermo_model

    Return thermodynamic model describing phase.

  u

    Internal energy in [J/kg or J/kmol].

  v

    Specific volume [m^3/kg or m^3/kmol] depending on `basis`.

  volume_mass

    Specific volume [m^3/kg].

  volume_mole

    Molar volume [m^3/kmol].

### InterfacePhase

class cantera.InterfacePhase(infile='', name='', adjacent=(), *, origin=None, source=None, yaml=None, thermo=None, species=(), **kwargs)

  Bases: `ThermoPhase`

  A class representing a surface or edge phase

  adjacent

    A dictionary containing higher-dimensional phases adjacent to this interface, for example bulk phases adjacent to a surface.

  coverages

    Get/Set the fraction of sites covered by each species.

  set_unnormalized_coverages(self, cov)

    Set the surface coverages without normalizing to force sum(cov) == 1.0. Useful primarily when calculating derivatives with respect to cov[k] by finite difference.

  site_density

    Get/Set the site density. [kmol/m^2] for surface phases; [kmol/m] for edge phases.

### PureFluid

class cantera.PureFluid(infile='', name='')

  Bases: `ThermoPhase`

  A pure substance that can be a gas, a liquid, a mixed gas-liquid fluid, or a fluid beyond its critical point.

  DPQ

    Get the density [kg/m^3], pressure [Pa], and vapor fraction.

  HPQ

    Get the enthalpy [J/kg or J/kmol], pressure [Pa] and vapor fraction.

  PQ

    Get/Set the pressure [Pa] and vapor fraction of a two-phase state.

  PV

    Get/Set the pressure [Pa] and specific volume [m^3/kg] of a PureFluid.

  Q

    Get/Set vapor fraction (quality). Can be set only when in the two-phase region.

  SH

    Get/Set the specific entropy [J/kg/K] and the specific enthalpy [J/kg] of a PureFluid.

  SPQ

    Get the entropy [J/kg/K or J/kmol/K], pressure [Pa], and vapor fraction.

  ST

    Get/Set the entropy [J/kg/K] and temperature [K] of a PureFluid.

  SVQ

    Get the entropy [J/kg/K or J/kmol/K], specific volume [m^3/kg or m^3/kmol], and vapor fraction.

  TDQ

    Get the temperature [K], density [kg/m^3 or kmol/m^3], and vapor fraction.

  TH

    Get/Set the temperature [K] and the specific enthalpy [J/kg] of a PureFluid.

  TPQ

    Get/Set the temperature [K], pressure [Pa], and vapor fraction of a PureFluid.

    An Exception is raised if the thermodynamic state is not consistent.

  TQ

    Get/Set the temperature [K] and vapor fraction of a two-phase state.

  TV

    Get/Set the temperature [K] and specific volume [m^3/kg] of a PureFluid.

  UP

    Get/Set the specific internal energy [J/kg] and the pressure [Pa] of a PureFluid.

  UVQ

    Get the internal energy [J/kg or J/kmol], specific volume [m^3/kg or m^3/kmol], and vapor fraction.

  VH

    Get/Set the specific volume [m^3/kg] and the specific enthalpy [J/kg] of a PureFluid.

## Mixture

class cantera.Mixture(phases)

  Bases: `object`

  Class Mixture represents mixtures of one or more phases of matter. To construct a mixture, supply a list of phases to the constructor, each paired with the number of moles for that phase:

      >>> gas = cantera.Solution("gas.yaml")
      >>> gas.species_names
      ['H2', 'H', 'O2', 'O', 'OH']
      >>> graphite = cantera.Solution("graphite.yaml")
      >>> graphite.species_names
      ['C(g)']
      >>> mix = cantera.Mixture([(gas, 1.0), (graphite, 0.1)])
      >>> mix.species_names
      ['H2', 'H', 'O2', 'O', 'OH', 'C(g)']

  Note that the objects representing each phase compute only the intensive state of the phase – they do not store any information on the amount of this phase. Mixture objects, on the other hand, represent the full extensive state.

  Mixture objects are ‘lightweight’ in the sense that they do not store parameters needed to compute thermodynamic or kinetic properties of the phases. These are contained in the (‘heavyweight’) phase objects. Multiple mixture objects may be constructed using the same set of phase objects. Each one stores its own state information locally, and synchronizes the phases objects whenever it requires phase properties.

  P

    Get or set the Pressure [Pa] of all phases in the mixture. When set, the temperature of the mixture is held fixed.

  T

    Get or set the Temperature [K] of all phases in the mixture. When set, the pressure of the mixture is held fixed.

  charge

    The total charge in Coulombs, summed over all phases.

  chemical_potentials

    The chemical potentials of all species [J/kmol].

  element_index(self, element) → int

    Index of element with name ‘element’.

        >>> mix.element_index('H')
        2

  element_moles(self, e)

    Total number of moles of element `e`, summed over all species. The element may be referenced either by index number or by name.

  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` 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 theory, see Smith and Missen, “Chemical Reaction Equilibrium.”

    Parameters

      - XY –

        A two-letter string, which must be one of the set:

            ['TP', 'HP', 'SP']

      - solver – Set to either ‘auto’, ‘vcs’, or ‘gibbs’ to choose implementation of the solver to use. ‘vcs’ uses the solver implemented in the C++ class ‘VCSnonideal’, ‘gibbs’ uses the one implemented in class ‘MultiPhaseEquil’. ‘auto’ will try the ‘vcs’ solver first and then the ‘gibbs’ solver if that fails.

      - rtol – Error tolerance. Iteration will continue until (Delta mu)/RT is less than this value for each reaction. Note that this default is very conservative, and good equilibrium solutions may be obtained with larger error tolerances.

      - max_steps – Maximum number of steps to take while solving the equilibrium problem for specified T and P.

      - max_iter – Maximum number of temperature and/or pressure iterations. This is only relevant if a property pair other than (T,P) is specified.

      - estimate_equil – Flag indicating whether the solver should estimate its own initial condition. If 0, the initial mole fraction vector in the phase objects are used as the initial condition. If 1, the initial mole fraction vector is used if the element abundances are satisfied. if -1, the initial mole fraction vector is thrown out, and an estimate is formulated.

      - log_level – Determines the amount of output displayed during the solution process. 0 indicates no output, while larger numbers produce successively more verbose information.

  max_temp

    The maximum temperature for which all species in multi-species solutions have valid thermo data. Stoichiometric phases are not considered in determining max_temp.

  min_temp

    The minimum temperature for which all species in multi-species solutions have valid thermo data. Stoichiometric phases are not considered in determining min_temp.

  n_atoms(self, k, m)

    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')
        4.0

  n_elements

    Total number of elements present in the mixture.

  n_phases

    Number of phases

  n_species

    Number of species.

  phase(self, n)

    Return the ThermoPhase object for phase number `n` in the mixture.

  phase_charge(self, p)

    The charge of phase `p` in Coulombs.

  phase_index(self, p)

    Index of the phase named `p`.

  phase_moles(self, p=None)

    Moles in phase `p`, if `p` is specified, otherwise the number of moles in all phases.

  phase_names

    Names of all phases in the order added.

  report(self, threshold=1e-14)

    Generate a report describing the thermodynamic state of this mixture. To print the report to the screen, simply call the mixture object. The following two statements are equivalent:

        >>> mix()
        >>> print(mix.report())

  set_phase_moles(self, p, moles)

    Set the number of moles of phase `p` to `moles`.

  species_index(self, phase, species)
    Parameters

      - phase – Phase object, index or name

      - species – Species name or index

    Returns the global index of species `species` in phase `phase`.

  species_moles

    Get or set the number of moles of each species. May be set either as a string or as an array. If an array is used, it must be dimensioned at least as large as the total number of species in the mixture. Note that the species may belong to any phase, and unspecified species are set to zero.

        >>> mix.species_moles = 'C(s):1.0, CH4:2.0, O2:0.2'

  species_name(self, k)

    Name of the species with index `k`. Note that index numbers are assigned in order as phases are added.

  species_names

    Get the names of the species from all phases in the mixture

## Species

class cantera.Species(name=None, composition=None, charge=None, size=None, init=True, *args, **kwargs)

  Bases: `object`

  A class which stores data about a single chemical species that may be needed to add it to a `Solution` or `Interface` object (and to the underlying `ThermoPhase` and `Transport` objects).

  Parameters

    - name – A string giving the name of the species, such as `'CH4'`

    - composition – The elemental composition of the species, given either as a dict or a composition string, such as `{'C':1, 'H':4}` or `'C:1, H:4'`.

    - charge – The electrical charge, in units of the elementary charge. Default 0.0.

    - size – The effective size [m] of the species. Default 1.0.

    - init – Used internally when wrapping Species objects returned from C++

  Example: creating an ideal gas phase with a single species:

      ch4 = ct.Species('CH4', 'C:1, H:4')
      ch4.thermo = ct.ConstantCp(300, 1000, 101325,
                                 (300, -7.453347e7, 1.865912e5, 3.576053e4))
      tran = ct.GasTransportData()
      tran.set_customary_units('nonlinear', 3.75, 141.40, 0.0, 2.60, 13.00)
      ch4.transport = tran
      gas = ct.Solution(thermo='IdealGas', species=[ch4])

  The static methods `fromYaml`, `fromCti`, `fromXml`, `listFromFile`, `listFromYaml`, `listFromCti`, and `listFromXml` can be used to create `Species` objects from existing definitions in the CTI or XML formats. Either of the following will produce a list of 53 `Species` objects containing the species defined in the GRI 3.0 mechanism:

      S = ct.Species.list_from_file("gri30.yaml")

      import pathlib
      S = ct.Species.listFromYaml(
          pathlib.Path('path/to/gri30.yaml').read_text(),
          section='species')

  charge

    The electrical charge on the species, in units of the elementary charge.

  clear_user_data(self)

    Clear all saved input data, so that the data given by `input_data` or `Solution.write_yaml` will only include values generated by Cantera based on the current object state.

  composition

    A dict containing the elemental composition of the species. Keys are element names; values are the corresponding atomicities.

  static fromCti(text)

    Create a Species object from its CTI string representation.

    Deprecated since version 2.5: The CTI input format is deprecated and will be removed in Cantera 3.0.

  static fromXml(text)

    Create a Species object from its XML string representation.

    Deprecated since version 2.5: The XML input format is deprecated and will be removed in Cantera 3.0.

  static fromYaml(text)

    Create a Species object from its YAML string representation.

    Deprecated since version 2.6: To be deprecated with version 2.6, and removed thereafter. Replaced by `Reaction.from_yaml`.

  static from_dict(data)

    Create a `Species` object from a dictionary corresponding to its YAML representation.

    Parameters

      data – A dictionary corresponding to the YAML representation.

  static from_yaml(text)

    Create a `Species` object from its YAML string representation.

  input_data

    Get input data defining this Species, along with any user-specified data provided with its input (YAML) definition.

  static listFromCti(text)

    Create a list of Species objects from all the species defined in a CTI string.

    Deprecated since version 2.5: The CTI input format is deprecated and will be removed in Cantera 3.0.

  static listFromFile(filename, section='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`.

    Directories on Cantera’s input file path will be searched for the specified file.

    In the case of an XML file, the `<species>` nodes are assumed to be children of the `<speciesData>` node in a document with a `<ctml>` root node, as in the XML files produced by conversion from CTI files.

    Deprecated since version 2.5: The CTI and XML input formats are deprecated and will be removed in Cantera 3.0.

    Deprecated since version 2.6: To be removed after Cantera 2.6. Replaced by ‘Species.list_from_file’.

  static listFromXml(text)

    Create a list of Species objects from all the species defined in an XML string. The `<species>` nodes are assumed to be children of the `<speciesData>` node in a document with a `<ctml>` root node, as in the XML files produced by conversion from CTI files.

    Deprecated since version 2.5: The XML input format is deprecated and will be removed in Cantera 3.0.

  static listFromYaml(text, section=None)

    Create a list of Species objects from all the species defined in a YAML string.

    Deprecated since version 2.6: To be deprecated with version 2.6, and removed thereafter. Replaced by `Reaction.list_from_yaml`.

  static 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 searched for the specified file.

  static list_from_yaml(text, section=None)

    Create a list of Species objects from all the species defined in a YAML string. If `text` is a YAML mapping, the `section` name of the list to be read must be specified. If `text` is a YAML list, no `section` name should be supplied.

  name

    The name of the species.

  size

    The effective size [m] of the species.

  thermo

    Get/Set the species reference-state thermodynamic data, as an instance of class `SpeciesThermo`.

  transport

    Get/Set the species transport parameters, as an instance of class `GasTransportData`.

  update_user_data(self, data)

    Add the contents of the provided `dict` as additional fields when generating YAML phase definition files with `Solution.write_yaml` or in the data returned by `input_data`. Existing keys with matching names are overwritten.

## Species Thermodynamic Properties

These classes are used to describe the reference-state thermodynamic properties of a pure species.

### SpeciesThermo

class cantera.SpeciesThermo(T_low, T_high, P_ref, coeffs)

  Bases: `object`

  Base class for representing the reference-state thermodynamic properties of a pure species. These properties are a function of temperature. Derived classes implement a parameterization of this temperature dependence. This is a wrapper for the C++ class SpeciesThermoInterpType.

  Parameters

    - T_low – The minimum temperature [K] at which the parameterization is valid

    - T_high – The maximum temperature [K] at which the parameterization is valid

    - P_ref – The reference pressure [Pa] for the parameterization

    - coeffs – An array of coefficients for the parameterization. The length of this array and the meaning of each element depends on the specific parameterization.

  clear_user_data(self)

    Clear all saved input data, so that the data given by `input_data` or `Solution.write_yaml` will only include values generated by Cantera based on the current object state.

  coeffs

    Array of coefficients for the parameterization. The length of this array and the meaning of each element depends on the specific parameterization.

  cp(self, T)

    Molar heat capacity at constant pressure [J/kmol/K] at temperature T.

  h(self, T)

    Molar enthalpy [J/kmol] at temperature T

  input_data

    Get input data defining this SpeciesThermo object, along with any user-specified data provided with its input (YAML) definition.

  max_temp

    Maximum temperature [K] at which the parameterization is valid.

  min_temp

    Minimum temperature [K] at which the parameterization is valid.

  n_coeffs

    Number of parameters for the parameterization.

  reference_pressure

    Reference pressure [Pa] for the parameterization.

  s(self, T)

    Molar entropy [J/kmol/K] at temperature T

  update_user_data(self, data)

    Add the contents of the provided `dict` as additional fields when generating YAML phase definition files with `Solution.write_yaml` or in the data returned by `input_data`. Existing keys with matching names are overwritten.

### ConstantCp

class cantera.ConstantCp(T_low, T_high, P_ref, coeffs)

  Bases: `SpeciesThermo`

  Thermodynamic properties for a species that has a constant specific heat capacity. This is a wrapper for the C++ class ConstCpPoly.

  Parameters

    coeffs –

    An array of 4 elements:

    > - `coeffs[0]` = \(T_0\) [K]

    > - `coeffs[1]` = \(H^o(T_0, p_{ref})\) [J/kmol]

    > - `coeffs[2]` = \(S^o(T_0, p_{ref})\) [J/kmol-K]

    > - `coeffs[3]` = \(c_p^o(T_0, p_{ref})\) [J/kmol-K]

### Mu0Poly

class cantera.Mu0Poly(T_low, T_high, P_ref, coeffs)

  Bases: `SpeciesThermo`

  Thermodynamic properties for a species which is parameterized using an interpolation of the Gibbs free energy based on a piecewise constant heat capacity approximation. This is a wrapper for the C++ class Mu0Poly.

  Parameters

    coeffs –

    An array of 2+2*npoints elements, in the following order:

    > - `coeffs[0]`: number of points (integer)

    > - `coeffs[1]`: h^o(298.15 K) [J/kmol]

    > - `coeffs[2]`: T_1 [Kelvin]

    > - `coeffs[3]`: mu^o(T_1) [J/kmol]

    > - `coeffs[4]`: T_2 [Kelvin]

    > - `coeffs[5]`: mu^o(T_2) [J/kmol]

    > - …

### NasaPoly2

class cantera.NasaPoly2(T_low, T_high, P_ref, coeffs)

  Bases: `SpeciesThermo`

  Thermodynamic properties for a species which is parameterized using the 7-coefficient NASA polynomial form in two temperature ranges. This is a wrapper for the C++ class NasaPoly2.

  Parameters

    coeffs –

    An array of 15 elements, in the following order:

    > - `coeffs[0]`: The mid-point temperature [K] between the two parameterizations

    > - `coeffs[1:8]`: The 7 coefficients of the high-temperature parameterization

    > - `coeffs[8:15]`: The 7 coefficients of the low-temperature parameterization

    This is the coefficient order used in the standard fixed-format NASA input files.

### Nasa9PolyMultiTempRegion

class cantera.Nasa9PolyMultiTempRegion(T_low, T_high, P_ref, coeffs)

  Bases: `SpeciesThermo`

  Thermodynamic properties for a species which is parameterized using the 9-coefficient NASA polynomial form encompassing multiple temperature ranges. This is a wrapper for the C++ class Nasa9PolyMultiTempRegion.

  Parameters

    coeffs –

    An array of 1 + 11*`nzones` elements, in the following order:

    > - `coeffs[0]`: Number of zones (`nzones`)

    > - `coeffs[1 + 11*zone]`: minimum temperature within zone

    > - `coeffs[2 + 11*zone]`: maximum temperature within zone

    > - `coeffs[3:11 + 11*zone]`: 9 coefficients of the parameterization

    where `zone` runs from zero to `nzones`-1.

### ShomatePoly2

class cantera.ShomatePoly2(T_low, T_high, P_ref, coeffs)

  Bases: `SpeciesThermo`

  Thermodynamic properties for a species which is parameterized using the Shomate equation in two temperature ranges. This is a wrapper for the C++ class ShomatePoly2.

  Parameters

    coeffs –

    An array of 15 elements, in the following order:

    > - `coeffs[0]`: The mid-point temperature [K] between the two parameterizations

    > - `coeffs[1:8]`: The 7 coefficients of the low-temperature parameterization

    > - `coeffs[8:15]`: The 7 coefficients of the high-temperature parameterization

    These coefficients should be provided in their customary units (that is, such that \(c_p^o\) is in J/gmol-K and \(H^o\) is in kJ/gmol, as in the NIST Chemistry WebBook).

## Element

class cantera.Element(self, arg)

  Bases: `object`

  An element or a named isotope defined in Cantera.

  Class `Element` gets data for the elements and isotopes defined in Elements.cpp. This class can be used in two ways. The first way is to get information about all of the elements stored in Cantera. The three attributes `num_elements_defined`, `element_symbols`, and `element_names` can be accessed by:

      >>> ct.Element.num_elements_defined
      >>> ct.Element.element_symbols
      >>> ct.Element.element_names

  Otherwise, if the class `Element` is called with an argument, it stores the data about that particular element. For example:

      >>> ar_sym = ct.Element('Ar')
      >>> ar_name = ct.Element('argon')
      >>> ar_num = ct.Element(18)

  would all create instances with the information for argon. The available argument options to create an instance of the `Element` class with the element information are the `name`, `symbol`, and `atomic_number`. Once an instance of the class is made, the `name`, `atomic_number`, `symbol`, and atomic `weight` can be accessed as attributes of the instance of the `Element` class.

      >>> ar_sym.name
      'argon'
      >>> ar_sym.weight
      39.948
      >>> ar_sym.atomic_number
      18
      >>> ar_sym.symbol
      'Ar'

  The elements available are listed below, in the `element_symbols` and `element_names` attribute documentation.

  num_elements_defined = 118
  element_symbols = ['H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne', 'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar', 'K', 'Ca', 'Sc', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn', 'Ga', 'Ge', 'As', 'Se', 'Br', 'Kr', 'Rb', 'Sr', 'Y', 'Zr', 'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn', 'Sb', 'Te', 'I', 'Xe', 'Cs', 'Ba', 'La', 'Ce', 'Pr', 'Nd', 'Pm', 'Sm', 'Eu', 'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb', 'Lu', 'Hf', 'Ta', 'W', 'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg', 'Tl', 'Pb', 'Bi', 'Po', 'At', 'Rn', 'Fr', 'Ra', 'Ac', 'Th', 'Pa', 'U', 'Np', 'Pu', 'Am', 'Cm', 'Bk', 'Cf', 'Es', 'Fm', 'Md', 'No', 'Lr', 'Rf', 'Db', 'Sg', 'Bh', 'Hs', 'Mt', 'Ds', 'Rg', 'Cn', 'Nh', 'Gl', 'Mc', 'Lv', 'Ts', 'Og']
  element_names = ['hydrogen', 'helium', 'lithium', 'beryllium', 'boron', 'carbon', 'nitrogen', 'oxygen', 'fluorine', 'neon', 'sodium', 'magnesium', 'aluminum', 'silicon', 'phosphorus', 'sulfur', 'chlorine', 'argon', 'potassium', 'calcium', 'scandium', 'titanium', 'vanadium', 'chromium', 'manganese', 'iron', 'cobalt', 'nickel', 'copper', 'zinc', 'gallium', 'germanium', 'arsenic', 'selenium', 'bromine', 'krypton', 'rubidium', 'strontium', 'yttrium', 'zirconium', 'nobelium', 'molybdenum', 'technetium', 'ruthenium', 'rhodium', 'palladium', 'silver', 'cadmium', 'indium', 'tin', 'antimony', 'tellurium', 'iodine', 'xenon', 'cesium', 'barium', 'lanthanum', 'cerium', 'praseodymium', 'neodymium', 'promethium', 'samarium', 'europium', 'gadolinium', 'terbium', 'dysprosium', 'holmium', 'erbium', 'thulium', 'ytterbium', 'lutetium', 'hafnium', 'tantalum', 'tungsten', 'rhenium', 'osmium', 'iridium', 'platinum', 'gold', 'mercury', 'thallium', 'lead', 'bismuth', 'polonium', 'astatine', 'radon', 'francium', 'radium', 'actinium', 'thorium', 'protactinium', 'uranium', 'neptunium', 'plutonium', 'americium', 'curium', 'berkelium', 'californium', 'einsteinium', 'fermium', 'mendelevium', 'nobelium', 'lawrencium', 'rutherfordium', 'dubnium', 'seaborgium', 'bohrium', 'hassium', 'meitnerium', 'darmstadtium', 'roentgenium', 'copernicium', 'nihonium', 'flerovium', 'moscovium', 'livermorium', 'tennessine', 'oganesson']
  property atomic_number

    The atomic number of the element or isotope.

  property name

    The name of the element or isotope.

  property symbol

    The symbol of the element or isotope.

  property weight

    The atomic weight of the element or isotope.