Reaktoro
A unified framework for modeling chemically reactive systems
ChemicalEditor Class Reference

Provides convenient operations to initialize ChemicalSystem and ReactionSystem instances. More...

#include <ChemicalEditor.hpp>

Public Member Functions

 ChemicalEditor ()
 Construct a default ChemicalEditor instance. More...
 
 ChemicalEditor (const Database &database)
 Construct a ChemicalEditor instance with the provided database.
 
 ChemicalEditor (const ChemicalEditor &other)
 Construct a copy of the provided ChemicalEditor instance.
 
virtual ~ChemicalEditor ()
 Destroy the ChemicalEditor instance.
 
auto operator= (const ChemicalEditor &other) -> ChemicalEditor &
 Assign this ChemicalEditor instance with another.
 
auto setTemperatures (std::vector< double > values, std::string units) -> void
 Set the temperatures for constructing interpolation tables of thermodynamic properties. More...
 
auto setPressures (std::vector< double > values, std::string units) -> void
 Set the pressures for constructing interpolation tables of thermodynamic properties. More...
 
auto initializePhasesWithElements (const StringList &elements) -> void
 Initialize all possible phases that can exist with given elements. More...
 
auto addPhase (const AqueousPhase &phase) -> AqueousPhase &
 Add an aqueous phase in the chemical editor. More...
 
auto addPhase (const GaseousPhase &phase) -> GaseousPhase &
 Add a gaseous phase in the chemical editor. More...
 
auto addPhase (const MineralPhase &phase) -> MineralPhase &
 Add a mineral phase in the chemical editor. More...
 
auto addReaction (const MineralReaction &reaction) -> MineralReaction &
 Add a mineral reaction in the chemical editor. More...
 
auto addAqueousPhase (const StringList &species) -> AqueousPhase &
 Add an aqueous phase in the chemical editor. More...
 
auto addAqueousPhaseWithElements (const StringList &elements) -> AqueousPhase &
 Add an aqueous phase in the chemical editor. More...
 
auto addAqueousPhaseWithElementsOf (const StringList &compounds) -> AqueousPhase &
 Add an aqueous phase in the chemical editor. More...
 
auto addGaseousPhase (const StringList &species) -> GaseousPhase &
 Add a gaseous phase in the chemical editor. More...
 
auto addGaseousPhaseWithElements (const StringList &elements) -> GaseousPhase &
 Add a gaseous phase in the chemical editor. More...
 
auto addGaseousPhaseWithElementsOf (const StringList &compounds) -> GaseousPhase &
 Add a gaseous phase in the chemical editor. More...
 
auto addMineralPhase (const StringList &species) -> MineralPhase &
 Add a mineral phase in the chemical editor. More...
 
auto addMineralPhaseWithElements (const StringList &elements) -> MineralPhase &
 Add a mineral phase in the chemical editor. More...
 
auto addMineralPhaseWithElementsOf (const StringList &compounds) -> MineralPhase &
 Add a mineral phase in the chemical editor. More...
 
auto addMineralReaction (const MineralReaction &reaction) -> MineralReaction &
 Add a mineral reaction in the chemical editor. More...
 
auto addMineralReaction (std::string mineral) -> MineralReaction &
 Add a mineral reaction in the chemical editor. More...
 
auto aqueousPhase () const -> const AqueousPhase &
 Return the aqueous phase in the chemical editor.
 
auto aqueousPhase () -> AqueousPhase &
 Return the aqueous phase in the chemical editor.
 
auto gaseousPhase () const -> const GaseousPhase &
 Return the gaseous phase in the chemical editor.
 
auto gaseousPhase () -> GaseousPhase &
 Return the gaseous phase in the chemical editor.
 
auto mineralPhases () const -> const std::vector< MineralPhase > &
 Return the mineral phases in the chemical editor.
 
auto mineralPhases () -> std::vector< MineralPhase > &
 Return the mineral phases in the chemical editor.
 
auto createChemicalSystem () const -> ChemicalSystem
 Create a ChemicalSystem instance with the current state of the chemical editor.
 
