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 thisAnyMap
.
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 asExtensibleRate.set_parameters
andExtensibleRate.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 usingUnits
orUnitStack
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 theUnitSystem
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 installscipy
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 toTrue
, 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 levelextensions
andreactions
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 theCoolRate
andCoolRateData
classes to handle reactions whosetype
in the YAML file is set tocool-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