Add: support partial freezing of species in equilibrium calculations

[AlbertoCuadra]

Description

Currently, the Combustion Toolbox enforces a binary treatment of species: each species is either fully reactive or fully inert. There is no mechanism to prescribe that only a fraction of a species participates in the chemical equilibrium calculation while the remaining portion is retained as frozen in the composition.

Proposed capability

Introduce a new feature that allows users to define partial freezing of a species by assigning a reactive fraction and a frozen fraction within the same species entry, without resorting to database-level workarounds.

This would require extending internal logic in the following subpackages:

• +core — modify the chemical system accordingly through the ChemicalSystem object. If is a fuel species it has to be considered in the calculation of the equivalence ratio or in the definition of the new composition provided the equivalence ratio. Therefore, Mixture class will be also affected.
• +equilibrium —in the same fashion as with inert species, we have to extend the equilibrium formulation to handle split reactive/inert contributions for a single species entry.

Use case

This feature is particularly relevant in scenarios where reaction progress is physically limited, such as:

• Dissociation-limited combustion
• Evaporation-controlled fuel injection

In these cases, a portion of a fuel or intermediate species should remain unreacted by constraint, rather than by chemical equilibrium.

Temporary workaround

Until partial freezing is natively supported, the following workaround can be used: duplicate the species in the database (e.g., H2 and H2frozen) and assign the duplicate to the inert pool. The original species participates in the equilibrium calculation, while the duplicated one remains frozen. This effectively emulates split reactivity but requires manual database modification and is not intended as a long-term solution --- although it is relatively straightforward to implement in practice. For instance:

% Import packages
import combustiontoolbox.databases.NasaDatabase
import combustiontoolbox.core.*
import combustiontoolbox.equilibrium.*

% Get Nasa database
DB = NasaDatabase();
DB.species.H2frozen = DB.species.H2;
DB.species.H2frozen.name = 'H2frozen';

% Define chemical system
system = ChemicalSystem(DB);

% Initialize mixture
mix = Mixture(system);

% Define chemical state without inert species
set(mix, {'H2'}, 'fuel', 1);
set(mix, {'N2', 'O2', 'Ar', 'CO2'}, 'oxidizer', [78.084, 20.9476, 0.9365, 0.0319] / 20.9476);
set(mix, {'H2frozen'}, 'inert', 1);

% Define properties
mix = setProperties(mix, 'temperature', 500, 'pressure', 1 * 1.01325, 'equivalenceRatio', 0.5);

% Initialize solver
solver = EquilibriumSolver('problemType', 'TP’);

% Solve problems
solver.solveArray(mix);

Important note

While the workaround correctly enforces that a portion of H₂ remains frozen and does not affect the equilibrium composition (since frozen species are excluded from the Gibbs minimization loop), the entropy of the mixture will not be thermodynamically consistent. This occurs because H₂ and H_2,frozen are treated as two distinct chemical entities in the entropy of mixing term, which artificially increases the mixture entropy. Consequently, any entropy-derived quantity — such as the Gibbs free energy $G = H - TS$, will reflect this bias.

This behavior is acceptable only under the frozen-species assumption, where one is primarily concerned with composition and bulk thermodynamic variables (e.g., $T, p, \rho, h$). However:

• To maintain thermodynamic consistency, internal adjustments are required in the +core subpackage, specifically in the routine that computes the entropy of mixing, ensuring that duplicated species are grouped when computing the total entropy.
• The workaround cannot be applied if the duplicated species are allowed to react, since that would alter the chemical potentials of the mixture, shift the global Gibbs minimum, and thus change the equilibrium state itself.