auto createReactionSystem () const -> ReactionSystem
 Create a ReactionSystem instance with the current state of the chemical editor.
 
 operator ChemicalSystem () const
 Convert this ChemicalEditor instance to a ChemicalSystem instance.
 
 operator ReactionSystem () const
 Convert this ChemicalEditor instance to a ReactionSystem instance.
 

Detailed Description

Provides convenient operations to initialize ChemicalSystem and ReactionSystem instances.

The ChemicalEditor class is used to conveniently create instances of classes ChemicalSystem and ReactionSystem.

Usage

The code below uses a ChemicalEditor instance to define a chemical system composed of an aqueous phase and a mineral phase. In addition, it defines a chemical reaction involving both aqueous and mineral species. Finally, the editor instance is used to create a ChemicalSystem instance and a ReactionSystem instance.

using namespace Reaktoro;
// A Database instance is necessary to create a ChemicalEditor instance
Database database("geodb.xml");
// Create the ChemicalEditor instance to setup the chemical system and reactions
// Define a chemical system with an aqueous and a mineral phase
editor.addAqueousPhase("H2O(l), H+, OH-, HCO3-, CO2(aq), Ca++");
editor.addMineralPhase("Calcite");
// Define a mineral reaction involving the mineral phase and the aqueous phase
editor.addMineralReaction("Calcite")
.setEquation("-1:Calcite, -1:H+, 1:HCO3-, 1:Ca++")
.setSpecificSurfaceArea(100.0, "cm2/g")
.addMechanism("logk = -5.81 mol/(m2*s), Ea = 23.5 kJ/mol")
.addMechanism("logk = -0.30 mol/(m2*s), Ea = 14.4 kJ/mol, a[H+] = 1.0");
// Create the ChemicalSystem and ReactionSystem instances
ChemicalSystem system = editor;
ReactionSystem reactions = editor;
See also
Database, ChemicalSystem, ReactionSystem, AqueousPhase, GaseousPhase, MineralPhase, AqueousSpecies, GaseousSpecies, MineralSpecies, MineralReaction

Constructor & Destructor Documentation

◆ ChemicalEditor()

Construct a default ChemicalEditor instance.

The built-in database supcrt98.xml is used for the initialization of a ChemicalEditor instance using the default constructor.

Member Function Documentation

◆ setTemperatures()

auto setTemperatures ( std::vector< double >  values,
std::string  units 
) -> void

Set the temperatures for constructing interpolation tables of thermodynamic properties.

Parameters
valuesThe temperature values
unitsThe units of the temperature values

◆ setPressures()

auto setPressures ( std::vector< double >  values,
std::string  units 
) -> void

Set the pressures for constructing interpolation tables of thermodynamic properties.

Parameters
valuesThe pressure values
unitsThe units of the pressure values

◆ initializePhasesWithElements()

auto initializePhasesWithElements ( const StringList elements) -> void

Initialize all possible phases that can exist with given elements.

Parameters
elementsThe element symbols of interest.

◆ addPhase() [1/3]

auto addPhase ( const AqueousPhase phase) -> AqueousPhase&

Add an aqueous phase in the chemical editor.

Note that only one aqueous phase can exist in the chemical editor. So whenever this method is called, it has the effect of updating the current state of the aqueous phase in the editor.

Parameters
phaseThe AqueousPhase instance
Returns
A reference to the created AqueousPhase object.

◆ addPhase() [2/3]

auto addPhase ( const GaseousPhase phase) -> GaseousPhase&

Add a gaseous phase in the chemical editor.

Note that only one gaseous phase can exist in the chemical editor. So whenever this method is called, it has the effect of updating the current state of the gaseous phase in the editor.

Parameters
phaseThe GaseousPhase instance
Returns
A reference to the created GaseousPhase object.

◆ addPhase() [3/3]

auto addPhase ( const MineralPhase phase) -> MineralPhase&

Add a mineral phase in the chemical editor.

If a mineral phase with the same name already exists, then the existing phase is replaced by the new one.

Parameters
phaseThe MineralPhase instance
Returns
A reference to the created MineralPhase object.

