rizer.misc.ct_utils#

Classes#

CanteraStringInputThermo

CanteraStringInput

Functions#

load_goutier2025_mechanism(phase_name) → cantera.Solution

Load the Goutier2025 mechanism for CH4 to C2H2.

load_goutier2025_mechanism_with_options([thermo, ...]) → cantera.Solution

Load the Goutier2025 mechanism for CH4 to C2H2, with individually selectable options.

plot_chemical_equilibrium(thermo, initial_solution, ...)

Plot main species under thermochemical equilibrium with [Cantera].

get_similar_reactions(reaction, gas[, verbose]) → dict[int, cantera.Reaction]

Get all reactions in a cantera.Solution that are similar to reaction.

to_cantera_format(A, b, Ea, plasma, equation, note[, ...]) → str

Convert a reaction rate constant to Cantera format.

get_fake_reverse_reaction(reaction, gas) → cantera.Reaction

Generate a fake reverse reaction for unit conversion purposes.

to_reverse_reaction_format(forward_reaction, gas, note) → str

return_x_y_from_hydrocarbon(hydrocarbon) → tuple[int, int]

Return the number of carbon atoms and hydrogen atoms in a hydrocarbon.

from_ct_dict_to_ct_str(ct_dict) → str

Convert a Cantera dictionary to a Cantera string.

partially_ionized_mole_fractions(x_e[, background, ion]) → str

Cantera X string for a seeded, partially ionized plasma composition.

Module Contents#

rizer.misc.ct_utils.load_goutier2025_mechanism(phase_name: str) → cantera.Solution#

Load the Goutier2025 mechanism for CH4 to C2H2.

The mechanism is loaded from the data/mechanisms/Goutier2025/CH4_to_C2H2.yaml file.

To properly load the mechanism, the following classes need to be imported from rizer.kinetics.extensible_rate:

  • ExtensibleElectronTemperaturePlasmaRateData

  • ExtensibleTwoTempPlasmaRateData

  • JanevDissociativeRecombinationC2Hy

  • DruyvesteynRate

  • ReverseTwoTemperaturePlasma

Even though the classes are imported, they are not used in this function. They are only used to ensure that the YAML file can be loaded by Cantera.

Parameters:

phase_name (str) –

Name of the phase to load. Could be:

  • plasma: Plasma phase without electronic excited states.

  • gas: Gas phase without electronic excited states.

  • plasma_with_electronic_excited_states: Plasma phase with electronic excited states.

  • gas_with_electronic_excited_states: Gas phase with electronic excited states.

  • plasma_druyvesteyn_with_electronic_excited_states: Plasma phase with electronic excited states and Druyvesteyn electron energy distribution function.

  • gas_druyvesteyn_with_electronic_excited_states: Gas phase with electronic excited states and Druyvesteyn electron energy distribution function.

Returns:

The loaded mechanism.

Return type:

cantera.Solution

rizer.misc.ct_utils.load_goutier2025_mechanism_with_options(thermo: str = 'plasma', electron_energy_distribution: str = 'maxwellian', electronic_excited_states: str | list[str] | None = 'None', radiative_ionization_included: bool = False) → cantera.Solution#

Load the Goutier2025 mechanism for CH4 to C2H2, with individually selectable options.

Unlike load_goutier2025_mechanism(), which loads one of a fixed set of pre-composed phases, this function dynamically assembles the phase from the same data/mechanisms/Goutier2025/CH4_to_C2H2.yaml file: it loads the phase that is the superset of species and reactions for the requested thermo and electron_energy_distribution, then filters species and reactions down to the requested electronic_excited_states and radiative_ionization_included. The YAML file itself is never modified.

Parameters:

  • thermo (str, optional) – Either plasma or gas, by default plasma.

  • electron_energy_distribution (str, optional) – Either maxwellian or Druyvesteyn, by default maxwellian.

  • electronic_excited_states (str, list of str, or None, optional) –

    Which atomic species to include electronically excited states for, by default None.

    • None or “None”: no electronically excited states.

    • atomic_C: electronically excited states of atomic carbon only.

    • atomic_H: electronically excited states of atomic hydrogen only.

    • [“atomic_C”, “atomic_H”]: electronically excited states of both.

    • all: equivalent to [“atomic_C”, “atomic_H”].

  • radiative_ionization_included (bool, optional) – The mechanism includes three radiative-recombination reactions (e- + C+ => C, e- + H+ => H, e- + H2+ => H + H), whose forward rate is physically correct. Their detailed-balance reverse reactions would represent radiative ionization (e.g. H + hnu => e- + H+), but a rate derived from detailed balance with the electron temperature does not correctly capture this photon-driven process. By default (False), these three reverse reactions are removed. If True, they are kept.

