bloc.ctutils#

Util functions to handle the Cantera package.

Attributes#

fuel

MECHANISM_SOLUTION_CACHE

Functions#

draw_network_and_render(sim[, path])

Draw the network structure and render it as a PNG file.

collect_all_reactors_and_reservoirs(sim)

Collect all Reactors and Reservoirs in a Network.

heating_values(fuel[, mechanism, return_unit, verbose])

Return the Lower & Higher heating values (LHV, HHV) for the specified fuel, in J/kg.

get_STP_properties_IUPAC(g)

Get density and enthalpy under Standard Temperature & Pressure (STP).

get_NTP_properties_NIST(g)

Get density and enthalpy under Normal Temperature & Pressure (NTP).

get_gas_phase_composition(gas[, solid_sp, n_C_min])

Return the gas phase composition by removing solid species and renormalising the mole/mass fractions.

get_gas_species(gas[, solid_sp, n_C_min])

Return a list of gaseous species from the gas object.

get_gas_phase_density(gas[, solid_sp, n_C_min])

Return the corrected density of the gas object, removing the solid species.

get_reactor_by_name(sim, name)

Get a reactor from a ReactorNet by name.

get_cached_solution(mechanism_source)

Get or create a cached Solution object for a mechanism.

get_property_at_conditions(mechanism_source, T, P, ...)

Calculate thermodynamic property at specific conditions.

get_cached_solution_at_state(mechanism_source, T, P, X)

Get a cached Solution object configured to specific thermodynamic state.

get_property_at_conditions_reuse(existing_gas, T, P, ...)

Calculate thermodynamic property at specific conditions by reusing existing Solution.

Module Contents#

bloc.ctutils.draw_network_and_render(sim, path=None)#

Draw the network structure and render it as a PNG file.

If path is None then PNG file path is the original file with _sim.png extension.

See https://cantera.org/stable/python/zerodim.html#cantera.ReactorNet.draw

Example

from bloc.ctutils import draw_network_and_render
# add your simulation code
# ``sim`` is the Cantera simulation object
draw_network_and_render(sim)
bloc.ctutils.collect_all_reactors_and_reservoirs(sim)#

Collect all Reactors and Reservoirs in a Network.

Parameters:

sim (cantera.ReactorNet)

Return type:

set of cantera.Reactor

bloc.ctutils.heating_values(fuel, mechanism=None, return_unit='J/kg', verbose=False)#

Return the Lower & Higher heating values (LHV, HHV) for the specified fuel, in J/kg.

References: https://cantera.org/examples/jupyter/thermo/heating_value.ipynb.html

Parameters:

  • fuel (cantera.Solution or cantera.Species) – Cantera Solution or Species object representing the fuel.

  • mechanism (str, optional) – kinetic mechanism including the thermodynamic data used to do the calculations. If not given, uses the mechanism of the fuel.

  • return_unit (str, optional) – unit of the returned values, default is “J/kg”. Other units are not implemented yet.

  • verbose (bool, optional) – If True, print verbose output.

Returns:

  • tuple of float – (LHV, HHV) in the specified unit (default is J/kg). LHV is the lower heating value, HHV is the higher heating value.

  • If O2 is not defined in mechanism, returns nan.

Examples

::

import cantera import as ct from bloc.ctutils import heating_values

g = ct.Solution(“gri30.yaml”) g.TPX = 273.15, 1e5, “CH4:1” # °C, Pa, mole fraction lhv, hhv = heating_values(g) # J/kg

Notes

@Jean: Warning, according to Wikipedia, there are several definition of LHV. Here, we assume that water condensation energy is not recovered, but heat is recovered down to 25°C. Another widespread defintion considers that the products are cooled to 150°C –> no water condensation, nor heat recovery below 150°C.

bloc.ctutils.get_STP_properties_IUPAC(g)#

Get density and enthalpy under Standard Temperature & Pressure (STP).

Here STP is defined as :

  • 0°C (273.15 K), 1 bar (100 kPa), according to STP by IUPAC (>=1982)

It should not be confused with :

  • 0°C (273.15 K), 1 atm (101.325 kPa): as in STP by IUPAC (before 1982) and as in

    DIN 1343, used as the base value for defining the standard cubic meter.

  • 15°C (288.15 K), 1 atm (101.325 kPa): as in ISO 2533 conditions

  • 20°C (293.15 K), 1 atm (101.325 kPa), as in Normal (NTP) conditions by NIST

References

https://en.wikipedia.org/wiki/Standard_temperature_and_pressure.

bloc.ctutils.get_NTP_properties_NIST(g)#

