Reaktoro  v2.0.0 A unified framework for modeling chemically reactive systems
EquilibriumSpecs Class Reference

The class used to define conditions to be satisfied at chemical equilibrium. More...

#include <EquilibriumSpecs.hpp>

## Public Member Functions

EquilibriumSpecs (const ChemicalSystem &system)
Construct an EquilibriumSpecs object.

auto temperature () -> void
Specify that the temperature of the system at chemical equilibrium is given. More...

auto pressure () -> void
Specify that the pressure of the system at chemical equilibrium is given. More...

auto volume () -> void
Specify that the volume of the system at chemical equilibrium is given. More...

auto internalEnergy () -> void
Specify that the internal energy of the system at chemical equilibrium is given. More...

auto enthalpy () -> void
Specify that the enthalpy of the system at chemical equilibrium is given. More...

auto gibbsEnergy () -> void
Specify that the Gibbs energy of the system at chemical equilibrium is given. More...

auto helmholtzEnergy () -> void
Specify that the Helmholtz energy of the system at chemical equilibrium is given. More...

auto entropy () -> void
Specify that the entropy of the system at chemical equilibrium is given. More...

auto charge () -> void
Specify that the electric charge at chemical equilibrium is given.

auto elementAmount (const StringOrIndex &element) -> void
Specify that the amount of an element at chemical equilibrium is given. More...

auto elementAmountInPhase (const StringOrIndex &element, const StringOrIndex &phase) -> void
Specify that the amount of an element in a phase at chemical equilibrium is given. More...

auto elementMass (const StringOrIndex &element) -> void
Specify that the mass of an element at chemical equilibrium is given. More...

auto elementMassInPhase (const StringOrIndex &element, const StringOrIndex &phase) -> void
Specify that the mass of an element in a phase at chemical equilibrium is given. More...

auto phaseAmount (const StringOrIndex &phase) -> void
Specify that the amount of a phase at chemical equilibrium is given. More...

auto phaseMass (const StringOrIndex &phase) -> void
Specify that the mass of a phase at chemical equilibrium is given. More...

auto phaseVolume (const StringOrIndex &phase) -> void
Specify that the volume of a phase at chemical equilibrium is given. More...

auto chemicalPotential (String substance) -> void
Specify that the chemical potential of a substance at chemical equilibrium is given. More...

auto lnActivity (const Species &species) -> void
Specify that the ln activity of a species at chemical equilibrium is given. More...

auto lnActivity (String species) -> void
Specify that the ln activity of a species at chemical equilibrium is given. More...

auto lgActivity (String species) -> void
Specify that the lg activity of a species at chemical equilibrium is given. More...

auto activity (String species) -> void
Specify that the activity of a species at chemical equilibrium is given. More...

auto fugacity (String gas) -> void
Specify that the fugacity of a gaseous species at chemical equilibrium is given. More...

auto pH () -> void
Specify that the pH at chemical equilibrium is given. More...

auto pMg () -> void
Specify that pMg at chemical equilibrium is given. More...

auto pE () -> void
Specify that pE at chemical equilibrium is given. More...

auto Eh () -> void
Specify that Eh at chemical equilibrium is given. More...

auto openTo (const ChemicalFormula &substance) -> void
Specify that the chemical system is open to a substance. More...

auto addUnknownTitrantAmount (const ChemicalFormula &substance) -> void
Specify that the chemical system is open to a given chemical state. // TODO: Implement EquilibriumSpecs::auto openTo(const ChemicalState& state). More...

auto addUnknownChemicalPotential (const String &species) -> void
Specify that the chemical potential of a species is unknown at equilibrium and must be computed.

auto addUnknownStandardChemicalPotential (const String &species) -> void
Specify that the standard chemical potential of a species is unknown at equilibrium and must be computed.

auto addUnknownActivity (const String &species) -> void
Specify that the activity of a species is unknown at equilibrium and must be computed.

auto addUnknownActivityCoefficient (const String &species) -> void
Specify that the activity coefficient of a species is unknown at equilibrium and must be computed.

auto numInputs () const -> Index
Return the number of introduced input variables.

auto numParams () const -> Index
Return the number of model parameters among the introduced input variables.

auto numControlVariables () const -> Index
Return the number of all introduced control variables.

