Skip to content

Aqueous Geochemical Speciation Calculations on the WORM Portal with AqEquil

This guide is for getting started with geochemical speciation calculations on the WORM Portal. Speciation calculations can be performed on the WORM Portal with AqEquil, a Python package that makes it easy to set up, perform, and visualize results from geochemical speciation software EQ3/6.

For full documentation visit the AqEquil code documentation.

What an aqueous speciation calculation?

Aqueous geochemical speciation is a way to estimate aqueous solution chemical composition at a desired temperature and pressure.

For example, if you provide an initial concentration of total CO2(aq), the speciation calculation will check how much of the CO2 reacts to form other carbon compounds:

CO2 + H2O ⇌ HCO3- + H+ ⇌ CO32- + 2H+

Protons are involved in these equilibrium reactions so the pH of the system will affect how much of each carbon compound is expected to coexist in solution. Temperature and pressure will also make a difference.

If an initial concentration of Ca2+ is also provided, ion complexation with these carbon species can also be taken into account (e.g., CaHCO3+, CaCO3(aq)).

If you do not have initial concentrations of aqueous species, you can instead set the solution to be in equilibrium with minerals. For instance, you can set the concentration of CO2(aq) to be in equilibrium with dolomite, Fe2+ to magnetite, and so on.

A handful of initial concentrations can result in dozens upon dozens of calculated speciated solutes!

What results are calculated?

Be default, an speciation calculation performed on the WORM Portal will provide:

  • distributions of aqueous species - concentrations, activities, and chemical forms of dissolved species.

  • mineral saturation indices - minerals and solid solutions that are under- or super-saturated and their chemical affinities.

  • oxidation reduction (redox) potentials of common redox couples, e.g., O2/H2O, SO42-/HS-, NO3-/and NH4+

  • fugacities of gases - e.g. CO2(g), O2(g),

  • ion activity ratios - e.g. log(aMg2+/aH+2)

  • charge balance - equivalents of positive and negative charge and how closely they are balanced.

  • ionic strength - concentration of ions in solution.

Not calculated by default but is available as an option:

  • energy supply - how much energy is available (in calories per kg of water) for catalyzing redox reactions?

What kind of data should be collected before setting up a calculation?

There are two categories of data you need before performing a speciation calculation:

  1. A thermodynamic database. Here we will use the WORM database with properties of over 1000 aqueous, gaseous, and crystalline chemical species formatted into a large CSV table. You can read more about the format of the WORM database here, or browse through the entire database here.

  2. A set of input constraints. This is a set of starting parameters for your calculation. This could be a set of measurements collected from a water sample, a list of reagents added to a solution, a list of minerals in equilibrium with a fluid, or simply a set of guesses to see what happens.

Setting up a calculation

Create a new folder on the WORM Portal to store your project files. At the minimum, an aqueous speciation calculation needs:

  1. a CSV input file with calculation input constraints (sample chemistry data). A sample file can be found here. Download it with save as and upload it to your new project folder.
  2. a Jupyter notebook to execute the calculation. Create a new Python 3 notebook in your project folder.

Take a moment to examine the CSV input file input_example_wrm.csv. It contains temperature measurements and water chemistry data for six samples collected from hot springs in Yellowstone National Park, USA, Iceland, and from hyperalkaline springs in Oman. The file also includes columns containing metadata, such as when and where the sample was collected (Year and Area).

Open a new Python 3 Jupyter notebook in your project folder.

In the first cell, paste the following:

1
2
import AqEquil
ae = AqEquil.AqEquil()

The first line imports the AqEquil package that supports speciation calculations. The second line instantiates the ae object we will use to set up the calculation.

Create a new cell below this and paste the following:

1
2
3
4
speciation = ae.speciate(
      input_filename="input_example_wrm.csv",
      exclude=["Year", "Area"],
    )

Line 1 assigns the speciation object that will store results. The ae object has a function called speciate where you can set calculation options within the parentheses.

Line 2 tells the speciate function where to find your sample input CSV file.

Line 3 tells speciate to ignore the Year and Area columns in the CSV file. A Year or Area cannot be speciated so we must tell the code to exclude them.

Running the calculation

Run the notebook. You should get a message that looks like this: 

Warning: no 'logfO2' column found. Attempting to find a column for aqueous O2 to estimate logfO2 at sample temperature and pressure...

Warning: non-numeric aqueous O2 value in sample Crater Hills Geyser. Resorting to using Log fO2 (log bars) with a value of -6

Using wrm to speciate Crater Hills Geyser
Using wrm to speciate Gas Crack
Using wrm to speciate Spray Geyser Source
Using wrm to speciate Bison Pool
Using wrm to speciate Snail
Using wrm to speciate Ambergris
Using wrm to speciate MLS Source
Finished!

Congratulations, you have performed several aqueous speciation calculations!

Question

What do the warnings mean?

The first warning says that a logfO2 column was not found in the input CSV. This is okay! When speciating sample data, a redox value is necessary to estimate distributions of aqueous species. By default, the code looks for a logfO2 value. If it can't find one, it looks for an O2(aq) value to estimate logfO2 according to

O2(aq) ⇌ O2(g)

The second warning tells us that that the code couldn't find a numeric O2(aq) value for the sample "Crater Hills Geyser". Indeed, it is missing from the input file. The code has defaulted to a redox value of logfO2 = -6 for this sample.

The rest of the printout indicates that wrm was used to speciate sample data. This is an abbreviation for the default speciation thermodynamic database on the WORM Portal. This thermodynamic databases will be covered in more detail later, including how to quickly customize a database with your own species and pressure conditions.

Viewing results

Plotting

Create a new cell and run the following:

1
speciation.plot_mass_contribution("HCO3-", sort_by="pH")

This should generate an interactive plot comparing mole fractions of carbonate species across the six samples in the input file. Samples are arranged by pH (defined by sort_by) from lowest to highest (left to right).

Try replacing "HCO3-" with "Ca+2", set sort_by="Temperature", and run the cell again. Now your plot should look like this:

Take a look at hypothetical solid solutions in the Ambergris in a new cell:

1
speciation.plot_solid_solutions("Ambergris")

The upper plot shows the mole fraction of the solid solution endmembers. Calcium-carbonate is estimated to be 97% calcite and 3% magnesite.

Four solid solutions are supersaturated (blue, positive affinity), two are undersaturated (orange, negative affinity), and orthopyroxene is so close to equilibrium that its affinity bar is invisible.