The abundances of all solutes and total alkalinity provided as arguments to PyCO2SYS or returned from it as results are in units of micromoles per kilogram (µmol kg-1), with kilograms (kg) being of the total solution. This means that they are neither concentrations nor molarity values, which are both per unit volume rather than mass, nor are they molality values, which are per kilogram of H2O. Although sometimes referred to as molinity, the correct term is substance content , which we abbreviate to content.

Temperature is in degrees Celsius (∘C) and salinity is practical salinity, which is dimensionless .

Pressure is in decibars (dbar) and represents the hydrostatic pressure exerted by the overlying water column, consistent with typical oceanographic conductivity–temperature–depth (CTD) measurement reporting. Atmospheric pressure is not included, so pressure is effectively zero in the laboratory and at the sea surface.

The pH can be provided on the free, total, seawater, and/or NBS (now NIST) scale, with [H+] as a substance content, as noted above, and thus in moles per kilogram of solution (mol kg solution-1) Appendix ;. In the results, pH is returned on all four of these scales.

A notable feature of all CO2SYS software is the variety of different parameterisation options to calculate the various equilibrium constants and some components' total contents from salinity, temperature, and pressure. Which parameterisations the user selects can appreciably alter the results, so these choices should always be explicitly reported.

Some of these options also influence other, seemingly unrelated, parameters of other chemical systems. This is not widely appreciated because this happens internally, hidden within the code. The most influential choice is for the carbonic acid dissociation constants, K1* and K2*, for which there are 17 different options in PyCO2SYS (Table ). We organise these options into three groups based on their effect on the “hidden” internal parameterisations (Table ).

Standard case. These are all identical, aside from their varying carbonic acid constants.

Other internal settings are consistent across all cases (Table ). These three cases have been present since the original CO2SYS for MS-DOS . That program included only options 1–8 for the carbonic acid dissociation constants (Table ), with the others being published subsequent to its release. All subsequently added carbonic acid options follow the standard case. While it is beyond the scope of this paper to judge the relative merits of the different options, in general we recommend that one of the standard cases be used unless there is a specific reason for doing otherwise.

In addition to the carbonic acid equilibria, the user has multiple parameterisation options for each of the following: (i) the ratio between total borate and salinity, (ii) the bisulfate dissociation constant KSO4*, and (iii) the hydrogen fluoride dissociation constant KHF* (Tables  and ). However, note that for (i), the user's choice is not respected in the GEOSECS cases, and neither (ii) nor (iii) is included at all in the freshwater case (Table ). It should also be noted that choices (ii) and (iii) affect pH scale conversions, including of equilibrium constants, which can have a small (but practically negligible) effect on the results.

Equilibrium constants in PyCO2SYS are all stoichiometric rather than thermodynamic and thus denoted with K*. This means that they represent the equilibrium balance of solute substance contents, not of their chemical activities. They are evaluated as follows:

calculated on the pH scale reported in the literature as a function of temperature and salinity at zero in-water pressure;

There are some exceptions to the evaluation steps listed above. First, the pH scale conversions (steps 2 and 4) are not applied to KSO4*, KHF*, Ksp*(calcite), Ksp*(aragonite), or K0*. For KSO4* and KHF*, this is because these constants always remain on the free pH scale. The other constants in this list are for equilibria that do not directly involve H+ and are therefore independent of the pH scale. Second, no pressure correction (step 3) is applied to the CO2 solubility factor K0* . This value and calculations of fCO2, pCO2, and xCO2 are thus valid only for the surface ocean (Sect. ).

In PyCO2SYS, users can also specify their own values for any or all of the equilibrium constants or total salt contents. Any values specified in this way are used as-is throughout PyCO2SYS: no pH scale or pressure corrections are applied, so it is left to the user to ensure that the values are provided on the appropriate pH scale and at the relevant temperature and pressure.

A useful feature of all CO2SYS software that can nonetheless cause confusion is calculations at “input” and “output” conditions; “conditions” refers to temperature and pressure. There is an unhelpful overlap of nomenclature, with input and output used firstly in a programming context to refer to arguments that are passed into functions and returned from them as results, and secondly in a measurement context in which they refer to the temperatures and pressures under which the known parameter pairs are provided and at which results are to be calculated. For clarity, we therefore use the terms “arguments” and “results” in the programming context, while input and output always refer to the measurement context. Thus, we provide values at both input and output conditions as arguments to PyCO2SYS and we receive calculations at both input and output conditions as results from the program.

