Getting Started
===============

This is the ten-minute version: open something that already works, see where
everything is, change one thing, and watch the results follow. The
:doc:`quick_start` chapter builds a project from nothing; this one does not,
because the fastest way to understand GibbsStudio is to take a working
project apart.

You need GibbsStudio installed (:doc:`installation`). No licence is needed
for anything here.


Open an example
---------------

GibbsStudio ships with 48 example projects — real ones, including most of
the PHREEQC manual's examples. Open the browser from the welcome page or
with *File → Open Example...*; *Help → Manual* opens this document.

Start with :ref:`01 – Results Visualization <example-phreeqc-basics-01>`. It is
a 1D transport model with cation exchange, taken from
:ref:`example 11 <example-phreeqc-manual-11>` of the PHREEQC manual, set up with
several plots.

The project opens with its results already in it. Nothing has to be run
before you can look around — results are stored in the project file.


Look around
-----------

Work down the tree in the **Model dock** on the left. Every branch is
described in :doc:`project_model`; what matters now is the shape:

* **Models** holds the chemistry — a PHREEQC lab, with its database and its
  input.
* **Studies** holds the run that produced the results.
* **Data Analysis** holds the filters that cut the results into views.
* **Output** holds the tables and plots.

Select things as you go. The **Form dock** in the middle shows the selected
entity's settings; the **Main dock** on the right shows what it produces.
Select a plot and the plot appears; select the study and its output appears.

This is the whole interaction model. Everything else is detail.


Change something and recompute
------------------------------

Now make the project yours.

1. Select the PHREEQC input under **Models** and change a number — a
   concentration in the input, say.
2. Notice what happens to everything downstream: the study is marked **out of
   date**, and so is anything built on it. The plots still show the *old*
   results, because GibbsStudio does not re-run a simulation because you
   typed.
3. Press **Recompute** (``Ctrl+F5``). Watch the *Progress* tab of the
   **Message dock**.
4. The plots redraw.

That loop — change, recompute, look — is most of the work in practice. The
out-of-date marking is what stops you reading a plot that no longer matches
its input, which is easier to do than it sounds.


Make the change a parameter
---------------------------

Editing the input directly is fine for one value. The moment you want to try
several, make it a :doc:`parameters` instead:

1. Add a parameter under **Parameters**, with the value you just typed.
2. Replace the number in the PHREEQC input with ``@{my_parameter}@`` — the
   markers tell GibbsStudio to substitute the parameter there.
3. Recompute. The result should be identical, because nothing has changed
   except where the number lives.

Nothing visible has happened, and that is the point: the model now has a knob
on it. Every study type beyond the plain one — sweeping a range, fitting to
data, sampling a distribution — is a way of turning that knob. See
:doc:`studies`.


Where to go next
----------------

* :doc:`project_model` — the window, the tree and the vocabulary, properly.
* :doc:`quick_start` — building a PHREEQC project from nothing.
* :doc:`databases` — choosing a database, which matters more than it looks.
* :doc:`studies` — what else can be run, once a model has parameters.
* :doc:`results` — filters, tables, statistics and plots.

And keep opening examples. There are 48 of them, and they were written to be
read.