Models
======

**Models** is the branch of the project tree that holds what is being
described — the chemistry, or the mathematics. A study runs *on* a model; the
model itself does not run.

Two kinds live here:

* a **PHREEQC lab**, which is the subject of this chapter;
* a **function model**, a set of named mathematical expressions, for problems
  with no chemistry in them. Function models are useful in their own right and
  are what the "analytic" examples use to show a study type without PHREEQC
  in the way.

Earlier versions of GibbsStudio called this branch *Chemistries*.


The PHREEQC lab
---------------

A lab is a self-contained PHREEQC setting: the databases available to it, the
chemical components defined in it, the input models, and the selected outputs
that say what to record. A project can hold more than one, and they are
independent — two labs can use different databases without interfering.

A new project is created with a lab already in it, carrying ``phreeqc.dat``,
a default selected output and a simple input model, so there is something to
run from the start.

Under a lab:

**Parameters**
   Parameters local to this lab. They behave as project :doc:`parameters` do,
   but are scoped here.

**Databases**
   The thermodynamic databases, and which is the default. See
   :doc:`databases`.

**Components**
   The chemistry defined once and reused: *Solutions*, *Equilibrium Phases*
   and *Selected Outputs*.


Components
----------

A component is a piece of PHREEQC chemistry held as an entity rather than as
text, so it can be named, reused by several models, and pointed at by
parameters.

**Solutions**
   Water compositions.

**Equilibrium Phases**
   The minerals and gases a solution is allowed to equilibrate with.

Defining these as components rather than writing them into the input is what
lets a parametric study vary them: a parameter in a component's field is
swept, fitted or sampled like any other.


Selected outputs
----------------

A **selected output** says what PHREEQC should record from each simulation.
It is not a detail — it decides what exists afterwards. Nothing that is not
in the selected output is available later to a filter, a table or a plot,
whatever the simulation computed internally.

Choose the database first, then pick the fields from the list it offers.

Species, phases and totals written **directly in the input file** do not
appear in that list, because the list comes from the database rather than
from your input. They can still be recorded: type them into the box. They are
shown in amber in the selected list as a warning that they were not
recognised, and they will appear in the output if the simulation produces
them. Amber here means "not checked", not "wrong" — but it is also where a
typo hides, since a misspelt name simply produces nothing.

Recording everything is tempting and expensive: the selected output is
written for every simulation of every run, so a parametric study of a
thousand simulations writes it a thousand times. Record what you will use.


Input models
------------

A PHREEQC input model is the PHREEQC input itself, written in the editor. It
is analogous to a PHREEQC input file, with the restrictions described under
:doc:`studies`.


Examples
--------

* :ref:`01 – Function Surface Drawing <example-hfstudio-01>` — a function model
  and nothing else: the study machinery on a surface whose answer you
  already know.
* :ref:`02 – Trigonometric Function Drawing <example-hfstudio-02>` — one model,
  two outputs, and where a parameter is declared.
* :ref:`01 – Speciation calculation <example-phreeqc-manual-01>` — a PHREEQC lab, and
  how to add a species the database lacks without editing the database.