bloc.chem.state#

Cached Solution state management and property lookup.

Attributes#

MECHANISM_SOLUTION_CACHE

Functions#

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.chem.state.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.chem.state.MECHANISM_SOLUTION_CACHE: dict[str, cantera.Solution]#
bloc.chem.state.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.chem.state.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.chem.state.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.chem.state.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