Skip to main content
`Ctrl`+`K`

# 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

  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

  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.

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

    New in version 3.0.

  factor

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

    New 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, Coltrin and Glarborg, ‘Chemically Reacting Flow’, Wiley Interscience, 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.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`.

  New in version 3.0.

## Exceptions

### CanteraError

class cantera.CanteraError

  Bases: `RuntimeError`

### 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`