What is Kgen?

Kgen provides a uniform and internally-consistent way of calculating stoichiometric equilibrium constants (Ks) in modern and palaeo seawater as a function of temperature, salinity, pressure and the concentration of Mg and Ca, using Matlab, Python, and R.

Why does Kgen exist?

Determining the ‘best’ way to calculate Ks is not straightforward, and it is very easy to introduce typos and errors when manually implementing K calculation. Kgen solves this by providing an open-source, internally consistent way to calculate Ks across multiple languages.

There are multiple tools available for calculating the speciation of carbon in seawater, implemented across multiple platforms and languages. These are used to calculate the state of carbon in modern seawater, and incorporated into routines used to construct records of carbon in palaeo-seawater by integrating proxy records. All of these approaches rely on Ks, which describe the dissociation of weak acids and bases in seawater as a function of pH.

The history of calculating seawater Ks is long and tortuous, plagued by generations of typos and inconsistencies. Thanks to the heroic efforts of a lot of people, these discrepancies have been gradually corrected over time to the point where the majority of carbon calculation tools produce comparable results in modern seawater. However, the corrections to get to this point are often done in the back-end of manually-maintained code repositories, where it is difficult to keep track of what has changed when, and which of the numerous historic definitions in the literature is ‘correct’.

This presents newcomers to the field seeking to calculate Ks with a daunting array of options. How do they calculate Ks in seawater, and how do they know if their calculations are correct?

This issue has been largely solved in modern seawater by publications such as the `Guide to Best Practices for Ocean CO₂ Measurement’ (Dickson, Sabine and Christian, 2007), which provides a clear and concise description of K calculation along with ‘check values’ to confirm your implementation of them.

This issue is more complex in palaeo-seawater, where secular changes in seawater chemistry require the modification of Ks to account for these changes. This was elegantly accomplished using the MyAMI ion interaction model (Hain et al., 2015), although initial debate over some parameters in the model, alongside errors in the K ‘look up table’ provided in the initial publication further muddied the waters here.

With Kgen, we aim to transparently address all these uncertainties, and present a single reference implementation for K calculation that can be used across multiple platforms and languages.

What does Kgen do?

Kgen provides a single function (calc_Ks) in Matlab, Python, and R, which takes the temperature, salinity, pressure, [Mg] and [Ca] concentrations, and returns K₀, K₁, K₂, K_W, K_B, K_S, K_spA, K_spC, K_P1, K_P2, K_P3, K_Si, and K_F at the specified conditions.

How does Kgen do this?

For modern seawater, we use the reference formulae for K calculation and pressure corrections in Dickson, Sabine and Christian (2007). These functions have been manually implemented in each language, but all use a shared database of coefficients within these functions, ensuring that the Ks are consistent across all languages.

For Mg and Ca adjustment, we use a modified version of the MyAMI ion interaction model (Hain et al., 2015), which is available as a standalone Python package pymyami. This modification of MyAMI brings a number of improvements over the original, most notably calculation speed (2-4 orders of magnitude faster). For a full account of these differences, see the pymyami GitHub page.

For cases where calculation speed is of particular concern, we also provide a polynomial approximation of the K correction factors calculated by MyAMI (accurate to ~0.25%), which can be used instead of the full MyAMI calculation.

Python and R directly use the pymyami package to correct Ks for Mg and Ca, and can use either the direct calculation method or the polynomial approximation. Matlab can only use the polynomial approximation.

How do we ensure that the Ks are correct?

Kgen conducts a number of automated tests whenever the underlying code is changed, which ensure the long-term consistency and stability of the calculated values:

1. Calculated Ks and pressure correction factors for modern seawater are checked against the nominal values provided in Dickson, Sabine and Christian (2007).

1. MyAMI correction factors for seawater Mg and Ca produced by the pymyami package are checked against values produced by the original model of Hain et al., (2015), with modifications after Zeebe & Tyrrel (2018).

1. To ensure consistency between languages, we calculate Ks across the complete valid input range of temperature, salinity, pressure, Mg and Ca with each language, and conduct an inter-comparison between the Ks calculated by each language.

A note on pH Scales

All the Ks calculated by Kgen are on the Total pH scale, assuming modern ocean SO₄ concentration.