auto numControlVariablesP () const -> Index
Return the number of introduced p control variables.

auto numControlVariablesQ () const -> Index
Return the number of introduced q control variables.

auto numTitrants () const -> Index
Return the number of all introduced explicit and implicit titrants.

auto numTitrantsExplicit () const -> Index
Return the number of all introduced explicit titrants.

auto numTitrantsImplicit () const -> Index
Return the number of all introduced implicit titrants.

auto numConstraints () const -> Index
Return the number of all introduced equation and chemical potential constraints.

auto namesInputs () const -> Strings
Return the names of the introduced input variables.

auto namesParams () const -> Strings
Return the names of the model parameters among the input variables.

auto namesControlVariables () const -> Strings
Return the names of all introduced control variables.

auto namesControlVariablesP () const -> Strings
Return the names of introduced p control variables.

auto namesControlVariablesQ () const -> Strings
Return the names of introduced q control variables.

auto namesTitrants () const -> Strings
Return the names of all introduced explicit and implicit titrants.

auto namesTitrantsExplicit () const -> Strings
Return the names of all introduced explicit titrants.

auto namesTitrantsImplicit () const -> Strings
Return the names of all introduced implicit titrants.

auto namesConstraints () const -> Strings
Return the names of all introduced equation and chemical potential constraints.

auto addControlVariableQ (const ControlVariableQ &qvar) -> void
Add a q control variable in the specification of the chemical equilibrium problem.

auto addControlVariableP (const ControlVariableP &pvar) -> void
Add a p control variable in the specification of the chemical equilibrium problem.

auto addConstraint (const ConstraintEquation &constraint) -> void
Add a new equation constraint to be satisfied at chemical equilibrium.

auto addInput (const String &var) -> Index
Add a new input variable for the chemical equilibrium problem with name var.

auto addInput (const Param &param) -> Index
Add model parameter param as a new input variable for the chemical equilibrium problem.

auto system () const -> const ChemicalSystem &
Return the chemical system associated with the equilibrium conditions.

auto inputs () const -> const Strings &
Return the input variables in the chemical equilibrium specifications.

auto params () const -> const Vec< Param > &
Return the model parameters among the input variables.

auto indicesParams () const -> const Vec< Index > &
Return the indices of the model parameters among the input variables.

auto isTemperatureUnknown () const -> bool
Return true if temperature is unknown in the chemical equilibrium specifications.

auto isPressureUnknown () const -> bool
Return true if pressure is unknown in the chemical equilibrium specifications.

auto indexControlVariableTemperature () const -> Index
The index of temperature among the p control variables or Index(-1) if it is a given input.

auto indexControlVariablePressure () const -> Index
The index of pressure among the p control variables or Index(-1) if it is a given input.

auto controlVariablesQ () const -> const Vec< ControlVariableQ > &
Return the q control variables in the chemical equilibrium specifications.

auto controlVariablesP () const -> const Vec< ControlVariableP > &
Return the q control variables in the chemical equilibrium specifications.

auto titrants () const -> Vec< ChemicalFormula >
Return the chemical formulas of the explicit and implicit titrant substances.

auto titrantsExplicit () const -> Vec< ChemicalFormula >
Return the chemical formulas of the explicit titrant substances.

auto titrantsImplicit () const -> Vec< ChemicalFormula >
Return the chemical formulas of the implicit titrant substances.

auto constraintsEquationType () const -> Vec< ConstraintEquation > const &
Return the equation constraints to be satisfied at chemical equilibrium.

## Detailed Description

The class used to define conditions to be satisfied at chemical equilibrium.

### Explicit Titrants

The explicit titrants are the titrants introduced with method EquilibriumSpecs::openTo. In the code below, the names of the explicitly introduced titrants are shown:

using namespace Reaktoro;
EquilibriumSpecs specs(system); // for some ChemicalSystem object system
specs.openTo("H2S"); // a titrant named [H2S] will be introduced.
specs.openTo("CO2"); // a titrant named [CO2] will be introduced.
EquilibriumSpecs(const ChemicalSystem &system)
Construct an EquilibriumSpecs object.
auto system() const -> const ChemicalSystem &
Return the chemical system associated with the equilibrium conditions.
The namespace containing all components of the Reaktoro library.
Definition: Algorithms.hpp:28

