{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6e2640c5",
   "metadata": {},
   "source": [
    "# Functionality of Database class\n",
    "\n",
    "In this tutorial, we provide an explanation on the functionality of the class\n",
    "[Database](https://reaktoro.org/cpp/classReaktoro_1_1Database.html)\n",
    "that provides operations to retrieve physical and thermodynamic data of chemical species.\n",
    "\n",
    "### Importing the reaktoro Python package\n",
    "\n",
    "Using **Reaktoro** in Python requires first an import of the python package `reaktoro`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5e0138e8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from reaktoro import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e9851ed",
   "metadata": {},
   "source": [
    "From this point on, we are able to use the library components of Reaktoro (classes, methods, constants), which are\n",
    "needed to define our chemical system and chemical reaction modeling problems.\n",
    "\n",
    "> **Note:** To simplify the tutorials, we\n",
    "use `from reaktoro import *`, which imports all components of the `reaktoro` package into the default Python\n",
    "namespace. In a more complex project, this can potentially create name conflicts. Thus, for bigger applications,\n",
    "consider using `import reaktoro as rkt`, and then refer to Reaktoro’s classes and methods as `rkt.Database`,\n",
    "`rkt.ChemicalSystem`, `rkt.equilibrate`, etc.\n",
    "\n",
    "Reaktoro currently supports the following thermodynamic databases:\n",
    "\n",
    "* SUPCRT92;\n",
    "* PHREEQC; and\n",
    "* GEMS.\n",
    "\n",
    "More information can be found on the web-page with the\n",
    "[Reaktoro's Documentation](https://reaktoro.org/thermodynamic-databases.html).\n",
    "\n",
    "### Initializing a thermodynamic database\n",
    "\n",
    "To initialize a thermodynamic database, we must provide xml-file, i.e.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "832b2537",
   "metadata": {},
   "outputs": [],
   "source": [
    "db = Database(\"supcrt98.xml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7257f668",
   "metadata": {},
   "source": [
    "Here, we use [supcrt98.xml](https://github.com/reaktoro/reaktoro/blob/master/databases/supcrt/supcrt98.xml)\n",
    "database file generated from the original **SUPCRT92** database file slop98.dat.\n",
    "\n",
    "> **Note:** If filename does not point\n",
    "to a valid database file or the database file is not found, then a default built-in database with the same name\n",
    "will be tried. If no default built-in database exists with a given name, an exception will be thrown.\n",
    "\n",
    "### Accessing the content of thermodynamic database\n",
    "\n",
    "It is possible to print all the aqueous species contained in the database SUPCRT92, i.e.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2fb61d4d",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of all aqueous species in database SUPCRT92:\")\n",
    "for aqueous_species in db.aqueousSpecies():\n",
    "    print(aqueous_species.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a0a482be",
   "metadata": {},
   "source": [
    "Similar output can be written for the gaseous species (with exception of the function that return the list of such\n",
    "species), i.e.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7f15854e",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of all gaseous species in database SUPCRT92:\")\n",
    "for gaseous_species in db.gaseousSpecies():\n",
    "    print(gaseous_species.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ce8fd59",
   "metadata": {},
   "source": [
    "All the minerals included in the database can be accessed as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8361c372",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of all minerals in database SUPCRT92:\")\n",
    "for minerals in db.mineralSpecies():\n",
    "    print(minerals.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1598176c",
   "metadata": {},
   "source": [
    "To check if certain species is present in the database, one can use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bbe48ccd",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Is Zn++ present in the database? \", db.containsAqueousSpecies(\"Zn++\"))\n",
    "print(\"Is Calcite present in the database? \", db.containsMineralSpecies(\"Calcite\"))\n",
    "print(\"Is CO2(g) present in the database? \", db.containsGaseousSpecies(\"CO2(g)\"))\n",
    "print(\"Is Zn+ present in the database? \", db.containsAqueousSpecies(\"Zn+\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7b2b0b5",
   "metadata": {},
   "source": [
    "Besides, we can output all, say, aqueous species containing a particular element (e.g., hydrogen):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71f1e720",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of all aqueous species in database with hydrogen:\")\n",
    "for species in db.aqueousSpeciesWithElements([\"H\"]):\n",
    "    print(species.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4c3e8ea0",
   "metadata": {},
   "source": [
    "A thermodynamic database contains model parameters for the evaluation of standard thermodynamic properties of\n",
    "species and/or reactions (e.g., standard Gibbs energies, equilibrium constants). These properties can be accessed by\n",
    "fetching a particular element from the database:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "808610d5",
   "metadata": {},
   "outputs": [],
   "source": [
    "species = db.aqueousSpecies(\"CaCl2(aq)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f9e45f8",
   "metadata": {},
   "source": [
    "After obtaining a particular species, its properties can be obtained by calling corresponding function, e.g., we can\n",
    "output charge and dissociation of CaCl<sub>2</sub>:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8191254",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Charge of CaCl2(aq): \", species.charge())\n",
    "print(\"Dissociation CaCl2(aq): \", species.dissociation())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dad490eb",
   "metadata": {},
   "source": [
    "Alternatively, one can also use more recent SUPCRT databased from 2017:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0a53705",
   "metadata": {},
   "outputs": [],
   "source": [
    "db = Database(\"supcrt07.xml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf469be4",
   "metadata": {},
   "source": [
    "To list all the mineral species, we use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "31ebff8d",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"List of all minerals in database SUPCRT07:\")\n",
    "for minerals in db.mineralSpecies():\n",
    "    print(minerals.name())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c05b58da",
   "metadata": {},
   "source": [
    "Assume that we want to study the properties of pyrrhotite (FeS). To fetch it from the database,\n",
    "access its formula, molar mass, charge, as well as elements, which Pyrrhotite, is constructed from,\n",
    "the following code it used:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "843f96de",
   "metadata": {},
   "outputs": [],
   "source": [
    "species = db.mineralSpecies(\"Pyrrhotite\")\n",
    "\n",
    "print(\"Formula of Pyrrhotite:\", species.formula())\n",
    "print(f\"Molar mass of Pyrrhotite: {species.molarMass():4.4e} kg/mol\")\n",
    "print(\"Charge of Pyrrhotite:\", species.charge())\n",
    "print(\"Name : Molar mass \")\n",
    "for elements in species.elements():\n",
    "    print(f\"{elements.name():>4} : {elements.molarMass()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "802d9c78",
   "metadata": {},
   "source": [
    "Similar output can be done, for instance, for Siderite (FeCO3):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "69993e54",
   "metadata": {},
   "outputs": [],
   "source": [
    "species = db.mineralSpecies(\"Siderite\")\n",
    "\n",
    "print(\"Formula of Siderite:\", species.formula())\n",
    "print(f\"Molar mass of Siderite: {species.molarMass():4.4e} kg/mol\")\n",
    "print(\"Charge of Siderite:\", species.charge())\n",
    "print(\"Name : Molar mass \")\n",
    "for elements in species.elements():\n",
    "    print(f\"{elements.name():>4} : {elements.molarMass()}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}