Get density and enthalpy under Normal Temperature & Pressure (NTP).

Here NTP is defined as :

  • 20°C (293.15 K), 1 atm (101.325 kPa), according to NTP by NIST

It should not be confused with :

  • 0°C (273.15 K), 1 bar (100 kPa), according to STP by IUPAC (>=1982)

  • 0°C (273.15 K), 1 atm (101.325 kPa): as in STP by IUPAC (before 1982) and as in

    DIN 1343, used as the base value for defining the standard cubic meter.

  • 15°C (288.15 K), 1 atm (101.325 kPa): as in ISO 2533 conditions

References

https://en.wikipedia.org/wiki/Standard_temperature_and_pressure.

bloc.ctutils.get_gas_phase_composition(gas, solid_sp=['C(s)', 'C(soot)', 'CSOLID'], n_C_min=300)#

Return the gas phase composition by removing solid species and renormalising the mole/mass fractions.

Parameters:

  • gas (cantera.Solution) – The gas phase object from Cantera.

  • solid_sp (list of str, optional) – List of solid species to remove from the gas phase composition. Default is [“C(s)”, “C(soot)”, “CSOLID”].

  • n_C_min (int, optional) – Minimum number of carbon atoms to consider a species as solid. Default is 300.

Returns:

A pandas Series containing the gas phase composition, sorted by species name in descending order.

Return type:

pd.Series

bloc.ctutils.get_gas_species(gas, solid_sp=['C(s)', 'C(soot)', 'CSOLID'], n_C_min=300)#

Return a list of gaseous species from the gas object.

Parameters:

  • gas (cantera.Solution) – The gas object containing gaseous species and soot.

  • solid_sp (list of str, optional) – List of solid species to consider. Default is [“C(s)”, “C(soot)”, “CSOLID”].

  • n_C_min (int, optional) – Minimum number of carbon atoms to consider a species as solid. Default is 300. This is used as a second filter to identify solid carbon species. A specie is considered solid if it satisfies one criterium (s in solid_sp) OR the other (n_C >= n_C_min).

Returns:

A list of gaseous species names (i.e., not solid carbon species).

Return type:

list of str

bloc.ctutils.get_gas_phase_density(gas, solid_sp=['C(s)', 'C(soot)', 'CSOLID'], n_C_min=300)#

Return the corrected density of the gas object, removing the solid species.

Parameters:

  • gas (cantera.Solution) – The gas object containing gaseous species and soot. Works with states[i].

  • solid_sp (list of str, optional) – List of solid species to consider. Default is [“C(s)”, “C(soot)”, “CSOLID”].

  • n_C_min (int, optional) – Minimum number of carbon atoms to consider a species as solid. Default is 300. This is used as a second filter to identify solid carbon species. A specie is considered solid if it satisfies one criterium (s in solid_sp) OR the other (n_C >= n_C_min).

Returns:

The corrected density of the gas object, removing the solid species.

Return type:

float

bloc.ctutils.fuel#
bloc.ctutils.get_reactor_by_name(sim, name)#

Get a reactor from a ReactorNet by name.

Parameters:

  • sim (ct.ReactorNet) – The reactor network simulation

  • name (str) – Name of the reactor to find

Returns:

The reactor with the given name, or None if not found

Return type:

ct.Reactor or None

Examples

>>> import cantera as ct
>>> gas = ct.Solution("gri30.yaml")
>>> reactor = ct.IdealGasConstPressureReactor(gas, name="test_reactor")
>>> sim = ct.ReactorNet([reactor])
>>> found_reactor = get_reactor_by_name(sim, "test_reactor")
>>> print(found_reactor.name)
test_reactor
bloc.ctutils.MECHANISM_SOLUTION_CACHE#
bloc.ctutils.get_cached_solution(mechanism_source)#

Get or create a cached Solution object for a mechanism.

This function provides centralized access to the MECHANISM_SOLUTION_CACHE, creating new Solution objects only when needed and reusing existing ones for performance optimization.

Parameters:

mechanism_source (str) – The mechanism source (e.g., ‘gri30.yaml’ or path to mechanism file)

Returns:

Cached Solution object for the mechanism

Return type:

ct.Solution

Examples

>>> gas = get_cached_solution("gri30.yaml")
>>> gas.TPX = 1000, ct.one_atm, {"H2": 1.0}
>>> print(gas.T)
1000.0
bloc.ctutils.get_property_at_conditions(mechanism_source, T, P, composition, property_name='h', use_cache=True)#

Calculate thermodynamic property at specific conditions.