The amounts of these explicit titrants are unknown in the chemical equilibrium problem and computed together with the amounts of species.

### Implicit Titrants

The implicit titrants are the titrants introduced with methods:

In the code below, the names of the implicitly introduced titrants are shown:

using namespace Reaktoro;
EquilibriumSpecs specs(system); // for some ChemicalSystem object system
specs.lnActivity("Ca+2"); // a titrant named [Ca+2] will be introduced.
specs.fugacity("O2"); // a titrant named [O2] will be introduced.
specs.pH(); // a titrant named [H+] will be introduced.
specs.pMg(); // a titrant named [Mg+2] will be introduced.
specs.pE(); // a titrant named [e-] will be introduced.
specs.Eh(); // a titrant named [e-] will be introduced.

The amounts of these implicit titrants are unknown in the chemical equilibrium problem and computed together with the amounts of species.

### Control Variables

The control variables in a chemical equilibrium problem are unknowns introduced along with equilibrium constraints. These control variables can be:

• temperature,
• pressure, and
• amounts of explicit and implicit titrants.

The number of these control variables depend whether temperature and/or pressure are unknown and if any titrant has been introduced, explicitly or implicitly. For example, if EquilibriumSpecs::temperature is not called, then temperature is unknown and computed in the chemical equilibrium calculation. The same applies for pressure in case EquilibriumSpecs::pressure is not called. Titrants are introduced either explicitly, with method EquilibriumSpecs::openTo, or implicitly, with methods:

The following example formulates a set of specifications for a chemical equilibrium problem in which temperature and the amount of titrant [CO2] are introduced control variables. Their values are not known in advance; they are computed as part of the chemical equilibrium calculation.

using namespace Reaktoro;
EquilibriumSpecs specs(system); // for some ChemicalSystem object system
specs.temperature(); // temperature is an input variable in the chemical equilibrium problem.
specs.pressure(); // pressure is an input variable in the chemical equilibrium problem.
specs.volume(); // volume is an input variable in the chemical equilibrium problem.
specs.openTo("CO2"); // a titrant named [CO2] is introduced, and its amount computed at the end of the equilibrium calculation.

## ◆ temperature()

 auto temperature ( ) -> void

Specify that the temperature of the system at chemical equilibrium is given.

This method introduces one input variable with name T. By calling this method, you are specifying that temperature is known in the equilibrium calculation. Thus, temperature will not be considered as a control variable whose value needs to be computed.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesControlVariables.

## ◆ pressure()

 auto pressure ( ) -> void

Specify that the pressure of the system at chemical equilibrium is given.

This method introduces one input variable with name P. By calling this method, you are specifying that pressure is known in the equilibrium calculation. Thus, pressure will not be considered as a control variable whose value needs to be computed.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesControlVariables.

## ◆ volume()

 auto volume ( ) -> void

Specify that the volume of the system at chemical equilibrium is given.

This method introduces one input variable with name V. It also introduces an equation constraint with name volume to enforce a given volume value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ internalEnergy()

 auto internalEnergy ( ) -> void

Specify that the internal energy of the system at chemical equilibrium is given.

This method introduces one input variable with name U. It also introduces an equation constraint with name internalEnergy to enforce a given internal energy value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ enthalpy()

 auto enthalpy ( ) -> void

Specify that the enthalpy of the system at chemical equilibrium is given.

This method introduces one input variable with name H. It also introduces an equation constraint with name enthalpy to enforce a given enthalpy value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ gibbsEnergy()

 auto gibbsEnergy ( ) -> void

Specify that the Gibbs energy of the system at chemical equilibrium is given.

This method introduces one input variable with name G. It also introduces an equation constraint with name gibbsEnergy to enforce a given Gibbs energy value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ helmholtzEnergy()

 auto helmholtzEnergy ( ) -> void

Specify that the Helmholtz energy of the system at chemical equilibrium is given.

This method introduces one input variable with name A. It also introduces an equation constraint with name helmholtzEnergy to enforce a given Helmholtz energy value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ entropy()

 auto entropy ( ) -> void

Specify that the entropy of the system at chemical equilibrium is given.

This method introduces one input variable with name S. It also introduces an equation constraint with name entropy to enforce a given entropy value for the chemical system at equilibrium.

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints.

## ◆ elementAmount()

 auto elementAmount ( const StringOrIndex & element ) -> void

