Utilities#

YAML Input/Output #

AnyMap #

class cantera.AnyMap#

Bases: dict

A key-value store representing objects defined in Cantera’s YAML input format.

Extends the capabilities of a normal dict object by providing functions for converting values between different unit systems. See Units for details on how units are handled in YAML input files.

convert(key, dest)#: Convert the value corresponding to the specified key to the units defined by dest. dest may be a string or a Units object.

convert_activation_energy(key, dest)#: Convert the value corresponding to the specified key to the units defined by dest. dest may be a string or a Units object defining units that are interpretable as an activation energy.

convert_rate_coeff(key, dest)#: Convert the value corresponding to the specified key to the units defined by dest, with special handling for UnitStack input and potentially-undefined rate coefficient units.

default_units()#

set_activation_energy(key, value, src)#: Set the element key of this map to the specified value, converting from the activation energy units defined by src to the correct unit system for this map when serializing to YAML.

set_quantity(key, value, src)#: Set the element key of this map to the specified value, converting from the units defined by src to the correct unit system for this map when serializing to YAML.

units#: Get the UnitSystem applicable to this AnyMap.

YamlWriter #

class cantera.YamlWriter#

Bases: object

A class for generating full YAML input files from multiple Solution objects

add_solution(soln)#: Include a phase definition for the specified Solution object

output_units#

Set the units to be used in the output file. Dimensions not specified will use Cantera’s defaults.

Parameters:: units – A UnitSystem object or map where keys are dimensions (mass, length, time, quantity, pressure, energy, activation-energy), and the values are corresponding units such as kg, mm, s, kmol, Pa, cal, and eV.

precision#: For output floating point values, set the maximum number of digits to the right of the decimal point. The default is 15 digits.

set_header(soln)#: Include top-level information for the specified Solution object

skip_user_defined#: By default user-defined data present in the input is preserved on output. This method can be used to skip output of user-defined data fields which are not directly used by Cantera.

to_file(filename)#: Write the definitions for the added phases, species and reactions to the specified file.

to_string()#: Return a YAML string that contains the definitions for the added phases, species, and reactions.

Unit Conversions #

UnitSystem #

class cantera.UnitSystem(units)#

Bases: object

Unit system used for YAML input and output.

The UnitSystem class is used to specify dimensional values for a given unit system. The main use is for converting values specified in input files to Cantera’s native unit system, which is SI units except for the use of kmol as the base unit of quantity, that is, kilogram, meter, second, kelvin, ampere, and kmol.

Generally, this class is used indirectly, through methods interacting with AnyMap objects such as ExtensibleRate.set_parameters and ExtensibleRate.get_parameters.

The default unit system used by Cantera is SI+kmol:

ct.UnitSystem({
    "length": "m", "mass": "kg", "time": "s",
    "quantity": "kmol", "pressure": "Pa", "energy": "J",
    "temperature": "K", "current": "A", "activation-energy": "J / kmol"})

A CGS+mol unit system with activation energy units of cal/mol is created as:

ct.UnitSystem({
    "length": "cm", "mass": "g", "time": "s",
    "quantity": "mol", "pressure": "dyn / cm^2", "energy": "erg",
    "temperature": "K", "current": "A", "activation-energy": "cal / mol"})

Defaults for dimensions not specified will be left unchanged. Accordingly, the default unit system is retrieved as:

ct.UnitSystem()

convert_activation_energy_to(quantity, dest)#

Convert quantity to the activation energy units defined by dest, using this UnitSystem to define the default units of quantity. quantity can be one of the following:

A number, for example 3.14
A “quantity string” containing a number and a dimension string, separated by a space. For example, "3.14 J/kmol"
A NumPy array of either numeric values or quantity strings as described above
A list, tuple, or other sequence of any shape containing numeric values or quantity strings, For example ("30 kcal/mol", 3.14, "12000 K")

dest can be a string or Units object specifying the destination units, which must be interpretable as unit of energy per unit quantity (for example, J/kmol), energy (for example, eV) or temperature (K).

convert_rate_coeff_to(quantity, dest)#: Convert a quantity representing a rate coefficient to the units defined by dest, using this UnitSystem to define the default units of quantity. Behaves similar to`convert_to` but with special handling for the case of standalone rate constants, where the destination units are not actually known, and where the units may be specified using Units or UnitStack objects.

