Thermodynamic Properties#

These classes are used to describe the thermodynamic state of a system.

Caution

The MATLAB toolbox is an experimental part of the Cantera API and may be changed without notice. It includes breaking changes from the legacy MATLAB API. While almost all features of the legacy MATLAB API are implemented, the toolbox does not include all functionality available for the C++ and Python interfaces.

Phases#

ThermoPhase#

class ct.ThermoPhase#

Bases: handle

ThermoPhase Class.

Instance of class ct.ThermoPhase associated with a ct.Solution object. The constructor is called whenever a new ct.Solution is instantiated and cannot be used directly.

Parameters:: id – Integer ID of the solution holding the ct.ThermoPhase object.

Create a ct.ThermoPhase object.

Property Summary

D#: Density depending on the basis [kmol/m³ or kg/m³].

DP#: Get/Set density [kg/m³ or kmol/m³] and pressure [Pa].

DPQ#: Get density [kg/m³ or kmol/m³], pressure [Pa], and vapor fraction.

DPX#: Get/Set density [kg/m³ or kmol/m³], pressure [Pa], and mole fractions.

DPY#: Get/Set density [kg/m³ or kmol/m³], pressure [Pa], and mass fractions.

G#: Gibbs free energy depending on the basis [J/kmol or J/kg].

H#: Enthalpy depending on the basis [J/kmol or J/kg].

HP#: Get/Set enthalpy [J/kg or J/kmol] and pressure [Pa].

HPQ#: Get enthalpy [J/kg or J/kmol], pressure [Pa], and vapor fraction.

HPX#: Get/Set enthalpy [J/kg or J/kmol], pressure [Pa], and mole fractions.

HPY#: Get/Set enthalpy [J/kg or J/kmol], pressure [Pa], and mass fractions.

P#: Pressure [Pa].

PQ#: Get/Set pressure [Pa] and vapor fraction of a two-phase state.

PV#: Get/Set pressure [Pa] and specific volume [m³/kg or m³/kmol].

PVX#: Get/Set pressure [Pa], specific volume [m³/kg or m³/kmol], and mole fractions.

PVY#: Get/Set pressure [Pa], specific volume [m³/kg or m³/kmol], and mass fractions.

Q#: Vapor fraction of the phase.

S#: Entropy depending on the basis [J/kmol/K or J/kg/K].

SH#: Get/Set entropy [J/kg/K or J/kmol/K] and enthalpy [J/kg or J/kmol].

SHX#: Get/Set entropy [J/kg/K or J/kmol/K], enthalpy [J/kg or J/kmol], and mole fractions.

SHY#: Get/Set entropy [J/kg/K or J/kmol/K], enthalpy [J/kg or J/kmol], and mass fractions.

SP#: Get/Set entropy [J/kg/K or J/kmol/K] and pressure [Pa].

SPQ#: Get entropy [J/kg/K or J/kmol/K], pressure [Pa], and vapor fraction.

SPX#: Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mole fractions.

SPY#: Get/Set entropy [J/kg/K or J/kmol/K], pressure [Pa], and mass fractions.

ST#: Get/Set entropy [J/kg/K or J/kmol/K] and temperature [K].

STX#: Get/Set entropy [J/kg/K or J/kmol/K], temperature [K], and mole fractions.

STY#: Get/Set entropy [J/kg/K or J/kmol/K], temperature [K], and mass fractions.

SV#: Get/Set entropy [J/kg/K or J/kmol/K] and specific volume [m³/kg or m³/kmol].

SVQ#: Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m³/kg or m³/kmol], and vapor fraction.

SVX#: Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m³/kg or m³/kmol], and mole fractions.

SVY#: Get/Set entropy [J/kg/K or J/kmol/K], specific volume [m³/kg or m³/kmol], and mass fractions.

T#: Temperature [K].

TD#: Get/Set temperature [K] and density [kg/m³ or kmol/m³].

TDQ#: Get temperature [K], density [kg/m³ or kmol/m³], and vapor fraction.

TDX#: Get/Set temperature [K], density [kg/m³ or kmol/m³], and mole fractions.