This function can either use a cached Solution object (default, most efficient) or create a new temporary Solution object for each call. The cached approach uses MECHANISM_SOLUTION_CACHE to avoid object creation overhead and is recommended for most use cases.

Parameters:

  • mechanism_source (str) – The mechanism source (e.g., from gas.source)

  • T (float) – Temperature in K

  • P (float) – Pressure in Pa

  • composition (str or dict) – Composition as string (e.g., “H2:1”) or dictionary

  • property_name (str, optional) – Property to calculate. Default is “h” (enthalpy). Options: “h”, “s”, “cp”, “cv”, “density”, etc.

  • use_cache (bool, optional) – Whether to use cached Solution objects. Default is True (recommended). Set to False to create a new temporary Solution object for each call.

Returns:

The requested property value

Return type:

float

Examples

>>> import cantera as ct
>>> gas = ct.Solution("gri30.yaml")
>>> # Get enthalpy of H2 at 1000K, 1atm using cached Solution (default)
>>> h_ref = get_property_at_conditions(gas.source, 1000, ct.one_atm, "H2:1", "h")
>>> # Get enthalpy without caching (creates new Solution object)
>>> h_ref = get_property_at_conditions(
...     gas.source, 1000, ct.one_atm, "H2:1", "h", use_cache=False
... )
bloc.ctutils.get_cached_solution_at_state(mechanism_source, T, P, X)#

Get a cached Solution object configured to specific thermodynamic state.

This unified function uses the MECHANISM_SOLUTION_CACHE to avoid creating new Solution objects when configuring Solutions for plotting, post-processing, or other temporary operations.

WARNING: This function returns a mutable cached object that shares state across calls. Only use for operations where state mutation is acceptable.

SAFE USAGE: - Reactor/Reservoir creation (state is copied during instantiation) - Post-processing and visualization (single-use operations) - Final state analysis and composition extraction

UNSAFE USAGE: - Iterative property calculations (use fresh ct.Solution() instead) - Multiple property evaluations within same computational loop - Any operation requiring state isolation between calls

Parameters:

  • mechanism_source (str) – The mechanism source (e.g., from gas.source or state.source)

  • T (float) – Temperature in K

  • P (float) – Pressure in Pa

  • X (dict or array) – Composition as dictionary or array

Returns:

A cached Solution object configured to the specified state. WARNING: This object is shared across all calls with the same mechanism.

Return type:

ct.Solution

Examples

>>> # SAFE: Reactor creation (state copied)
>>> gas_upstream = get_cached_solution_at_state(mechanism, T, P, X)
>>> reservoir = ct.Reservoir(gas_upstream)  # Safe - state copied

>>> # SAFE: Post-processing (single use)
>>> gas_final = get_cached_solution_at_state(
...     reactor_states.source,
...     reactor_states.T[-1],
...     reactor_states.P[-1],
...     reactor_states.X[-1],
... )
>>> Y_out = get_gas_phase_composition(gas_final).mass_fraction_dict()

>>> # UNSAFE: Property calculations (use fresh Solution instead)
>>> # gas = get_cached_solution_at_state(mechanism, T, P, X)  # DON'T DO THIS
>>> # h = gas.h  # UNSAFE - contamination risk
>>> gas = ct.Solution(mechanism)  # DO THIS INSTEAD
>>> gas.TPX = T, P, X
>>> h = gas.h  # SAFE - isolated object
bloc.ctutils.get_property_at_conditions_reuse(existing_gas, T, P, composition, property_name='h')#

Calculate thermodynamic property at specific conditions by reusing existing Solution.

This is more efficient than get_property_at_conditions as it reuses an existing Solution object, saving the overhead of creating new objects.

DEPRECATED: Use get_property_at_conditions_cached() instead for better performance and to avoid interfering with existing Solution objects.

Parameters:

  • existing_gas (ct.Solution) – An existing Solution object to temporarily modify

  • T (float) – Temperature in K

  • P (float) – Pressure in Pa

  • composition (str or dict) – Composition as string (e.g., “H2:1”) or dictionary

  • property_name (str, optional) – Property to calculate. Default is “h” (enthalpy).

Returns:

The requested property value

Return type:

float

Examples

>>> import cantera as ct
>>> gas = ct.Solution("gri30.yaml")
>>> gas.TPX = 300, ct.one_atm, "CH4:1"  # Set initial state
>>> # Get enthalpy of H2 at 1000K, 1atm (gas state will be restored)
>>> h_ref = get_property_at_conditions_reuse(gas, 1000, ct.one_atm, "H2:1", "h")
>>> # gas is back to original state: 300K, CH4:1