Parameters
==========

A **parameter** is a named value you can use wherever a number is expected.
Parameters are what turn a single calculation into a study: a value written
once in the input is a constant, but a parameter can be swept, fitted or
sampled from a distribution without touching the model.

They are the feature the rest of the manual leans on. :doc:`studies` of every
kind beyond the plain PHREEQC study exist to vary them, and :doc:`fitting`
exists to determine them.


Creating one
------------

Parameters live in the **Parameters** branch, either of the project or of a
model. Add one, give it a name and a value.

A parameter's value can be a plain number or an **expression over other
parameters** — ``porosity * 2``, ``log10(k_calcite)``. A parameter defined in
terms of others is kept consistent with them: change the one and the other
follows.

Every parameter needs a value, including those a study is going to generate.
The value is what the model uses when the parameter is not being varied, and
it is where a fit starts from.


Using one
---------

In most fields a parameter is used by name.

In a **PHREEQC input**, where the surrounding text is PHREEQC's own syntax
rather than GibbsStudio's, a parameter is marked so that GibbsStudio knows to
substitute it. The marker is ``@{`` … ``}@``:

.. code-block:: text

   @{my_param}@

To calculate with it rather than just use it, put dollar signs inside the
marker as well. Everything between them is a mathematical expression:

.. code-block:: text

   SOLUTION 0
       Cl      @{$ini_conc$}@
       pe      @{$-1 * pe_param$}@
       Ca      @{$10^C_param$}@

The expression is evaluated and the result substituted before the input
reaches PHREEQC, so what PHREEQC reads is a number. :doc:`expressions` lists
what can go inside.

This is also the answer to "why is my parameter being ignored?" — a parameter
named in a PHREEQC input without the markers is just text, and PHREEQC will
read it as text.


Scope
-----

A parameter on the project is visible everywhere in it. A parameter on a
model is visible within that model.

Prefer the project for anything a study will vary, since that is where studies
look.


Choosing good parameters
------------------------

A few habits that save time later:

* **Name them for what they are**, not for where they appear. ``k_calcite``
  survives a rearranged input; ``param_1`` does not.
* **Parameterise the quantity, not its transform.** Make the rate constant
  the parameter and take its logarithm in the expression, rather than storing
  the logarithm — the number in the table is then the one you would quote.
  :doc:`fitting` can still fit it on a log scale.
* **Keep the count down.** Every parameter a study varies multiplies its cost,
  and every parameter a fit adjusts needs data to determine it.


Examples
--------

* :ref:`01 – Function Surface Drawing <example-hfstudio-01>` — numeric and text
  parameters, and a parameter whose value is an expression over another.
* :ref:`02 – Parametric Mixing <example-phreeqc-basics-02>` — a PHREEQC input
  parameterised and then swept in two dimensions.
* :ref:`03 – Saturation Indices with PHREEQC <example-akva-03>` — an input
  whose every varying value is a parameter, fed from a table of samples.