TDY#: Get/Set temperature [K], density [kg/m³ or kmol/m³], and mass fractions.

TH#: Get/Set temperature [K] and enthalpy [J/kg or J/kmol].

THX#: Get/Set temperature [K], enthalpy [J/kg or J/kmol], and mole fractions.

THY#: Get/Set temperature [K], enthalpy [J/kg or J/kmol], and mass fractions.

TP#: Get/Set temperature [K] and pressure [Pa].

TPQ#: Get temperature [K], pressure [Pa], and vapor fraction.

TPX#: Get/Set temperature [K], pressure [Pa], and mole fractions.

TPY#: Get/Set temperature [K], pressure [Pa], and mass fractions.

TQ#: Get/Set temperature [K] and vapor fraction of a two-phase state.

TV#: Get/Set temperature [K] and specific volume [m³/kg or m³/kmol].

TVX#: Get/Set temperature [K], specific volume [m³/kg or m³/kmol], and mole fractions.

TVY#: Get/Set temperature [K], specific volume [m³/kg or m³/kmol], and mass fractions.

U#: Internal energy depending on the basis [J/kmol or J/kg].

UP#: Get/Set internal energy [J/kg or J/kmol] and pressure [Pa].

UPX#: Get/Set internal energy [J/kg or J/kmol], pressure [Pa], and mole fractions.

UPY#: Get/Set internal energy [J/kg or J/kmol], pressure [Pa], and mass fractions.

UV#: Get/Set internal energy [J/kg or J/kmol] and specific volume [m³/kg or m³/kmol].

UVQ#: Get internal energy [J/kg or J/kmol], specific volume [m³/kg or m³/kmol], and vapor fraction.

UVX#: Get/Set internal energy [J/kg or J/kmol], specific volume [m³/kg or m³/kmol], and mole fractions.

UVY#: Get/Set internal energy [J/kg or J/kmol], specific volume [m³/kg or m³/kmol], and mass fractions.

V#: Basis-dependent specific volume [m³/kmol or m³/kg]

VH#: Get/Set volume [m³/kg or m³/kmol] and enthalpy [J/kg or J/kmol].

VHX#: Get/Set specific volume [m³/kg or m³/kmol], enthalpy [J/kg or J/kmol], and mole fractions.

VHY#: Get/Set specific volume [m³/kg or m³/kmol], enthalpy [J/kg or J/kmol], and mass fractions.

X#: Mole fractions.

Y#: Mass fractions.

atomicWeights#: Atomic weights of the elements [kg/kmol].

basis#

Basis

>> tp.basis = b

Determines whether intensive thermodynamic properties are treated on a mass (per kg) or molar (per kmol) basis. This affects the values returned by the properties H, U, S, G, V, Density, Cv, and Cp, as well as the values used with the state-setting properties such as HPX and UV.

Parameters:: b – String. Can be mole / molar / Molar / Mole or mass / Mass.

charges#: Species charges in units of the elementary charge.

chemicalPotentials#: Chemical potentials of the species [J/kmol].

concentrations#: Concentrations of the species [kmol/m³ for bulk phases; kmol/m² for surface phases].

cp#: Basis-dependent specific heat at constant pressure and composition [J/kmol/K or J/kg/K].

critDensity#: Critical density [kg/m³].

critPressure#: Critical pressure [Pa].

critTemperature#: Critical temperature [K].

cv#: Basis-dependent specific heat at constant volume and composition [J/kmol/K or J/kg/K].

electricPotential#: Electric potential [V].

electrochemicalPotentials#: Electrochemical potentials of the species [J/kmol].

eosType#: Type of equation of state.

isIdealGas#: A flag indicating whether the phase is an ideal gas.

isothermalCompressibility#: Isothermal compressibility [1/Pa].

massDensity#: Mass basis density [kg/m³].

maxTemp#

Maximum temperature for which thermodynamic parameter fits are valid for all species.

The parameterizations used to represent the temperature-dependent species thermodynamic properties are generally only valid in some finite temperature range, which may be different for each species in the phase.