Returns:

The loaded mechanism.

Return type:

cantera.Solution

See also

load_goutier2025_mechanism

rizer.misc.ct_utils.plot_chemical_equilibrium(thermo: str | pathlib.Path, initial_solution: str | dict[str, float], temperatures: numpy.ndarray, unit: str = 'K', keep_only_first_species: int = 5, save_file_name: str | pathlib.Path | None = None, fraction: str = 'mole')#

Plot main species under thermochemical equilibrium with [Cantera].

Parameters:

  • thermo (str or pathlib.Path) – Cantera thermo file.

  • initial_solution (str or dict) – Initial solution (in mole). Either a string like “CH4:1, O2:2” or a dictionary like {“CH4”: 1, “O2”: 2}.

  • temperatures (numpy.ndarray) – Temperatures to evaluate.

  • unit (str, optional) – Temperature unit (“K” or “C”), by default “K”

  • keep_only_first_species (int, optional) – Keep only the first majority species, by default 5

  • save_file_name (str or pathlib.Path or None, optional) – Save file name, by default None

  • fraction (str, optional) – Display the result with “mole” or “mass” fraction, by default “mole”

rizer.misc.ct_utils.get_similar_reactions(reaction: str | cantera.Reaction, gas: cantera.Solution, verbose: bool = False) → dict[int, cantera.Reaction]#

Get all reactions in a cantera.Solution that are similar to reaction.

Similarity is defined as:

  • all the reactants of reaction are a subset of the reactants of one reaction in gas.

  • all the products of reaction are a subset of the reactants of one reaction in gas (happens when the reaction is reversible)

This function is used to give a hint on mistyped reactions.

Parameters:
Returns:

Dictionary of similar reactions.

  • Keys are the reaction index in gas.reactions().

  • Values are the corresponding reactions, as cantera.Reaction objects.

Return type:

dict of int to cantera.Reaction

Example

>>> import cantera as ct
>>> from rizer.misc.ct_utils import get_similar_reactions
>>> gas = ct.Solution("gri30.yaml")
>>> _ = get_similar_reactions("H + CH4 <=> CH3 + H2", gas, verbose=True)
Reactions similar to CH4 + H <=> CH3 + H2, with {'CH4': 1.0, 'H': 1.0} as either reactants or products, are {52: CH4 + H <=> CH3 + H2    <Arrhenius>}
rizer.misc.ct_utils.to_cantera_format(A: float, b: float, Ea: float, plasma: bool, equation: str, note: str, commented: bool = False, source: None | str = None, nist_url: None | str = None, umist_url: None | str = None, temperature_range: None | tuple[float, float] = None, see_also: None | str = None) → str#

Convert a reaction rate constant to Cantera format.

Parameters:

  • A (float) – Pre-exponential factor.

  • b (float) – Temperature exponent [-].

  • Ea (float) – Activation energy [K].

  • plasma (bool) – If True, the reaction is a plasma reaction.

  • equation (str) – Reaction equation.

  • note (str) – Note to add to the reaction.

  • commented (bool, optional) – If True, the reaction is commented, by default False.

  • source (None or str, optional) – Source of the reaction, by default None.

  • umist_url (None or str, optional) – URL to the [UMIST] database, by default None.

  • temperature_range (None or tuple of float, optional) – Temperature range validity of the reaction, by default None.

  • see_also (None or str, optional) – URL to a related reaction, by default None.

Returns:

Reaction rate constant in Cantera format.

Return type:

str

rizer.misc.ct_utils.get_fake_reverse_reaction(reaction: cantera.Reaction, gas: cantera.Solution) → cantera.Reaction#

Generate a fake reverse reaction for unit conversion purposes.

For non-reversible reactions, Cantera does not automatically create reverse reactions. This function generates a synthetic reverse reaction to allow proper unit conversion of the preexponential factor A using Cantera’s rate_coeff_units method.