Input and output conditions are used when measurements were conducted at a different temperature and/or pressure from what the sample would experience in situ or to evaluate the effect of changing these conditions on the solution chemistry. All core carbonate system parameters except for AT and TC are temperature- and pressure-sensitive, so the values of other measured arguments and calculated results may differ between the input and output conditions. For example, measurements might be conducted in a laboratory at 25 ∘C on samples that were collected from several kilometres' depth in the ocean at sub-zero temperatures. In this case, we would provide the measurement conditions (i.e. temperature and pressure in the laboratory) as input arguments and the environmental conditions (i.e. temperature and pressure in the ocean) as output arguments. The corresponding output-condition results from PyCO2SYS then represent the true state of the sample in situ in its environment. The input-condition results are of less environmental interest but may be useful for quality-control purposes.

If calculations are conducted using only in situ values, for example from model output or with the temperature and pressure corrections already applied, then output-condition arguments need not be supplied. Results are then calculated only under the input conditions for computational efficiency.

We refer to the parameters from which PyCO2SYS can solve the marine carbonate system as the “core” marine carbonate system parameters. These are AT, TC, pH (on any scale), pCO2, fCO2, xCO2, [CO2(aq)], [HCO3-], and [CO32-]. Any pair of these can be provided, except for two of pCO2, fCO2, xCO2, and [CO2(aq)], which would not be valid because these are all directly proportional to each other at a given temperature, salinity, and atmospheric pressure.

To calculate its results (Fig. ), PyCO2SYS first determines the unknown core parameters from whichever pair is provided by the user under the input conditions (Appendix ). The parameter pairs that require an iterative solver to find pH (i.e. AT plus TC or one of its components) are solved using a scheme that has been updated from previous versions of CO2SYS (Sect. ). The AT and TC provided or determined under the input conditions are then used to solve the core marine carbonate system again under the output conditions if these have been provided. This is possible because both AT and TC are unaffected by temperature and pressure changes.

Other properties of interest are subsequently calculated from whichever core parameters are most convenient under both input and (if provided) output conditions. These properties include all the individual components of alkalinity (Appendix ), calcite, and aragonite saturation states (Appendix ), as well as various chemical buffer factors (Sect. ).

Like most iterative solvers, the Newton–Raphson method (Sect. ) requires an initial pH value that is near the true value in order to prevent overshoot and guarantee convergence to a root. Previous versions of CO2SYS used 8 as the initial pH estimate in every case. This works well for typical open-ocean seawater but may be less appropriate in niche environments or when modelling acidimetric titrations. found a better initial pH estimate for solving from known AT and TC by considering only the contributions of carbonate and borate species to AT, simplifying the AT equation. 3ACB=[HCO3-]+2[CO32-]+[B(OH)4-]

Following and as also implemented elsewhere e.g., PyCO2SYS and CO2SYS-MATLAB v3.2.0 also take this approach (Appendix ). Furthermore, we have extended it to apply to the pH solvers that use one of the components of TC as the second known parameter, as follows. We note that these extensions are equivalent to those described and discussed in greater detail by , although they were added to the PyCO2SYS code in its v1.3.0 release (10.5281/zenodo.3780139, ​​​​​​​) before the publication of that study.

As well as solving from a pair of parameters, PyCO2SYS can be run with one or no marine carbonate system parameter arguments.

If no parameters are provided, then PyCO2SYS returns all the equilibrium constants and total salt contents that are calculated from temperature, pressure, and salinity (Sect. ) without actually using these to do any further computations.

If one parameter is provided, then the results that can be computed with that parameter alone are returned. This applies to pH, pCO2, fCO2, xCO2, and [CO2(aq)], as follows.

The pH can be converted between the different scales without knowledge of a second carbonate system parameter. Therefore, if pH alone is provided to PyCO2SYS, it is converted to every pH scale under the input conditions (Appendix ). Conversion to a different temperature and/or pressure does require solving the carbonate system (Fig. ), so output-condition values are not calculated.

Seawater pCO2, fCO2, xCO2, and [CO2(aq)] can also be interconverted without knowledge of a second carbonate system parameter (Appendix ). Therefore, if any of these parameters alone are provided to PyCO2SYS, all the others are calculated under the input conditions. If an output-condition temperature is provided, then pCO2 is also adjusted to the new temperature following , and all others in this set of parameters are calculated under output conditions from the new pCO2 value.