See also: maxTemp

molarDensity#: Molar basis density [kmol/m³].

molecularWeights#: Molecular weights [kg/kmol] of the species.

nElements#: Number of elements in the phase.

nSpecies#: Number of species in the phase.

name#: Name of the phase.

partialMolarCp#: Partial molar heat capacities for the species in the mixture [J/kmol/K].

partialMolarEnthalpies#: Partial molar enthalpies for the species in the mixture [J/kmol].

partialMolarEntropies#: Partial molar entropies for the species in the mixture [J/kmol/K].

partialMolarIntEnergies#: Partial molar internal energies for the species in the mixture [J/kmol].

partialMolarVolumes#: Partial molar volumes for the species in the mixture [m³/kmol].

refPressure#: Reference pressure [Pa] for standard-state.

satPressure#: Saturation pressure [Pa] at the current temperature

satTemperature#: Saturation temperature [K] at the current pressure

soundSpeed#

Speed of sound [m/s]

>> c = tp.soundspeed

If the phase is an ideal gas, the speed of sound is calculated by:

\[c = \sqrt{\gamma * R * T}\]

where \(\gamma\) is the ratio of specific heats, \(R\) is the specific gas constant, and \(T\) is the temperature. If the phase is not an ideal gas, the speed of sound is calculated by

\[c = \sqrt{\left(\frac{\partial p}{\partial \rho}\right)_s}\]

where \(p\) is the pressure and \(\rho\) is the density, and the subscript \(s\) indicates constant entropy. This is approximated by slightly increasing the density at constant entropy and computing the change in pressure.

\[c = \sqrt{\frac{p_1 - p_0}{\rho_1-\rho_0}}\]

speciesNames#: Cell array of species names

thermalExpansionCoeff#: Thermal expansion coefficient [1/K].

tpID#: ID of the ThermoPhase object.

Method Summary

display()#

elementIndex(name)#

Index of an element given its name

>> k = tp.elementIndex(name)

The index is an integer assigned to each element in sequence as it is read in from the input file.

If name is a single string, the return value will be a integer containing the corresponding index. If it is an cell array of strings, the output will be an array of the same shape containing the indices.

NOTE: In keeping with the conventions used by Matlab, this method returns 1 for the first element. In contrast, the corresponding method elementIndex in the Cantera C++ and Python interfaces returns 0 for the first element, 1 for the second one, etc.

>> ic = gas.elementIndex('C');
>> ih = gas.elementIndex('H');

Parameters:: name – String or cell array of strings of elements to look up
Returns:: Integer or vector of integers of element indices

elementalMassFraction(element)#

Elemental mass fraction in gas object

>> elMassFrac = tp.elementalMassFraction(element)

The elemental mass fraction in a gas object is calculated using the following equation:

\[elMassFrac = \sum_{1}^{nSpecies} \frac{nAtoms(k, m)*Mel(m)*Y(k)}{mw(k)}\]

where \(nAtoms(k, m)\) is the number of atoms of element \(m\) in species \(k\); \(Mel(m)\) is the atomic weight of element \(m\); \(Y(k)\) is the mass fraction of species \(k\); and \(mw(k)\) is the molecular weight of species \(k\).

Parameters:: element – String representing the element name.
Returns:: Elemental mass fraction within a gas object.

equilibrate(xy, solver, rtol, maxsteps, maxiter, loglevel)#

Set the phase to a state of chemical equilibrium

>> tp.equilibrate(xy, solver, rtol, maxsteps, maxiter, loglevel)

Parameters:

XY – A two-letter string, which must be one of the set ['TP','TV','HP','SP','SV','UV','UP'], indicating which pair of properties should be held constant. Not all of the properties to be held constant are available with all of the solvers.
solver – Specifies the equilibrium solver to use. Choices are ‘element_potential’ (fast solver using the element potential method), ‘gibbs’ (slower but more robust Gibbs minimization solver), ‘vcs’ (VCS algorithm). For the default ‘auto’ setting, the fast solver will be tried first, then if it fails the Gibbs minimization solver will be tried.
rtol – The relative error tolerance.
maxsteps – Maximum number of steps in composition to take to find a converged solution.
maxiter – For the Gibbs minimization solver only, this specifies the number of ‘outer’ iterations on T or P when some property pair other than TP is specified.
loglevel – Set to a value > 0 to write diagnostic output. Larger values generate more detailed information.

