Skip to main content
`Ctrl`+`K`

# Python Interface With Units

This interface allows users to specify physical units associated with quantities. To do so, this interface leverages the pint library to provide consistent unit conversion. Several examples of this interface can be found in the `samples/python` folder in the root of the repository. Examples that use this interface are suffixed with `_units`.

The overall goal is to provide a compatible implementation of the `cantera.Solution` and `cantera.PureFluid` interfaces. Please see those pages for further documentation of the available properties.

## Solution with Units

class cantera.with_units.Solution(infile='', name='', *, yaml=None)

  Bases: `object`

  This implementation of `Solution` operates with units by using the `pint` library to convert between unit systems. All properties are assigned units in the standard MKS system that Cantera uses, substituting kmol instead of mol. Each property is an instance of the `pint.Quantity` class.

  Similarly, properties must be instances of `pint.Quantity` classes when they are used for assignment to set the state. The properties may have any units, so long as the dimensions for the quantity are consistent. For example, temperatures can be provided in K, degC, degF, or degR; conversion will be done internally to Cantera’s consistent unit system.

  See the pint documentation for more information about using pint’s `Quantity` classes.

  Note: This class is experimental. It only implements methods from `ThermoPhase`. Methods from other classes are not yet supported. If you are interested in contributing to this feature, please chime in on our enhancements issue: Cantera/enhancements#174.

  A class for chemically-reacting solutions. Instances can be created to represent any type of solution – a mixture of gases, a liquid solution, or a solid solution, for example.

  Class `Solution` derives from classes `ThermoPhase`, `Kinetics`, and `Transport`. It defines no methods of its own, and is provided so that a single object can be used to compute thermodynamic, kinetic, and transport properties of a solution.

  To skip initialization of the Transport object, pass the keyword argument `transport_model=None` to the `Solution` constructor.

  The most common way to instantiate `Solution` objects is by using a phase definition, species and reactions defined in an input file:

      gas = ct.Solution('gri30.yaml')

  If an input file defines multiple phases, the corresponding key in the `phases` map can be used to specify the desired phase via the `name` keyword argument of the constructor:

      gas = ct.Solution('diamond.yaml', name='gas')
      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, a custom name can assigned via:

      gas.name = 'my_custom_name'

  `Solution` objects can also be constructed using `Species` and `Reaction` objects which can themselves either be imported from input files or defined directly in Python:

      spec = ct.Species.list_from_file("gri30.yaml")
      spec_gas = ct.Solution(thermo='ideal-gas', species=spec)
      rxns = ct.Reaction.list_from_file("gri30.yaml", spec_gas)
      gas = ct.Solution(thermo='ideal-tas', kinetics='gas',
                        species=spec, reactions=rxns, name='my_custom_name')

  where the `thermo` and `kinetics` keyword arguments are strings specifying the thermodynamic and kinetics model, respectively, and `species` and `reactions` keyword arguments are lists of `Species` and `Reaction` objects, respectively. Note that importing the reactions from a YAML input file requires a `Kinetics` object containing the species, as shown.

  Types of underlying models that form the composite `Solution` object are queried using the `thermo_model`, `kinetics_model` and `transport_model` attributes; further, the `composite` attribute is a shorthand returning a tuple containing the types of the three constitutive models.

  For non-trivial uses cases of this functionality, see the examples extract_submechanism.py and mechanism_reduction.py.

  In addition, `Solution` objects can be constructed by passing the text of the YAML phase definition in directly, using the `yaml` keyword argument:

      yaml_def = '''
      phases:
      - name: gas
        thermo: ideal-gas
        kinetics: gas
        elements: [O, H, Ar]
        species:
        - gri30.yaml/species: all
        reactions:
        - gri30.yaml/reactions: declared-species
        skip-undeclared-elements: true
        skip-undeclared-third-bodies: true
        state: {T: 300, P: 1 atm}
      '''
      gas = ct.Solution(yaml=yaml_def)

## PureFluid Phases With Units

The following convenience classes are available to create `PureFluid` objects with the indicated equation of state:

class cantera.with_units.CarbonDioxide

  Bases:

  Create a `PureFluid` object using the equation of state for carbon dioxide.

  The object returned by this method implements an accurate equation of state for carbon dioxide that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances. Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::CarbonDioxide in the Cantera C++ source code documentation.