◆ addReaction()

auto addReaction ( const MineralReaction reaction) -> MineralReaction&

Add a mineral reaction in the chemical editor.

Parameters
reactionThe MineralReaction instance
Returns
A reference to the created MineralReaction object.

◆ addAqueousPhase()

auto addAqueousPhase ( const StringList species) -> AqueousPhase&

Add an aqueous phase in the chemical editor.

This method constructs an AqueousPhase object that represents an aqueous phase in the system. The AqueousPhase object is created by specifying the names of the species one by one. These species names must conform to those used in the database that was specified during the initialization of the ChemicalEditor object, otherwise, an exception will be thrown. The example below describes the usage of this method for an aqueous phase that could be formed by mixing H2O, CO2 and NaCl.

#include <Reaktoro/Reaktoro.hpp> {delete}
using namespace Reaktoro; {delete}
editor.addAqueousPhase({"H2O(l)", "H+", "OH-", "HCO3-", "CO2(aq)", "Na+", "Cl-"});

An alternative way, in which to prior knowledge of the species names in the database is needed, consists of specifying a list of chemical element, compound, or substance names, and let the ChemicalEditor to figure out automatically which species from the loaded database should be added in the phase. This functionality is supported by methods

addAqueousPhaseWithElements(const std::vector<std::string>& elements),

addAqueousPhaseWithElementsOf(const std::vector<std::string>& compounds).

Parameters
speciesA StringList containing the names of the species.
Returns
A reference to the created AqueousPhase object.
See also
addGaseousPhase, addMineralPhase
Note
The old use of this function to add elements and/or compounds was removed. To use these functionalities, use addAqueousPhaseWitElements to add elements and addAqueousPhaseWitElementsOf to add compounds.

◆ addAqueousPhaseWithElements()

auto addAqueousPhaseWithElements ( const StringList elements) -> AqueousPhase&

Add an aqueous phase in the chemical editor.

This method constructs an AqueousPhase object that represents an aqueous phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the AqueousPhase object to be constructed by using a list of chemical element names, and the database will then be searched for all species that could be formed out of those elements. These species will then be used to construct the AqueousPhase object. The example below describes three equivalent alternatives to construct an AqueousPhase object that represents an aqueous phase that could be formed by mixing H2O, CO2 and NaCl.