massFraction(species)#

Get the mass fraction of one or a list of species

>> y = tp.massFraction(species)

Parameters:: species – String or cell array of strings of species whose mass fraction is desired
Returns:: Scalar or vector double mass fractions

moleFraction(species)#

Get the mole fraction of one or a list of species

>> x = tp.moleFraction(species)

Parameters:: species – String or cell array of strings of species whose mole fraction is desired
Returns:: Scalar or vector double mole fractions

nAtoms(species, element)#

Number of atoms of an element in a species

>> n = tp.nAtoms(k,m)

Parameters:

species – Species name or index
element – Element name or index

Returns:

Number of atoms of the specified element in the species.

report(threshold)#

setEquivalenceRatio(phi, fuelComp, oxComp)#: Set the mixture composition according to the equivalence ratio.

speciesIndex(name)#

Index of a species given the name

>> k = tp.speciesIndex(name)

The index is an integer assigned to each species in sequence as it is read in from the input file.

>> ich4 = gas.speciesIndex('CH4');
>> iho2 = gas.speciesIndex('HO2');

Note

In keeping with the conventions used by Matlab, this method returns 1 for the first species, 2 for the second, etc. In contrast, the corresponding method in the Cantera C++ and Python interfaces returns 0 for the first species, 1 for the second one, etc.

Parameters:: name – If name is a single string, the return value will be a integer containing the corresponding index. If it is an cell array of strings, the output will be an array of the same shape containing the indices.
Returns:: Scalar or array of integers

speciesName(k)#

Name of one or multiple species given the index

>> k = tp.speciesName(k)

Parameters:: k – Scalar of array of integers of NOTE: In keeping with the conventions used by Matlab, the indices of species start with 1 for the first, then 2 for the second, etc.
Returns:: Cell array of strings of species inquired.

Mixture#

class ct.Mixture(phases)#

Bases: handle

Mixture Class

>> m = ct.Mixture(phases)

Class ct.Mixture represents mixtures of one or more phases of matter. To construct a mixture, supply a cell array of phases and mole numbers

>> gas = ct.Solution('gas.yaml');
>> graphite = ct.Solution('graphite.yaml');
>> mix = ct.Mixture({gas, 1.0; graphite, 0.1});

Phases may also be added later using the addPhase method

>> water = ct.Solution('water.yaml');
>> mix.addPhase(water, 3.0);

Note that the objects representing each phase compute only the intensive state of the phase - they do not store any information on the amount of this phase. Mixture objects, on the other hand, represent the full extensive state.

Mixture objects are “lightweight” in the sense that they do not store parameters needed to compute thermodynamic or kinetic properties of the phases. These are contained in the (‘heavyweight’) phase objects. Multiple mixture objects may be constructed using the same set of phase objects. Each one stores its own state information locally, and synchronizes the phase objects whenever it requires phase properties.

Parameters:: phases – Cell array of phases and mole numbers.

Create a ct.Mixture object.

Property Summary

P#: Pressure [Pa].

T#: Temperature [K].

chemPotentials#: Chemical potentials [J/kmol] of species in the mixture.

mixID#

nElements#: Number of elements in a mixture.

nPhases#: Number of phases in a mixture.

nSpecies#: Number of species in a mixture.

phases#: Phases in the mixture

Method Summary

addPhase(phase, moles)#

Add a phase to a mixture.

>> m.addPhase(phase, moles)

Parameters:

phase – Instance of class ct.ThermoPhase which should be added.
moles – Number of moles [kmol] of the phase to be added to this mixture.

delete()#: Delete the ct.Mixture object.

display()#: Display the state of the mixture on the terminal.

elementIndex(name)#

