{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b40819ff",
   "metadata": {},
   "source": [
    "# Performing a chemical equilibrium calculation of carbonate species\n",
    "\n",
    "This tutorial demonstrates how to use Reaktoro to perform a chemical equilibrium calculation with carbon species.\n",
    "We start by importing the `reaktoro` package:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28bbede4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from reaktoro import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3975982",
   "metadata": {},
   "source": [
    "### Chemical system definition\n",
    "\n",
    "The default thermodynamic databases embedded into Reaktoro is SUPCRT92, so you do not have to initialize the\n",
    "database `db = Database('supcrt98.xml')`, unless you use an alternative one.\n",
    "Class [ChemicalEditor](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html)\n",
    "provides convenient operations to initialize\n",
    "[ChemicalSystem](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalSystem.html) and\n",
    "[ReactionSystem](https://reaktoro.org/cpp/classReaktoro_1_1ReactionSystem.html) instances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0099c698",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor = ChemicalEditor()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc298792",
   "metadata": {},
   "source": [
    "Alternatively, the editor can initialize from the file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d0ca8f8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Initialize a thermodynamic database with supcrt98.xml\n",
    "db = Database(\"supcrt98.xml\")\n",
    "#  Define the editor of the chemical system\n",
    "editor = ChemicalEditor(db)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d828986",
   "metadata": {},
   "source": [
    "To define a chemical system, *aqueous*, *gaseous*, and *mineral phases* must be added. For the aqueous phase,\n",
    "it can be done from a list of chemical element names. The database will be searched for all species that could be\n",
    "formed out of those elements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0008b104",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addAqueousPhaseWithElements(\"H O C Ca Cl Mg\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ea2208d",
   "metadata": {},
   "source": [
    "To add gaseous phase, we provide a specific list of gaseous species that must be used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84b70bb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addGaseousPhase([\"H2O(g)\", \"CO2(g)\", \"H2(g)\", \"O2(g)\", \"CH4(g)\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ab3fbce",
   "metadata": {},
   "source": [
    "For the [MineralPhase](https://reaktoro.org/cpp/classReaktoro_1_1MineralPhase.html) object, we add two pure mineral\n",
    "phases:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b5901de1",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addMineralPhase(\"Calcite\")\n",
    "editor.addMineralPhase(\"Dolomite\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2da55f7d",
   "metadata": {},
   "source": [
    "To create an object of class [ChemicalSystem](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalSystem.html)\n",
    "using the chemical system definition details stored in the object editor, we use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f79b2da9",
   "metadata": {},
   "outputs": [],
   "source": [
    "system = ChemicalSystem(editor)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9b08a84",
   "metadata": {},
   "source": [
    "To output the details of the chemical system to the console, i.e., the list of elements, species, and different\n",
    "phases, we can execute"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1eb63c81",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(system)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7dce7004",
   "metadata": {},
   "source": [
    "For the specific information about the chemical system, one can use the following methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0fb2ef7f",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Number of chemical species: \", len(system.species()))\n",
    "print(\"Number of phases: \", len(system.phases()))\n",
    "print(\"Number of elements: \", len(system.elements()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93a008ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of species in chemical system: \\n\")\n",
    "for species in system.species():\n",
    "    print(species.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "324c7599",
   "metadata": {},
   "source": [
    "> *See tutorials [**ChemicalEditor**](cl.chemical-editor.ipynb) and [**ChemicalSystem**](cl.chemical-system.ipynb)\n",
    "> for more detailed explanation of capabilities of these classes*."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6a4ddfa",
   "metadata": {},
   "source": [
    "### Defining the chemical equilibrium problem\n",
    "\n",
    "Next, we create an equilibrium problem with our prescribed equilibrium conditions for\n",
    "amounts of elements that are consistent with our intention of calculating reaction of calcite with\n",
    "injected 0.002 molal MaCl<sub>2</sub> brine. Both temperature and pressure are assumed to be default values, i.e.,\n",
    "25 &deg;C and 1 bar, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ce45b3f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "problem = EquilibriumProblem(system)\n",
    "problem.add(\"H2O\", 1, \"kg\")\n",
    "problem.add(\"MgCl2\", 0.002, \"mol\")\n",
    "problem.add(\"CaCO3\", 1, \"mol\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0d7b4a4",
   "metadata": {},
   "source": [
    "### Calculating the chemical equilibrium state\n",
    "\n",
    "In this step, we use the [equilibrate](https://reaktoro.org/cpp/namespaceReaktoro.html#af2d3b39d3e0b8f9cb5a4d9bbb06b697e)\n",
    "function to calculate the chemical equilibrium state of the system with the given equilibrium conditions stored in\n",
    "the object problem."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "90666ae9",
   "metadata": {},
   "outputs": [],
   "source": [
    "state = equilibrate(problem)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fd5305ac",
   "metadata": {},
   "source": [
    "Reaktoro uses an efficient **Gibbs energy minimization** computation to determine the species amounts that correspond\n",
    "to a state of minimum Gibbs energy in the system while satisfying the prescribed amount conditions for the\n",
    "temperature, pressure, and element amounts. The result is stored in the object `state` of class\n",
    "[ChemicalState](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalState.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1873750f",
   "metadata": {},
   "source": [
    "To output the result of equilibration to the console, we use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38009b1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(state)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67da176e",
   "metadata": {},
   "source": [
    "We will obtain the table describing the chemical state of the system. For example, the molar amounts, molar fractions,\n",
    "activities, activity coefficients, and chemical potentials of the species. The molar volumes of the phases,\n",
    "the amounts of each element in the phases, and also the total phase molar amounts."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61d06521",
   "metadata": {},
   "source": [
    "Alternatively, to save equilibrated state into a file, one can use method\n",
    "[ChemicalState::output](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalState.html#ae5f2706f5be6e6856360a2f1073931e2):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee7d74b7",
   "metadata": {},
   "outputs": [],
   "source": [
    "state.output(\"result.txt\")  # Output the equilibrium state into a file result.txt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed51155e",
   "metadata": {},
   "source": [
    "To print the amounts of some specific aqueous species, one can use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "95ec6b2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Print the amounts of some aqueous species\n",
    "print(\"Amount of CO2(aq):\", state.speciesAmount(\"CO2(aq)\"))\n",
    "print(\"Amount of HCO3-:\", state.speciesAmount(\"HCO3-\"))\n",
    "print(\"Amount of CO3--:\", state.speciesAmount(\"CO3--\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "63051e6e",
   "metadata": {},
   "source": [
    "Similarly, one can also print the amounts of the certain element, say carbon, in both aqueous and gaseous phases"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0da3d9af",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Print the amounts of element C in both aqueous and gaseous phases\n",
    "print(\"Amount of C in aqueous phase:\", state.elementAmountInPhase(\"C\", \"Aqueous\"))\n",
    "print(\"Amount of C in gaseous phase:\", state.elementAmountInPhase(\"C\", \"Gaseous\"))\n",
    "print(\"Amount of C in calcite phase:\", state.elementAmountInPhase(\"C\", \"Calcite\"))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}