{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "247051c5",
   "metadata": {},
   "source": [
    "# Functionality of ChemicalEditor class\n",
    "\n",
    "In this tutorial, we provide clarification of the functionality of the class\n",
    "[ChemicalEditor](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html) that is used to\n",
    "conveniently create chemical and reaction systems.\n",
    "\n",
    "### Importing the reaktoro Python package\n",
    "\n",
    "Using **Reaktoro** in Python requires an import of the python package `reaktoro`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3608dca4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from reaktoro import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2eebe77",
   "metadata": {},
   "source": [
    "The default thermodynamic databases embedded into Reaktoro is SUPCRT92, so you do not have to initialize the\n",
    "database `db = Database('supcrt98.xml')`, unless an alternative database must be used.\n",
    "\n",
    "### Initializing chemical editor\n",
    "\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.\n",
    "To define the editor of the chemical system from the default database SUPCRT92, we use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "23035bca",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor = ChemicalEditor()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e23d9796",
   "metadata": {},
   "source": [
    "Alternatively, the editor can be initialized by the database instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "088a1d6b",
   "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": "f93e8906",
   "metadata": {},
   "source": [
    "### Preparation of chemical system definition\n",
    "\n",
    "Before the definition of chemical system, aqueous, gaseous, and mineral phases must be added. It can be done in\n",
    "various ways. Let us consider, first, the definition of aqueous species:\n",
    "\n",
    "* With method [ChemicalEditor::addAqueousPhase](\n",
    "https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html#a68cdc98877671b61490d0752b3060d91),\n",
    "the [AqueousPhase](https://reaktoro.org/cpp/classReaktoro_1_1AqueousPhase.html)\n",
    "can be created by specifying the names of the species one by\n",
    "one. These species names must conform to those used in the database that was specified during the initialization of\n",
    "the [ChemicalEditor](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html) object, otherwise, an exception\n",
    "will be thrown."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5efc7d96",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addAqueousPhase(\n",
    "    [\"H2O(l)\", \"H+\", \"OH-\", \"Na+\", \"Cl-\", \"HCO3-\", \"CO3--\", \"CO2(aq)\"]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89f400de",
   "metadata": {},
   "source": [
    "* Alternatively, instead of listing the names of the species one by one, which might require prior knowledge of the\n",
    "species names in the database, we can use method [ChemicalEditor::addAqueousPhaseWithElements](\n",
    "https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html#a2c11397b4d486cf0fc18ae26eaf87980).\n",
    "It permits the [AqueousPhase](https://reaktoro.org/cpp/classReaktoro_1_1AqueousPhase.html)\n",
    "object to be constructed by using a list of chemical element names. The database will be searched for all\n",
    "species that could be formed out of those elements. These species will then be used to construct\n",
    "[AqueousPhase](https://reaktoro.org/cpp/classReaktoro_1_1AqueousPhase.html) object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dadd7216",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addAqueousPhaseWithElements(\"H O C Ca Cl Mg\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e4a423b6",
   "metadata": {},
   "source": [
    "* Finally, [AqueousPhase](https://reaktoro.org/cpp/classReaktoro_1_1AqueousPhase.html)\n",
    "object can be also constructed by using a list of compounds or substance names that might not\n",
    "necessarily represent names of species in the database. The list of compounds will be broken into a list of element\n",
    "names, and the database will be similarly searched for all species that could be formed out of those elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2398ca0",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addAqueousPhaseWithElementsOf(\"H2O NaCl CO2\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "206fc9db",
   "metadata": {},
   "source": [
    "> **Note:** The call of\n",
    "[ChemicalEditor::addAqueousPhaseWithElements](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html#a2c11397b4d486cf0fc18ae26eaf87980) will result in larger chemical system than\n",
    "> call of [ChemicalEditor::addAqueousPhase](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html#a68cdc98877671b61490d0752b3060d91), where the specific aqueous species are provided.  In more demanding\n",
    "> applications (e.g., as a chemical solver in a reactive transport simulator), you might want to manually specify the\n",
    "> chemical species of each phase in your chemical system."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4988a05",
   "metadata": {},
   "source": [
    "To add gaseous phase, similar methods can be used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3dac10f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addGaseousPhase([\"H2O(g)\", \"CO2(g)\", \"H2(g)\", \"O2(g)\", \"CH4(g)\"])\n",
    "editor.addGaseousPhaseWithElements([\"H\", \"O\", \"C\"])\n",
    "editor.addGaseousPhaseWithElementsOf([\"H2O\", \"CO2\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb4b7d35",
   "metadata": {},
   "source": [
    "The [MineralPhase](https://reaktoro.org/cpp/classReaktoro_1_1MineralPhase.html) object is created by specifying the\n",
    "names of the species one by one. These species names must\n",
    "conform to those used in the database that was specified during the initialization of the\n",
    "[ChemicalEditor](https://reaktoro.org/cpp/classReaktoro_1_1ChemicalEditor.html) object,\n",
    "otherwise, an exception will be thrown. The example below describes the usage of this method for the creation of two\n",
    "pure mineral phases and one solid solution with two mineral species."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15cf07de",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addMineralPhase(\"Calcite\")\n",
    "editor.addMineralPhase(\"Dolomite\")\n",
    "editor.addMineralPhase([\"Dolomite\", \"Calcite\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ee03ad3",
   "metadata": {},
   "source": [
    "There are two more alternatives to add [MinerialPhase](https://reaktoro.org/cpp/classReaktoro_1_1MineralPhase.html),\n",
    "i.e.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e9e8afb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.addMineralPhaseWithElements([\"Ca\", \"C\", \"O\"])\n",
    "editor.addMineralPhaseWithElementsOf([\"CaCO3\", \"MgCO3\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33ea0b28",
   "metadata": {},
   "source": [
    "Besides phases, one could also set temperatures and pressures of considered chemical system for constructing\n",
    "interpolation tables of thermodynamic properties., e.g.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "675d58ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "editor.setTemperatures([60, 80, 100, 120, 140, 160], \"celsius\")\n",
    "editor.setPressures([1, 10, 100], \"bar\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "697ad910",
   "metadata": {},
   "source": [
    "Finally, the definition of the chemical system is done by calling"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43ebd4e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "system = ChemicalSystem(editor)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}