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.

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.