Running an analysis¶

After installing PhreeqPython, an analysis is: create an engine, add a solution, query it, and remove it when you no longer need it. Nothing has to be listed in SELECTED_OUTPUT first.

You can run these examples

Click Run (or Ctrl+Enter), or Run all to execute every editor in order. The first run loads Pyodide and can take a few seconds. Editors on this page share a session, so later cells reuse pp and solution.

Create a PhreeqPython instance¶

Import the package and construct a PhreeqPython object. That object is the engine: it loads a thermodynamic database (default vitens.dat) and keeps the numbered PHREEQC entities in memory — solutions, gases, and equilibrium phases.

Editor (session: analysis)Run

from phreeqpython import PhreeqPython

pp = PhreeqPython()
print('solutions in the engine', pp.get_solution_list())

OutputClear

Every Solution (and gas or phase) you create is stored on this instance. Mixing, copying, and reacting always go through that same engine.

Do not mix solutions from different instances

A Solution is a handle to a number inside one engine. a + b (and any other interaction) only works when both solutions belong to the same PhreeqPython instance. Creating a second instance starts a second, independent PHREEQC engine; solutions from one cannot be mixed, copied, or reacted with solutions from the other.

Set pp.ip.debug = True (or PhreeqPython(debug=True)) to print the PHREEQC snippets before they are sent.

Add a solution¶

add_solution creates water in the engine from PHREEQC SOLUTION keywords (pH, units, element totals, …). PhreeqPython assigns a number automatically: the first solution is 0, then 1, 2, and so on. The Python object is a handle to that numbered solution (solution.number).

Editor (session: analysis)Run

solution = pp.add_solution({
    'pH': 7,
    'units': 'mmol/kgw',
    'Na': 1,
    'Cl': 1,
})
print(solution)
print('number', solution.number)
print('solutions in the engine', pp.get_solution_list())

OutputClear

Copies and mixtures also get a new number. add_solution_simple is for a known chemical composition (for example 1 mmol NaOH); see Adding solutions.

Query a solution¶

After each calculation you can read Solution properties directly; pH, total, speciation, saturation indices, etc.

Editor (session: analysis)Run

print('pH', solution.pH)
print('Na mmol', solution.total('Na'))
print('Cl mmol', solution.total('Cl'))
print('SC', round(solution.sc, 1), 'uS/cm')

OutputClear

Forget a solution¶

PHREEQC keeps every numbered solution in the engine until you delete it. add_solution, copy(), and mixing (+ / *) each allocate a new number, so a long-running model — especially a loop that copies solutions, or a kinetic rate function that makes a temporary copy — can accumulate unused solutions and grow in memory.

Call forget() when you are done with a solution. That sends a PHREEQC DELETE for its number. Use get_solution_list() to see which numbers are still in the engine.

Editor (session: analysis)Run

print('before', pp.get_solution_list())
solution.forget()
print('after', pp.get_solution_list())

OutputClear