Specify that the amount of an element at chemical equilibrium is given.

Parameters
 element The name or index of the element in the chemical system.

## ◆ elementAmountInPhase()

 auto elementAmountInPhase ( const StringOrIndex & element, const StringOrIndex & phase ) -> void

Specify that the amount of an element in a phase at chemical equilibrium is given.

Parameters
 element The name or index of the element in the chemical system. phase The name or index of the phase in the chemical system.

## ◆ elementMass()

 auto elementMass ( const StringOrIndex & element ) -> void

Specify that the mass of an element at chemical equilibrium is given.

Parameters
 element The name or index of the element in the chemical system.

## ◆ elementMassInPhase()

 auto elementMassInPhase ( const StringOrIndex & element, const StringOrIndex & phase ) -> void

Specify that the mass of an element in a phase at chemical equilibrium is given.

Parameters
 element The name or index of the element in the chemical system. phase The name or index of the phase in the chemical system.

## ◆ phaseAmount()

 auto phaseAmount ( const StringOrIndex & phase ) -> void

Specify that the amount of a phase at chemical equilibrium is given.

Parameters
 phase The name or index of the phase in the chemical system.

## ◆ phaseMass()

 auto phaseMass ( const StringOrIndex & phase ) -> void

Specify that the mass of a phase at chemical equilibrium is given.

Parameters
 phase The name or index of the phase in the chemical system.

## ◆ phaseVolume()

 auto phaseVolume ( const StringOrIndex & phase ) -> void

Specify that the volume of a phase at chemical equilibrium is given.

Parameters
 phase The name or index of the phase in the chemical system.

## ◆ chemicalPotential()

 auto chemicalPotential ( String substance ) -> void

Specify that the chemical potential of a substance at chemical equilibrium is given.

This method introduces one input variable with name u[substance] (e.g., u[H2O] if substance is "H2O"). It also introduces a chemical potential constraint with same name to enforce a given chemical potential value for the substance at chemical equilibrium. This method also indicates that the chemical system is open to substance (e.g., the system is open to mass in/out of H2O). Thus an implicit titrant is introduced with name [substance] (e.g., [H2O]).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 substance The chemical formula of the substance (e.g., H2O, CO2, H+, Mg+2).

## ◆ lnActivity() [1/2]

 auto lnActivity ( const Species & species ) -> void

Specify that the ln activity of a species at chemical equilibrium is given.

This method introduces one input variable with name lnActivity[speciesName] (e.g., lnActivity[CO2(aq)] if species is a Species object with name "CO2(aq)"). It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for the natural log activity of the species at chemical equilibrium. This method also indicates that the chemical system is open to the underlying substance of the species, not the species itself. For example, the system is open to mass in/out of CO2 if the Species object species is CO2(aq), CO2(g) or CO2(l)). Thus an implicit titrant is introduced with name [substance] (e.g., [CO2]).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 species The chemical species as an Species object.

## ◆ lnActivity() [2/2]

 auto lnActivity ( String species ) -> void

Specify that the ln activity of a species at chemical equilibrium is given.

For more details, check the documentation of EquilibriumSpecs::lnActivity(const Species&).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 species The name of the chemical species as found in the database in use.
Note
The chemical species does not need to be in the chemical system; only in the database.
Warning
An error will be thrown if the database does not contain a species with given name.

## ◆ lgActivity()

 auto lgActivity ( String species ) -> void

Specify that the lg activity of a species at chemical equilibrium is given.

For more details, check the documentation of EquilibriumSpecs::lnActivity(const Species&).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 species The name of the chemical species as found in the database in use.
Note
The chemical species does not need to be in the chemical system; only in the database.
Warning
An error will be thrown if the database does not contain a species with given name.

## ◆ activity()

 auto activity ( String species ) -> void

Specify that the activity of a species at chemical equilibrium is given.

For more details, check the documentation of EquilibriumSpecs::lnActivity(const Species&).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 species The name of the chemical species as found in the database in use.
Note
The chemical species does not need to be in the chemical system; only in the database.
Warning
An error will be thrown if the database does not contain a species with given name.

## ◆ fugacity()

 auto fugacity ( String gas ) -> void

Specify that the fugacity of a gaseous species at chemical equilibrium is given.