editor.addAqueousPhaseWithElements({"H", "C", "Na", "Cl"});
editor.addAqueousPhaseWithElements({"H2O", "CO2", "NaCl");
editor.addAqueousPhaseWithElements("HCNaCl");

This might not be relevant for an aqueous phase, which in general contains many species, but it is a convenient functionality for gaseous and mineral phases, for example, which might only contain one species of interest.

Parameters
elementsA StringList containing a list of chemical element names.
Returns
A reference to the created AqueousPhase object.
See also
addGaseousPhaseWithElements, addMineralPhaseWithElements

◆ addAqueousPhaseWithElementsOf()

auto addAqueousPhaseWithElementsOf ( const StringList compounds) -> AqueousPhase&

Add an aqueous phase in the chemical editor.

This method constructs an AqueousPhase object that represents an aqueous phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the AqueousPhase object to be constructed by using a list of compound or substance names that might not represent names of species in the database. The list of compounds will be broken into a list of element names, and the database will then be searched for all species that could be formed out of those elements. These species will then be used to construct the AqueousPhase object. The example below describes three equivalent alternatives to construct an AqueousPhase object that represents an aqueous phase that could be formed by mixing H2O, CO2 and NaCl.

editor.addAqueousPhaseWithElementsOf("H2O NaCl CO2");
editor.addAqueousPhaseWithElementsOf({"H2O", "CO2", "NaCl");
editor.addAqueousPhaseWithElementsOf("HCNaCl");

This might not be relevant for an aqueous phase, which in general contains many species, but it is a convenient functionality for gaseous and mineral phases, for example, which might only contain one species of interest.

Parameters
compoundsA StringList containing a list of compound names.
Returns
A reference to the created AqueousPhase object.
See also
addGaseousPhaseWithElementsOf, addMineralPhaseWithElementsOf

◆ addGaseousPhase()

auto addGaseousPhase ( const StringList species) -> GaseousPhase&

Add a gaseous phase in the chemical editor.

This method constructs a GaseousPhase object that represents a gaseous phase in the system. The GaseousPhase object is created by specifying the names of the species one by one. These species names must conform to those used in the database that was specified during the initialization of the ChemicalEditor object, otherwise, an exception will be thrown. The example below describes the usage of this method for a gaseous phase that could be formed by mixing CH4 and O2.

editor.addGaseousPhase({"H2O(g)", "CO2(g)", "O2(g)", "CH4(g)"});

An alternative way, in which to prior knowledge of the species names in the database is needed, consists of specifying a list of chemical element, compound, or substance names, and let the ChemicalEditor to figure out automatically which species from the loaded database should be added in the phase. This functionality is supported by method addGaseousPhaseWithElements(std::string elements). addGaseousPhaseWithElementsOf(std::string compounds).

Parameters
speciesA StringList containing the names of the species.
Returns
A reference to the created GaseousPhase object.
See also
addAqueousPhase, addMineralPhase
Note
The old use of this function to add elements and/or compounds was removed. To use these functionalities, use addGaseousPhaseWitElements to add elements and addGaseousPhaseWitElementsOf to add compounds.

◆ addGaseousPhaseWithElements()

auto addGaseousPhaseWithElements ( const StringList elements) -> GaseousPhase&

Add a gaseous phase in the chemical editor.

This method constructs a GaseousPhase object that represents a gaseous phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the GaseousPhase object to be constructed by using a list of chemical element names and the database will then be searched for all species that could be formed out of those elements. These species will then be used to construct the GaseousPhase object. The example below describes three equivalent alternatives to construct a GaseousPhase object that represents a gaseous phase that could be formed by mixing H2O and CO2.

editor.addGaseousPhaseWithElements({"H", "O", "C"});
editor.addGaseousPhaseWithElements({"H2O", "CO2"});
editor.addGaseousPhaseWithElements({"HOC"});
Parameters
elementsA StringList containing a list of chemical element names.
Returns
A reference to the created GaseousPhase object.
See also
addAqueousPhaseWithElements, addMineralPhaseWithElements

◆ addGaseousPhaseWithElementsOf()

auto addGaseousPhaseWithElementsOf ( const StringList compounds) -> GaseousPhase&

Add a gaseous phase in the chemical editor.

This method constructs a GaseousPhase object that represents a gaseous phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the GaseousPhase object to be constructed by using a list of compound or substance names that might not represent names of species in the database. The list of compounds will be broken into a list of element names, and the database will then be searched for all species that could be formed out of those elements. The example below describes three equivalent alternatives to construct a GaseousPhase object that represents a gaseous phase that could be formed by mixing H2O and CO2.

editor.addGaseousPhaseWithElementsOf({"H2O", "CO2"});
editor.addGaseousPhaseWithElementsOf({"H2O CO2"});
editor.addGaseousPhaseWithElementsOf({"HOC"});
Parameters
compoundsA StringList containing a list of compound names.
Returns
A reference to the created GaseousPhase object.
See also
addAqueousPhaseWithElements, addMineralPhaseWithElements

◆ addMineralPhase()

auto addMineralPhase ( const StringList species) -> MineralPhase&

Add a mineral phase in the chemical editor.

This method constructs a MineralPhase object that represents a mineral phase in the system. The MineralPhase object is created by specifying the names of the species one by one. These species names must conform to those used in the database that was specified during the initialization of the ChemicalEditor object, otherwise, an exception will be thrown. The example below describes the usage of this method for the creation of two pure mineral phases and one solid solution with two mineral species.

// Create a pure mineral phase with only calcite [CaCO3(s)]
editor.addMineralPhase({"Calcite"});
// Create a pure mineral phase with only magnesite [MgCO3(s)]
editor.addMineralPhase("Magnesite");
// Create a solid solution with mineral species calcite and magnesite
editor.addMineralPhase({"Calcite", "Magnesite"});

An alternative way, in which a prior knowledge of the species names in the database is needed, consists of specifying a list of chemical elements or compounds, and let the ChemicalEditor to figure out automatically which species from the loaded database should be added in the phase. This functionality is supported by methods addMineralPhaseWithElements(std::string elements) and addMineralPhaseWithElementsOf(std::string compounds).

Parameters
speciesA StringList containing the names of the species.
Returns
A reference to the created MineralPhase object.
See also
addAqueousPhase, addGaseousPhase
Note
The old use of this function to add elements and/or compounds was removed. To use these functionalities, use addMineralPhaseWitElements to add eslements and addMineralPhaseWitElementsOf to add compounds.

◆ addMineralPhaseWithElements()

auto addMineralPhaseWithElements ( const StringList elements) -> MineralPhase&

Add a mineral phase in the chemical editor.

This method constructs a MineralPhase object that represents a mineral phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the MineralPhase object to be constructed by using a list of chemical element names, and the database will then be searched for all species that could be formed out of those elements. These species will then be used to construct the MineralPhase object. The example below describes several possibilities to construct a MineralPhase object.

// This will return an error, as it only accepts element names
editor.addMineralPhaseWithElements({"CaCO3", "MgCO3"});
editor.addMineralPhaseWithElements({"Ca", "C", "O"});
// This will only recognize the element "O", and CaC will be ignored
editor.addMineralPhaseWithElements({"CaC", "O"});
Note
In most cases, the solid solutions of interest have predefined mineral composition, so that one might prefer instead to list the mineral end-members one by one, instead of letting ChemicalEditor to populate the solid solution with many minerals that could be formed from a given list of chemical elements.
Parameters
elementsA StringList containing a list of chemical element names.
Returns
A reference to the created MineralPhase object.
See also
addAqueousPhaseWithElements, addGaseousPhaseWithElements

◆ addMineralPhaseWithElementsOf()

auto addMineralPhaseWithElementsOf ( const StringList compounds) -> MineralPhase&

Add a mineral phase in the chemical editor.

This method constructs a MineralPhase object that represents a mineral phase in the system. Instead of listing the names of the species one by one, which might require prior knowledge of the species names in the database, this method permits the MineralPhase object to be constructed by using a list of compound or substance names that might not represent names of species in the database. The list of compounds will be broken into a list of element names, and the database will then be searched for all species that could be formed out of those elements. These species will then be used to construct the MineralPhase object. The example below describes several possibilities to construct a MineralPhase object.

// Create a solid solution with all minerals that could be formed by combining compounds CaCO3 and MgCO3.
editor.addMineralPhaseWithElementsOf({"CaCO3", "MgCO3"});
// Create a solid solution with all minerals that could be formed from elements Ca, C, and O.
editor.addMineralPhaseWithElementsOf("CaCO3"); // assuming the name CaCO3 is not in the database
Note
In most cases, the solid solutions of interest have predefined mineral composition, so that one might prefer instead to list the mineral end-members one by one, instead of letting ChemicalEditor to populate the solid solution with many minerals that could be formed from a given list of compound names.
Parameters
compoundsA StringList containing a list of compound names.
Returns
A reference to the created MineralPhase object.
See also
addAqueousPhaseWithElementsOf, addGaseousPhaseWithElementsOf

◆ addMineralReaction() [1/2]

auto addMineralReaction ( const MineralReaction reaction) -> MineralReaction&

Add a mineral reaction in the chemical editor.

Parameters
reactionThe mineral reaction.
Returns
A reference to the created MineralReaction object.

◆ addMineralReaction() [2/2]

auto addMineralReaction ( std::string  mineral) -> MineralReaction&

Add a mineral reaction in the chemical editor.

Parameters
mineralThe name of the mineral for which the reaction will be defined.
Returns
A reference to the created MineralReaction object.

The documentation for this class was generated from the following files:
  • Reaktoro/Thermodynamics/Core/ChemicalEditor.hpp
  • Reaktoro/Thermodynamics/Core/ChemicalEditor.cpp