class cantera.with_units.Heptane

  Bases:

  Create a `PureFluid` object using the equation of state for heptane.

  The object returned by this method implements an accurate equation of state for n-heptane that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances. Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::Heptane in the Cantera C++ source code documentation.

class cantera.with_units.Hfc134a

  Bases:

  Create a `PureFluid` object using the equation of state for HFC-134a.

  The object returned by this method implements an accurate equation of state for refrigerant HFC134a (R134a) that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. Implements the equation of state given in:

  > R. Tillner-Roth, H. D. Baehr. An International Standard Formulation for The Thermodynamic Properties of 1,1,1,2-Tetrafluoroethane (HFC-134a) for Temperatures From 170 K to 455 K and Pressures up to 70 MPa. J. Phys. Chem. Ref. Data, Vol. 23, No. 5, 1994. pp. 657–729. http://dx.doi.org/10.1063/1.555958

  For more details, see classes PureFluidPhase and tpx::HFC134a in the Cantera C++ source code documentation.

class cantera.with_units.Hydrogen

  Bases:

  Create a `PureFluid` object using the equation of state for hydrogen.

  The object returned by this method implements an accurate equation of state for hydrogen that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::hydrogen in the Cantera C++ source code documentation.

class cantera.with_units.Methane

  Bases:

  Create a `PureFluid` object using the equation of state for methane.

  The object returned by this method implements an accurate equation of state for methane that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::methane in the Cantera C++ source code documentation.

class cantera.with_units.Nitrogen

  Bases:

  Create a `PureFluid` object using the equation of state for nitrogen.

  The object returned by this method implements an accurate equation of state for nitrogen that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::nitrogen in the Cantera C++ source code documentation.

class cantera.with_units.Oxygen

  Bases:

  Create a `PureFluid` object using the equation of state for oxygen.

  The object returned by this method implements an accurate equation of state for oxygen that can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram. The equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances Stanford: Stanford University, 1979. Print.

  For more details, see classes PureFluidPhase and tpx::oxygen in the Cantera C++ source code documentation.

class cantera.with_units.Water(backend='Reynolds')

  Bases:

  Create a `PureFluid` object using the equation of state for water and the `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 the `Reynolds` backend, the equation of state is taken from

  > W. C. Reynolds, Thermodynamic Properties in SI: graphs, tables, and computational equations for forty substances. Stanford: Stanford University, 1979. Print.

  which can be used in the liquid, vapor, saturated liquid/vapor, and supercritical regions of the phase diagram.

  The `IAPWS95` backend implements an IAPWS (International Association for the Properties of Water and Steam) formulation for thermodynamic properties taken from

  > W. Wagner, A. Pruss, The IAPWS Formulation 1995 for the Thermodynamic Properties of Ordinary Water Substance for General and Scientific Use, J. Phys. Chem. Ref. Dat, 31, 387, 2002.

  which currently only implements liquid and supercritical regions.

  In both cases, formulas for transport are taken from

  > J. V. Sengers, J. T. R. Watson, Improved International Formulations for the Viscosity and Thermal Conductivity of Water Substance, J. Phys. Chem. Ref. Data, 15, 1291, 1986.

  For more details, see classes PureFluidPhase, tpx::water, WaterSSTP and WaterTransport in the Cantera C++ source code documentation.

The full documentation for the `PureFluid` class and its properties is here:

class cantera.with_units.PureFluid(infile, name='', *, yaml=None, **kwargs)

  Bases: `object`

  This implementation of `PureFluid` operates with units by using the `pint` library to convert between unit systems. All properties are assigned units in the standard MKS system that Cantera uses, substituting kmol instead of mol. Each property is an instance of the `pint.Quantity` class.

  Similarly, properties must be instances of `pint.Quantity` classes when they are used for assignment to set the state. The properties may have any units, so long as the dimensions for the quantity are consistent. For example, temperatures can be provided in K, degC, degF, or degR; conversion will be done internally to Cantera’s consistent unit system.

  See the pint documentation for more information about using pint’s `Quantity` classes.

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