PHREEQC Databases
=================

Every PHREEQC calculation is made against a thermodynamic database, and the
database decides the answer as much as the input does. The same water, the
same keywords, two databases: two results, both correct for what they were
asked.

This chapter is about choosing one, looking inside it, and comparing it with
another. Looking inside and comparing are the **Database** module, which is
licensed; importing and using a database is part of the Phreeqc module and
needs no licence.


Importing a database
--------------------

A PHREEQC lab holds its databases under **Databases**. A new project starts
with ``phreeqc.dat`` already loaded.

To add another, add an *Imported Database* and either load the file into its
editor or paste the text in. Then **compute** it: a database is read and
indexed before anything can use it, and until that is done it is text rather
than thermodynamics.

Right-click a database and choose *Set As Default* to make it the one new
components use.

Databases are stored **inside the project**, not referenced from disk. A
project you send someone carries the database it was run against, which is
what makes a result reproducible. It also means a project does not follow a
database you later edit — recompute it deliberately.


Which database
--------------

The databases that ship with PHREEQC differ in scope, not quality, and the
choice is a scientific one:

``phreeqc.dat``
   The general-purpose default. Ion association, a broad element list,
   reliable for dilute to moderately saline waters.

``wateq4f.dat``
   Close to ``phreeqc.dat``, with more trace elements.

``llnl.dat``
   Very large, from Lawrence Livermore. Many more species and phases, over a
   wide temperature range. It costs noticeably more to run — if a project
   feels slow, this is often why.

``pitzer.dat``
   Pitzer specific-ion interaction rather than ion association. **This is the
   one to use for brines**: ion association breaks down at high ionic
   strength, and ``phreeqc.dat`` will give confident wrong answers for a
   concentrated solution. In exchange it covers far fewer elements.

``sit.dat``
   Specific ion interaction theory, the convention of the NEA thermodynamic
   database.

``Amm.dat``, ``iso.dat``
   Ammonia speciation and isotopes.

The rule of thumb: match the database to the ionic strength first and to the
element list second. A database that lacks your element cannot be used; a
database that is wrong about activity coefficients will not tell you so.


Looking inside one
------------------

A **database study** turns one database into tables you can read, filter and
plot:

* elements and their valence states;
* species, and master species;
* phases;
* reactions and their terms;
* rates;
* the warnings raised while importing it;
* an **overview** of eight counts — how big this database is;
* the **relationships**: each element as a root, with the items under it.

This is how to answer "does this database have what I need?" without reading
a 5 MB text file.


Comparing databases
-------------------

A **database comparison study** takes several databases of a lab and a system
you care about — written as the elements involved, for example ``Ca, C,
Fe(3)`` — and reports:

* what each database **has and lacks** for that system;
* the species and phases per element and valence state;
* **where** each species and phase is defined;
* how the **log K differs** where the reaction is written the same way;
* **log K against temperature**.

The last two are the useful ones. A species present in both databases with
different log K values will give different results, and the comparison shows
the size of the disagreement before you discover it as a discrepancy between
two projects.

The caveat on the log K comparison is in its own definition: *where the
reaction is written alike*. The same equilibrium written with a different
reaction has a different constant, and those are not comparable as numbers.

Hierarchical plots — sunburst, treemap and icicle — are the natural way to
look at any of this, since a database is a hierarchy of elements, valence
states and species.


Examples
--------

* :ref:`01 – Database Comparison <example-database-01>` — which database covers a Ca-C-S-Fe-U water.
* :ref:`02 – Phreeqc Relationships <example-database-02>` — the structure of ``phreeqc.dat``.
* :ref:`03 – Calcite and Quartz in Four Databases <example-database-03>` — the same two minerals in four
  databases, and the three different ways they disagree.