All arguments to PyCO2SYS, including settings, can be multidimensional. A combination of scalar and multidimensional arguments can be provided, with the latter formatted as NumPy ndarrays . Results that depend only on scalar arguments are themselves scalar, while results depending on multidimensional inputs are “broadcasted” into consistently shaped arrays (Fig. ). The code is optimised to efficiently compute across multidimensional arrays following the approach of CO2SYS-MATLAB since its v1.1 . However, all multidimensional arrays in CO2SYS-MATLAB are flattened into one-dimensional vectors and returned in the results in that same format.

Propagating the uncertainty in an argument through to a result requires knowing the derivative of the result with respect to the argument. Uncertainty propagation is available for a subset of the arguments in the original MS-DOS CO2SYS and was added to the Excel and MATLAB implementations more recently . However, while much of the code to solve the marine carbonate system in PyCO2SYS has been directly inherited from CO2SYS-MATLAB, its implementation of uncertainty propagation differs.

PyCO2SYS evaluates the derivatives using a finite-forward-difference approach. We use finite differences rather than automatic differentiation here because the latter, while possible, is computationally inefficient to apply over the entire PyCO2SYS program. We use forward- rather than central-difference derivatives because the former can be safely evaluated at zero for variables for which negative values are impossible (e.g. salinity). The derivative of a result r with respect to an argument a is thus calculated. 23∂r(a)∂a≈r(a+Δa)-r(a)Δa The value of Δa is fixed for each argument (Appendix ). Different values for different arguments are necessary because some arguments can differ by over 20 orders of magnitude from others. If Δa is too large, then the derivative may be inaccurate because the equations governing the marine carbonate system are non-linear, but if Δa is too small, then the derivative may be inaccurate due to the limitations of solver tolerance and computer precision. We therefore tested a range of Δa values for each variable under typical open-ocean conditions and selected an appropriate value between these extremes (e.g. Fig. ). The full list of Δa values is provided in Table .

PyCO2SYS can conveniently obtain derivatives of all its results with respect to all of its arguments and also with respect to all parameters that are normally calculated internally from temperature, pressure, and/or salinity, such as equilibrium constants and total salt contents.

The derivatives are calculated by a function that wraps the entire PyCO2SYS program, rather than by adding extra internal variables that keep track of the effects of differences in to the arguments, as has been implemented elsewhere e.g.. The PyCO2SYS approach means that if the main program is producing valid results, then the derivatives can also be considered reliable without needing to verify some separate calculation mechanism.

To determine the overall uncertainty in each result, the uncertainty components from different arguments are combined using 24σ2(r)=∑i∂r∂ai2σ2(ai), where σ is the uncertainty as a standard deviation (thus, σ2 is a variance). However, Eq. () is only valid if the uncertainties in all arguments are independent from each other. Propagation of co-varying uncertainties can still be carried out with PyCO2SYS because, as noted above, the derivative of any result with respect to any argument can be calculated. The user can therefore assemble the Jacobian matrix of partial derivatives needed to propagate any arbitrary set of co-varying argument uncertainties through to any result .

We used CO2SYS-MATLAB v2.0.5 as the main alternative software to compare our results with. PyCO2SYS was originally created as an as-close-as-possible Python translation of this particular version, so any differences in the results should be both understood and intentional. Its predecessor, CO2SYS-MATLAB v1.1 , was included in the software intercomparison study of . Indeed, it was selected as the reference software to test the others against. CO2SYS-MATLAB v2.0.5 differs from v1.1 only in that it contains one additional parameterisation for the carbonic acid dissociation constants plus some extra internal variables associated with uncertainty propagation. Comparing PyCO2SYS with CO2SYS-MATLAB v2.0.5 therefore also shows PyCO2SYS's performance and reliability in the context of the wider set of software tested and discussed by .

However, these CO2SYS-MATLAB versions do not permit solving with either carbonate or bicarbonate ion content as a known parameter, nor do they include ammonia or sulfide speciation. They also lack the parameterisations of and for the carbonic acid dissociation constants (options 16 and 17 in Table ) and the parameterisation of for bisulfate dissociation (Table ). We therefore also tested PyCO2SYS against CO2SYS-MATLAB v3.2.0 , which does include all these options.