Index of an element.

>> n = m.elementIndex(name)

Parameters:: name – Name of the element whose index is desired.
Returns:: Index of element with name name.

Note: In keeping with the conventions used by Matlab, the indices start from 1 instead of 0 as in Cantera C++ and Python interfaces.

elementMoles(e)#

Number of moles [kmol] of an element in a mixture.

>> moles = m.elementMoles(e)

Parameters:: e – Integer element number.
Returns:: Moles of element number ‘e’. If input ‘e’ is empty, return moles of every element in the mixture.

equilibrate(XY, solver, rtol, maxsteps, maxiter, estimate_equil)#

Set the mixture to a state of chemical equilibrium.

>> m.equilibrate(XY, solver, rtol, maxsteps, maxiter, estimate_equil)

Parameters:

XY – Two-letter string specifying the two properties to hold fixed. Currently, 'TP', 'HP', 'TV', and 'SP' are implemented. Default: 'TP'.
solver – Name of the solver to be used to equilibrate the phase. If solver = ‘element_potential’, the ChemEquil element potential solver will be used. If solver = ‘vcs’, the VCS solver will be used. If solver = ‘gibbs’, the MultiPhaseEquil solver will be used. If solver = ‘auto’, the solvers will be tried in order if the initial solver(s) fail. Default: 'auto'.
err – Error tolerance. Iteration will continue until \(\Delta\mu)/RT\) is less than this value for each reaction. Default: 1.0e-9. Note that this default is very conservative, and good equilibrium solutions may be obtained with larger error tolerances.
maxsteps – Maximum number of steps to take while solving the equilibrium problem for specified T and P. Default: 1000.
maxiter – Maximum number of temperature and/or pressure iterations. This is only relevant if a property pair other than (T,P) is specified. Default: 200.
estimate_equil – For MultiPhaseEquil solver, an integer indicating whether the solver should estimate its own initial condition. If 0, the initial mole fraction vector in the ThermoPhase object is used as the initial condition. If 1, the initial mole fraction vector is used if the element abundances are satisfied. If -1, the initial mole fraction vector is thrown out, and an estimate is formulated. Default: 0.

Returns:

The error in the solution.

nAtoms(e)#

Number of atoms of an element in a mixture.

>> n = m.nAtoms(e)

Parameters:: e – Index of element.
Returns:: Number of atoms for element e.

Note: In keeping with the conventions used by Matlab, the indices start from 1 instead of 0 as in Cantera C++ and Python interfaces.

phaseMoles(n)#

Number of moles [kmol] of a phase in a mixture.

>> moles = m.phaseMoles(n)

Parameters:: n – Integer phase number.
Returns:: Moles of element number ‘n’. If input ‘n’ is empty, return moles of every element in the mixture.

setPhaseMoles(n, moles)#

Set the number of moles [kmol] of a phase in a mixture.

>> m.setPhaseMoles(n, moles)

Parameters:

n – Phase number in the input.
moles – Number of moles to add.

setSpeciesMoles(moles)#

Set the moles [kmol] of the species.

>> m.setSpeciesMoles(moles)

Set the moles of multiple species. The moles may be specified either as a string, or as an vector. If a vector is used, it must be dimensioned at least as large as the total number of species in the mixture. Note that the species may belong to any phase, and unspecified species are set to zero.

>> mix.setSpeciesMoles('C(s):1.0, CH4:2.0, O2:0.2');

Parameters:: moles – Vector or string specifying the moles of species.

speciesIndex(k, p)#

Index of a species in a mixture.

>> n = m.speciesIndex(k, p)

Parameters:: name – Name of the species whose index is desired.
Returns:: Index of species with name name.

Note: In keeping with the conventions used by Matlab, the indices start from 1 instead of 0 as in Cantera C++ and Python interfaces.

speciesMoles(k)#

Number of moles [kmol] of a species in a mixture.

>> moles = m.speciesMoles(k)

Parameters:: k – Integer species number.
Returns:: Moles of species number ‘k’. If input ‘k’ is empty, return moles of every species in the mixture