This method introduces one input variable with name f[gas] (e.g., f[O2] if gas is "O2"). It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for the fugacity of the gas at chemical equilibrium. This method also indicates that the chemical system is open to gas (e.g., the system is open to mass in/out of O2). Thus an implicit titrant is introduced with name [substance] (e.g., [O2]).

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 gas The name of the gaseous species as found in the database in use.
Note
The gaseous species does not need to be in the chemical system; only in the database.
Warning
An error will be thrown if the database does not contain a gaseous species with given name.

## ◆ pH()

 auto pH ( ) -> void

Specify that the pH at chemical equilibrium is given.

This method introduces one input variable with name pH. It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for pH at chemical equilibrium. This method also indicates that the chemical system is open to mass in/out of H+. Thus an implicit titrant is introduced with name [H+]. The code below demonstrate the use of this method and its effect on the list of input variables, titrants and control variables.

using namespace Reaktoro;
EquilibriumSpecs specs(system); // for some ChemicalSystem object system
specs.enthalpy(); // introduces input variable H and constraint enthalpy
specs.pressure(); // introduces input variable P
specs.pH(); // introduces input variable pH, constraint pH, and titrant [H+]
print(specs.namesParams()); // H, P, pH
print(specs.namesTitrants()); // [H+]
print(specs.namesControlVariables()); // T, n[H+]
print(specs.namesContraints()); // enthalpy, pH
See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Warning
An error will be thrown if the system does not contain an aqueous species with formula H+.

## ◆ pMg()

 auto pMg ( ) -> void

Specify that pMg at chemical equilibrium is given.

This method introduces one input variable with name pMg. It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for pMg at chemical equilibrium. This method also indicates that the chemical system is open to mass in/out of Mg2+. Thus an implicit titrant is introduced with name [Mg+2].

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Warning
An error will be thrown if the system does not contain an aqueous species with formula Mg+2.

## ◆ pE()

 auto pE ( ) -> void

Specify that pE at chemical equilibrium is given.

This method introduces one input variable with name pE. It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for pE at chemical equilibrium. This method also indicates that the chemical system is open to mass in/out of e- (the electron substance). Thus an implicit titrant is introduced with name [e-].

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables

## ◆ Eh()

 auto Eh ( ) -> void

Specify that Eh at chemical equilibrium is given.

This method introduces one input variable with name Eh. It also introduces a chemical potential constraint with same name that is equivalent to enforcing a given value for Eh at chemical equilibrium. This method also indicates that the chemical system is open to mass in/out of e- (the electron substance). Thus an implicit titrant is introduced with name [e-].

See also
EquilibriumSpecs::namesParams, EquilibriumSpecs::namesConstraints, EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables

## ◆ openTo()

 auto openTo ( const ChemicalFormula & substance ) -> void

Specify that the chemical system is open to a substance.

Use this method to specify that the system is titrated with an unknown amount of a substance to be able to attain chemical equilibrium with given conditions. Its use introduces an explicit titrant with name [substance] (e.g., H2S is substance is "H2S"). The amount of this titrant is an unknown control variable which is computed in the chemical equilibrium calculation.

The code below demonstrate the use of this method and its effect on the list of titrants and control variables.

using namespace Reaktoro;
EquilibriumSpecs specs(system); // for some ChemicalSystem object system
specs.volume();
specs.pressure();
specs.openTo("H2S");
specs.openTo("CO2");
print(specs.namesTitrants()); // [H2S], [CO2]
print(specs.namesControlVariables()); // T, [H2S], [CO2]
Note
The code above is for demonstration purposes only. The given specifications do not produce a valid chemical equilibrium problem!
See also
EquilibriumSpecs::namesTitrants, EquilibriumSpecs::namesControlVariables
Parameters
 substance The chemical formula of the substance.

## ◆ addUnknownTitrantAmount()

 auto addUnknownTitrantAmount ( const ChemicalFormula & substance ) -> void

Specify that the chemical system is open to a given chemical state. // TODO: Implement EquilibriumSpecs::auto openTo(const ChemicalState& state).

Specify that the chemical system is open to a given material. // TODO: Implement EquilibriumSpecs::auto openTo(const Material& material). Specify that the chemical system is open to a titrant substance and its amount is unknown.

The documentation for this class was generated from the following file: