Thermodynamic Backends
======================

.. image:: https://img.shields.io/badge/Reaktoro%20Tutorial-Interactive!-E66581.svg?logo=data:image/png;base64,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
   :target: https://mybinder.org/v2/gh/reaktoro/reaktoro-jupyter/master?filepath=tutorial%2Foverview.ipynb

There are excellent and mature open-source software for modeling chemical
systems for which development and maintenance has been ongoing for several
years to a few decades. Wouldn't it be great if Reaktoro could use the best
these software can offer in terms of thermodynamic databases and activity
models as *thermodynamic backends*, while relying on Reaktoro's numerical
algorithms for the intense chemical reaction calculations? Well, it turns out
this is already supported for two widely used geochemical modeling codes:
PHREEQC_ and GEMS_.

.. figure:: img/phreeqc-logo.svg
    :figwidth: 80%
    :width: 50%
    :align: center
    :target: PHREEQC_

    PHREEQC is a computer program for speciation, batch-reaction,
    one-dimensional transport, and inverse geochemical calculations developed
    by USGS, United States.

.. figure:: img/gems-logo.png
    :figwidth: 80%
    :width: 50%
    :align: center
    :target: GEMS_

    GEMS is a Gibbs energy minimization software for geochemical modeling
    developed at Paul Scherrer Institute, Switzerland.

.. note::

    Neither PHREEQC nor GEMS are used in Reaktoro for solving the underlying
    mathematical problems for chemical equilibrium and kinetics. These backends
    act as providers of thermodynamic properties of species, phases, and
    reactions (e.g., activity coefficients, activities, standard chemical
    potentials, phase molar volume and enthalpy, equilibrium constant of
    reaction). Whenever Reaktoro's numerical algorithms need these properties,
    the thermodynamic backend is invoked to retrieve them in a very efficient
    way by directly using its API. It seems complicated, but rest assure, the
    usage is rather simple as you'll see below!

PHREEQC Backend
---------------

The code below demonstrates the combined use of Reaktoro and PHREEQC to perform
a chemical equilibrium calculation in which PHREEQC thermodynamic data and
activity models are used together with Reaktoro's Gibbs energy minimization
algorithm.

.. literalinclude:: ../../demos/python/demo-backends-phreeqc.py
    :start-at: from
    :language: python

Python and C++ files for this demo:
    | :download:`demo-backends-phreeqc.py<../../demos/python/demo-backends-phreeqc.py>`
    | :download:`demo-backends-phreeqc.cpp<../../demos/cpp/demo-backends-phreeqc.cpp>`

GEMS Backend
------------

Similarly, the code below briefly demonstrates how Reaktoro and GEMS can be
used together. You'll need first to prepare your chemical system definition
using GEM-Selektor, the graphical user interface of GEMS. In this step, you'll
be able to select which GEMS' supported thermodynamic database you want to use
as well as the activity models for each phase (aqueous, gaseous, solid
solutions). Next, export the GEMS project files to disk, and use it in Reaktoro
as shown below.

.. literalinclude:: ../../demos/python/demo-backends-gems.py
    :start-at: from
    :language: python

Python and C++ files for this demo:
    | :download:`demo-backends-gems.py<../../demos/python/demo-backends-gems.py>`
    | :download:`demo-backends-gems.cpp<../../demos/cpp/demo-backends-gems.cpp>`

What about more thermodynamic backends?
---------------------------------------

Are there other chemical reaction modeling software that you think could be
integrated with Reaktoro as *thermodynamic backends*? Let us know by creating a
new issue at `Reaktoro's GitHub Issues`_.

.. attention::
    It would be great if you could contribute to expanding the list of
    supported Reaktoro's thermodynamic backends. Contributions can be made in
    several forms, ranging from direct code contribution to financing a project
    in which one or more experts will implement this.

.. _PHREEQC: http://wwwbrr.cr.usgs.gov/projects/GWC_coupled/phreeqc/
.. _GEMS: http://gems.web.psi.ch/
.. _Reaktoro's GitHub Issues: https://github.com/reaktoro/reaktoro/issues/new