Parameters:

  • reaction (cantera.Reaction) – Cantera reaction object (can be forward or reversible).

  • gas (cantera.Solution) – Cantera gas object containing the reaction mechanism.

Returns:

A synthetic reverse reaction with flipped reactants and products.

Return type:

cantera.Reaction

Notes

This function creates a thermodynamically meaningless reaction (reactants and products are swapped) purely for determining the correct units of the rate constant for the reverse direction. The fake reaction is not intended for any thermodynamic calculations.

Examples

>>> import cantera as ct
>>> gas = ct.Solution("gri30.yaml")
>>> reaction = gas.reactions()[0]  # 2 O + M <=> O2 + M
>>> fake_rev = get_fake_reverse_reaction(reaction, gas)
>>> print(fake_rev.equation)
O2 + M <=> 2 O + M
rizer.misc.ct_utils.to_reverse_reaction_format(forward_reaction: cantera.Reaction, gas: cantera.Solution, note: str) → str#
rizer.misc.ct_utils.return_x_y_from_hydrocarbon(hydrocarbon: str) → tuple[int, int]#

Return the number of carbon atoms and hydrogen atoms in a hydrocarbon.

Parameters:

hydrocarbon (str) – The name of the hydrocarbon, like CH4 or C2H6.

Returns:

The number of carbon atoms and hydrogen atoms in the hydrocarbon.

Return type:

tuple of int, int

Examples

>>> return_x_y_from_hydrocarbon("CH4")
(1, 4)
>>> return_x_y_from_hydrocarbon("C2H6")
(2, 6)
>>> return_x_y_from_hydrocarbon("C3H8")
(3, 8)
>>> return_x_y_from_hydrocarbon("C2")
(2, 0)
>>> return_x_y_from_hydrocarbon("C")
(1, 0)
>>> return_x_y_from_hydrocarbon("C2H")
(2, 1)
>>> return_x_y_from_hydrocarbon("C2H2")
(2, 2)
>>> return_x_y_from_hydrocarbon("H2")
(0, 2)
>>> import pytest
>>> with pytest.raises(ValueError):
...     return_x_y_from_hydrocarbon("N2")
...
>>> with pytest.raises(ValueError):
...     return_x_y_from_hydrocarbon("C2H2^+")
...
class rizer.misc.ct_utils.CanteraStringInputThermo#
model: str#
temperature_ranges: list[float]#
data: list[list[float]]#
class rizer.misc.ct_utils.CanteraStringInput#
name: str#
composition: str#
thermo: CanteraStringInputThermo#
notes: str#
rizer.misc.ct_utils.from_ct_dict_to_ct_str(ct_dict: CanteraStringInput) → str#

Convert a Cantera dictionary to a Cantera string.

Parameters:

ct_dict (CanteraStringInput) – A dictionary containing the NASA9 coefficients, compatible with Cantera’s YAML format.

Returns:

A string in Cantera format, that can be used in a YAML file.

Return type:

str

rizer.misc.ct_utils.partially_ionized_mole_fractions(x_e: float, background: str = 'CH4', ion: str | None = None) → str#

Cantera X string for a seeded, partially ionized plasma composition.

One electron per singly-charged ion, so the charge balance the kinetics inherits starts satisfied. Seeding electrons alone makes a quasi-neutrality check fail on the initial condition rather than on anything a solver did, which is a failure mode that reads as a solver bug.

The mixture this returns is exactly electrically neutral, not quasi-neutral: the ion and electron mole fractions are equal by construction. What varies is how much of it is ionized, which is what x_e sets.

Parameters:

  • x_e (float) – Electron mole fraction [-]. The ion takes the same value and the background makes up the remainder, 1 - 2 * x_e.

  • background (str, optional) – Neutral species carrying the balance.

  • ion (str, optional) – Singly-charged ion. Defaults to background + "+", which is the ionized form of the background for every mechanism this is used with.

Returns:

X composition string, e.g. "CH4:9.9e-01, e-:5.0e-03, CH4+:5.0e-03".

Return type:

str

Examples

>>> partially_ionized_mole_fractions(1.0e-3)
'CH4:9.980000e-01, e-:1.000000e-03, CH4+:1.000000e-03'