convert_to(quantity, dest)#

Convert quantity to the units defined by dest, using this UnitSystem to define the default units of quantity. quantity can be one of the following:

A number, for example 3.14
A “quantity string” containing a number and a dimension string, separated by a space. For example, "3.14 kmol/m^3"
A NumPy array of either numeric values or quantity strings as described above
A list, tuple, or other sequence of any shape containing numeric values or quantity strings, For example ("3000 mm", 3.14, "12 cm")

dest can be a string or Units object specifying the destination units.

units#: Units used by the unit system

Units #

class cantera.Units(name)#

Bases: object

A representation of the units associated with a dimensional quantity.

This class is a light-weight interface to internal Cantera capabilities that are used for converting quantities between unit systems and checking for dimensional consistency. Internally, Units objects are mainly used within the UnitSystem class to convert values from a user-specified Unit system to Cantera’s base units (SI + kmol).

The Python API handles display of Units that do not require a conversion factor, with other functions not enabled.

dimension(primary: str) → float#

The dimension of the given unit component.

Added in version 3.0.

Parameters:: primary – A string with the desired unit component. One of "mass", "length", "time", "temperature", "current", or "quantity".

dimensions#: A dictionary of the primary unit components to their dimensions.

Added in version 3.0.

factor#: The factor required to convert from this unit to Cantera’s base units.

Added in version 3.0.

Global Functions #

cantera.add_directory(directory)#: Add a directory to search for Cantera data files.

cantera.get_data_directories()#: Get a list of the directories Cantera searches for data files.

cantera.import_phases(filename, phase_names)#: Import multiple phases from one file. The phase names should be entered as a list of strings.

cantera.appdelete()#: Delete all global Cantera C++ objects

cantera.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.

cantera.make_deprecation_warnings_fatal()#

cantera.suppress_deprecation_warnings()#

cantera.suppress_thermo_warnings(suppress=True)#

cantera.use_legacy_rate_constants(legacy)#

Set definition used for rate constant calculation.

If set to False (default value), rate constants of three-body reactions are consistent with conventional definitions (for example Eq. 9.75 in Kee et al. [2003]). If set to True, output for rate constants of three-body reactions is multiplied by third-body concentrations, consistent with Cantera’s behavior prior to version 3.0.

cantera.debug_mode_enabled()#

cantera.print_stack_trace_on_segfault()#: Enable printing a stack trace if a segfault occurs. Not recommended for general use as it is possible for this to deadlock.

Added in version 3.0.

cantera.add_module_directory()#: Add the directory containing the module from which this function is called to the Cantera input file search path.

cantera.extension(name: str)#

A decorator for declaring Cantera extensions that should be registered with the corresponding factory classes to create objects with the specified name.

This decorator can be used in combination with an extensions section in a YAML input file to trigger registration of extensions marked with this decorator, For example, consider an input file containing top level extensions and reactions sections such as:

extensions:
- type: python
  name: my_cool_module

...  # phases and species sections

reactions:
- equation: O + H2 <=> H + OH  # Reaction 3
  type: cool-rate
  A: 3.87e+04
  b: 2.7
  Ea: 6260.0

and a Python module my_cool_module.py:

import cantera as ct

class CoolRateData(ct.ExtensibleRateData):
    def update(self, soln):
        ...

@ct.extension(name="cool-rate", data=CoolRateData)
class CoolRate(ct.ExtensibleRate):
    def set_parameters(self, params, units):
        ...
    def eval(self, data):
        ...

Loading this input file from any Cantera user interface would cause Cantera to load the my_cool_module.py module and register the CoolRate and CoolRateData classes to handle reactions whose type in the YAML file is set to cool-rate.

Added in version 3.0.

Exceptions #

CanteraError #

class cantera.CanteraError#

Bases: RuntimeError

static set_stack_trace_depth(depth)#: Set the number of stack frames to include when a CanteraError is displayed. By default, or if the depth is set to 0, no stack information will be shown.

ThermoModelMethodError #

class cantera.ThermoModelMethodError(thermo_model)#

Bases: Exception

Exception raised for an invalid method used by a thermo model

Parameters:: thermo_model – The thermo model used by class ThermoPhase