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 a provided database.

ChemicalEditor (const ThermoFun::Database &database)
Construct a ChemicalEditor instance with a provided ThermoFun 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 LiquidPhase &phase) -> LiquidPhase &
Add a liquid 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 addLiquidPhase (const StringList &species) -> LiquidPhase &
Add a liquid phase in the chemical editor. More...

auto addLiquidPhaseWithElements (const StringList &elements) -> LiquidPhase &
Add a liquid phase in the chemical editor. More...

auto addLiquidPhaseWithElementsOf (const StringList &compounds) -> LiquidPhase &
Add a liquid 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 liquidPhase () const -> const LiquidPhase &
Return the liquid phase in the chemical editor.

auto liquidPhase () -> LiquidPhase &
Return the liquid 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++");
// Define a mineral reaction involving the mineral phase and the aqueous phase
.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;
Database, ChemicalSystem, ReactionSystem, AqueousPhase, GaseousPhase, LiquidPhase, MineralPhase, AqueousSpecies, GaseousSpecies, LiquidSpecies, MineralSpecies, MineralReaction

## ◆ ChemicalEditor()

 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.

## ◆ setTemperatures()

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

Set the temperatures for constructing interpolation tables of thermodynamic properties.

Parameters
 values The temperature values units The 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
 values The pressure values units The units of the pressure values

## ◆ initializePhasesWithElements()

 auto initializePhasesWithElements ( const StringList & elements ) -> void

Initialize all possible phases that can exist with given elements.

Parameters
 elements The element symbols of interest.

 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
 phase The AqueousPhase instance
Returns
A reference to the created AqueousPhase object.

 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 on gaseous phase in the editor.

Parameters
 phase The GaseousPhase instance
Returns
A reference to the created GaseousPhase object.

 auto addPhase ( const LiquidPhase & phase ) -> LiquidPhase&

Add a liquid phase in the chemical editor.

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

Parameters
 phase The LiquidPhase instance
Returns
A reference to the created LiquidPhase object.

 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
 phase The MineralPhase instance
Returns
A reference to the created MineralPhase object.

 auto addReaction ( const MineralReaction & reaction ) -> MineralReaction&

Add a mineral reaction in the chemical editor.

Parameters
 reaction The MineralReaction instance
Returns
A reference to the created MineralReaction object.

 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

Parameters
 species A StringList containing the names of the species.
Returns
A reference to the created AqueousPhase object.
Note

 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.

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
 elements A StringList containing a list of chemical element names.
Returns
A reference to the created AqueousPhase object.

 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.

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
 compounds A StringList containing a list of compound names.
Returns
A reference to the created AqueousPhase object.

 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.

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
 species A StringList containing the names of the species.
Returns
A reference to the created GaseousPhase object.
Note

 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.

Parameters
 elements A StringList containing a list of chemical element names.
Returns
A reference to the created GaseousPhase object.

 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.

Parameters
 compounds A StringList containing a list of compound names.
Returns
A reference to the created GaseousPhase object.

 auto addLiquidPhase ( const StringList & species ) -> LiquidPhase&

Add a liquid phase in the chemical editor.

This method constructs a LiquidPhase object that represents a liquid phase in the system. The LiquidPhase 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 liquid phase that could be formed by mixing CH4 and O2.

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 addLiquidPhaseWithElements(std::string elements). addLiquidPhaseWithElementsOf(std::string compounds).

Parameters
 species A StringList containing the names of the species.
Returns
A reference to the created LiquidPhase object.
Note

 auto addLiquidPhaseWithElements ( const StringList & elements ) -> LiquidPhase&

Add a liquid phase in the chemical editor.

This method constructs a LiquidPhase object that represents a liquid 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 LiquidPhase 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 LiquidPhase object. The example below describes three equivalent alternatives to construct a LiquidPhase object that represents a liquid phase that could be formed by mixing H2S and CO2.

Parameters
 elements A StringList containing a list of chemical element names.
Returns
A reference to the created LiquidPhase object.

 auto addLiquidPhaseWithElementsOf ( const StringList & compounds ) -> LiquidPhase&

Add a liquid phase in the chemical editor.

This method constructs a LiquidPhase object that represents a liquid 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 LiquidPhase 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 LiquidPhase object that represents a liquid phase that could be formed by mixing H2S and CO2.

Parameters
 compounds A StringList containing a list of compound names.
Returns
A reference to the created LiquidPhase object.

 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)]
// Create a pure mineral phase with only magnesite [MgCO3(s)]
// Create a solid solution with mineral species calcite and 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
 species A StringList containing the names of the species.
Returns
A reference to the created MineralPhase object.
Note

 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
// This will only recognize the element "O", and CaC will be ignored
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
 elements A StringList containing a list of chemical element names.
Returns
A reference to the created MineralPhase object.

 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.
// 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
 compounds A StringList containing a list of compound names.
Returns
A reference to the created MineralPhase object.

 auto addMineralReaction ( const MineralReaction & reaction ) -> MineralReaction&

Add a mineral reaction in the chemical editor.

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

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

Add a mineral reaction in the chemical editor.

Parameters
 mineral The 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
Provides operations to retrieve physical and thermodynamic data of chemical species.
Definition: Database.hpp:78
A class to represent a system and its attributes and properties.
Definition: ChemicalSystem.hpp:38
auto addMineralPhase(const StringList &species) -> MineralPhase &
Add a mineral phase in the chemical editor.
Definition: ChemicalEditor.cpp:628
Provides convenient operations to initialize ChemicalSystem and ReactionSystem instances.
Definition: ChemicalEditor.hpp:87
auto database(std::string name) -> std::string
Return the contents of a built-in database as a string.
Definition: DatabaseUtils.cpp:65
ChemicalEditor()
Construct a default ChemicalEditor instance.
Definition: ChemicalEditor.cpp:518
auto addAqueousPhase(const StringList &species) -> AqueousPhase &
Add an aqueous phase in the chemical editor.
Definition: ChemicalEditor.cpp:583
The namespace containing all components of the Reaktoro library.
Definition: ChemicalScalar.hpp:24
A class that represents a system of chemical reactions.
Definition: ReactionSystem.hpp:42
auto addMineralReaction(const MineralReaction &reaction) -> MineralReaction &
Add a mineral reaction in the chemical editor.
Definition: ChemicalEditor.cpp:643
auto addAqueousPhaseWithElements(const StringList &elements) -> AqueousPhase &
Add an aqueous phase in the chemical editor.
Definition: ChemicalEditor.cpp:588