PyCO2SYS can be used to reproduce the closed-cell seawater titration datasets simulated by . Each simulated dataset contains pH values for a seawater sample as it is titrated with incremental HCl additions across a pH range from approximately 8 to 3.

specified exact values for all stoichiometric equilibrium constants. PyCO2SYS allows these to be provided instead of being calculated internally from temperature and salinity (Sect. ). The titration is then simulated by calculating how AT should change through the titration due to acid addition, accounting for dilution of AT, TC, and all other dissolved solutes by acid addition, and then solving the carbonate system for pH from the so-determined AT and TC. Being tested here is the ability to solve for pH from known AT and TC across a wide range of pH and AT values, including negative AT.

The first titration dataset, without phosphate, is reproduced perfectly by PyCO2SYS to the number of decimal places reported by . The second titration, with 10 µmol kg-1 of total phosphate included, is reproduced perfectly by PyCO2SYS with the exception of three values at different titrant masses.

0.45 g: pH either 6.588221 (Dickson) or 6.599221 (PyCO2SYS)

The other 48 data points in this titration agree perfectly. The noted discrepancies occur in non-consecutive data points and are therefore unlikely to all be associated with an error in a particular equilibrium. Coupled with the nature of the differences (underlined above), which is one or two specific digits switched or replaced rather than the entire number being different, we conclude that these differences most likely represent minor typographical errors and therefore that PyCO2SYS does accurately reproduce these simulations in full.

The aim of our revised scheme for initial pH estimates, following , was to find values that were closer to the final solution across a wide range of pH, thus providing a more suitable starting point for the iterative solvers and thereby reducing the number of iterations required to converge at the solution.

We find that the initial pH estimates determined according to the scheme described in Sect.  do follow a pattern similar to the final solutions across wide ranges of argument values, including at the extremes at which the initial-estimate equations become invalid and default pH values are used instead (Fig. ). The number of iterations required to fall beneath the solver's tolerance threshold (10-8 in pH) is also reduced compared with the original approach of always using an initial pH of 8. Indeed, for typical ocean conditions we find that the iterative solver often does not alter the initial estimate at all. Suitable starting points for the iterative solvers are clearly being found.

It is not strictly true that the marine carbonate system can always be solved from any pair of its parameters. Some combinations have multiple solutions. For example, both the AT–[CO32-] and TC–[HCO3-] pairs can correspond to two different pH values . In this section, we show how PyCO2SYS is designed to return the root corresponding to typical seawater. However, it is important to realise that these alternative pH values are real solutions that could be made up in the laboratory or be found in nature; they are not simply mathematical anomalies to be ignored. We therefore used PyCO2SYS to explore the compositions of these alternatives.

In PyCO2SYS, pCO2 (and by extension, fCO2 and xCO2) is always evaluated at a total pressure near 1 atm; it is not corrected for the pressure of the overlying water column (Sect. ). This approach is consistent with all existing implementations of CO2SYS. In practice, it means that these values represent the approximate pCO2 that seawater would have if it were brought to the surface ocean without changing the solution composition – “approximate” because this calculation should use potential temperature, rather than in situ temperature, to retrieve the true value expected after adiabatic decompression . PyCO2SYS does not calculate potential temperature, but this could be provided by the user in place of in situ temperature.

Although a pressure correction for pCO2 (i.e. a pressure correction for K0* and the fugacity factor; Appendix ) is theoretically possible , it could be argued that this is unnecessary. First, the vast majority of pCO2 measurements are carried out only at the surface ocean e.g., in part due to practical constraints of the “gold-standard” equilibrator-based methodology. Second, the concept of pCO2 has utility only in the context of air–sea CO2 exchange, which takes place only at the surface ocean.

However, recent developments in sensor technology are beginning to enable direct measurements of in situ pCO2 at depth in the ocean . There is also growing interest in calculating in situ pCO2 values at depth for intercomparison exercises in which the marine carbonate system has been overdetermined by measuring more than two of its core parameters e.g., and the relevant pressure correction is implemented in software tools such as seacarb and mocsy . Therefore, we anticipate an increasing need for pressure-corrected pCO2 values, and while we have kept the approach in PyCO2SYS consistent with other CO2SYS software for now, we consider a robust implementation of these calculations to be an important target for future code development.

