Solution Guide

canterax.Solution is the main user-facing API. It wraps a loaded mechanism and exposes a Cantera-like ideal-gas state surface.

Constructing a solution

from canterax import Solution

gas = Solution("gri30.yaml")

Construction loads the mechanism immediately and initializes a default state:

  • temperature 300 K

  • pressure 1 atm

  • composition set to pure N2 when that species exists, otherwise the first species in the mechanism

Setting composition

Both mole and mass fractions are accepted. Strings use Cantera-style composition syntax.

gas.X = "CH4:1, O2:2, N2:7.52"
gas.Y = [0.055, 0.220, 0.725]

Canterax normalizes positive totals automatically. A non-positive total raises ValueError.

Setting thermodynamic state

The most direct state pair is TP.

gas.TP = 1200.0, 101325.0
gas.TPX = 1200.0, 101325.0, "CH4:1, O2:2, N2:7.52"

The following getter/setter pairs are implemented:

  • TP, TPX, TPY

  • HP, HPX, HPY

  • UV, UVX, UVY

  • SP, SPX, SPY

  • SV, SVX, SVY

  • TD, TDX, TDY

  • DP, DPX, DPY

Passing None in a tuple keeps the current value for that slot.

gas.TP = None, 2 * 101325.0
gas.TPX = 1500.0, None, None

Basis-aware aliases

The aliases below follow gas.basis, which can be either "mass" or "molar":

  • h

  • u

  • s

  • g

  • cp

  • cv

  • v

  • density

If you need an explicit unit basis regardless of current state, use the dedicated properties:

  • enthalpy_mass, enthalpy_mole

  • entropy_mass, entropy_mole

  • cp_mass, cp_mole

  • density_mass, density_mole

  • volume_mass, volume_mole

Scalar properties

Common properties include:

  • cp_mass, cp_mole

  • cv_mass, cv_mole

  • enthalpy_mass, enthalpy_mole

  • int_energy_mass, int_energy_mole

  • entropy_mass, entropy_mole

  • gibbs_mass, gibbs_mole

  • density_mass, density_mole

  • volume_mass, volume_mole

  • mean_molecular_weight

  • viscosity

  • thermal_conductivity

Species-level arrays

Canterax exposes the same kinds of standard-state and partial molar arrays users commonly inspect in Cantera:

  • standard_cp_R

  • standard_enthalpies_RT

  • standard_entropies_R

  • standard_int_energies_RT

  • standard_gibbs_RT

  • partial_molar_cp

  • partial_molar_enthalpies

  • partial_molar_entropies

  • partial_molar_int_energies

  • chemical_potentials

  • net_production_rates

These are returned as NumPy arrays.

Metadata and helper methods

Useful helpers include:

  • species_names, element_names

  • n_species, n_reactions, n_elements

  • molecular_weights, atomic_weights

  • species_name(k), species_index(name)

  • element_name(m), element_index(name)

  • n_atoms(species, element)

  • mass_fraction_dict(threshold=0.0)

  • mole_fraction_dict(threshold=0.0)

Practical notes

  • Solution is intentionally stateful and mutating, like Cantera’s Python API.

  • Composition setters accept strings, sequences, and arrays.

  • Many internal computations use JAX arrays, but user-facing property getters typically return Python scalars or NumPy arrays.

  • The current implementation targets ideal-gas mechanisms only.