One does not choose to write code in Python for its computational speed. Therefore, while optimising performance was not ignored in developing PyCO2SYS, it was not a main focus. We compared the computational speed of PyCO2SYS against that of CO2SYS-MATLAB v3.2.0 across a few different tasks for reference purposes. We ran CO2SYS-MATLAB in both MATLAB itself (expensive, proprietary software) and GNU Octave, a free and open-source MATLAB clone.

The different tasks are described in the subsequent sections, and the results are summarised in Table . Details of the computer and software used for testing are provided in Appendix .

Overall, the PyCO2SYS computation time has the same order of magnitude as CO2SYS-MATLAB, but it is generally somewhat slower. However, the difference is negligible in practice for relatively small datasets (up to about 105 data points) but may become more noticeable in larger calculations. Potential future improvements to PyCO2SYS's computational speed are discussed in Sect. .

The Autograd package that PyCO2SYS uses for automatic differentiation is still being maintained, and its most recent release (v1.3, July 2019) is stable, but it is no longer in active development. Its successor, JAX , has further benefits including “just-in-time” code compilation and parallelisation. These features could speed up computation speed in PyCO2SYS, especially the components involving automatic differentiation, potentially by several orders of magnitude. However, JAX cannot currently run natively on the Microsoft Windows operating system, which would greatly restrict the usability of PyCO2SYS for the oceanographic research community. This limitation is due to JAX's dependence on the separate XLA (accelerated linear algebra) compiler rather than being an intrinsic issue with JAX itself. Should this compatibility issue be resolved in the future, we envision updating PyCO2SYS to use JAX instead of Autograd. This should be relatively straightforward thanks to the close similarities between the API (application programming interface) of these packages.

As future developments are made to PyCO2SYS, we will aim to maintain consistency with other CO2SYS-family tools but cannot guarantee that all new features or updates will be added simultaneously across all implementations. In practice, the workload required to achieve this is not currently feasible, and we would not wish to hold back development because of the time required to replicate changes across multiple implementations. That said, the results should remain consistent enough that users can select which implementation to use based on their preferred software environment rather than the other way around.

This ambition could also extend beyond the CO2SYS family of software. Independently developed tools for solving the marine carbonate system exist in other languages, such as seacarb in R and mocsy in Fortran . These give sufficiently consistent results with each other that the selection of which tool to use does not affect scientific interpretation , and we have shown that PyCO2SYS is, and will remain, no exception. Even so, development and validation of PyCO2SYS so far have focused on comparisons with only CO2SYS-family software for practical reasons. Now that the basis of PyCO2SYS is established, we would welcome more direct interaction with the groups developing these other tools, working towards a set of marine–carbonate system-solving tools that return identical results regardless of the software platform. There can be a great advantage in having independent implementations led by different groups of researchers and developers. For example, this approach can help catch bugs and typographical errors, especially if each group extracts equations and parameterisations from the original literature instead of copying existing code. Working together, the groups would have a greater pool of knowledge and experience to identify errors in the literature (see e.g. , their Appendix A), which are often unpublished and known only through personal communications. But calculations must be regularly compared with each other if this advantage is to be realised.

Thanks largely to the efforts of , many tools now have an uncertainty propagation capability, as does PyCO2SYS. However, we still lack meaningful and statistically equivalent estimates for the actual uncertainties in the equilibrium constants. The software therefore stands ahead of our knowledge: as more work is done to robustly quantify these uncertainties, the tools are already in place to propagate them through to all marine carbonate system calculations.

As development of PyCO2SYS continues, we do not anticipate changing its fundamental approach to solving the marine carbonate system, but we will try to incorporate the latest research, including keeping up to date with new parameterisations, for example of stoichiometric equilibrium constants e.g.. Integration with a speciation model that can determine the equilibrium constants based on chemical activities, rather than parameterising these based on salinity, is an area of interest but would likely require such substantial changes to constitute a separate software tool. We do envision further additions to the main chemical speciation function in PyCO2SYS, for example to better represent the impact of organic contributions to alkalinity e.g. – noting that a simplified representation of such extra components can already be modelled in PyCO2SYS (Sect. ).

Through all these efforts, we aim to ensure that PyCO2SYS remains a reliable and comprehensive tool for analysing seawater chemistry from samples and experiments in the laboratory through to the changing marine carbonate system across the global ocean.