Submitted as: development and technical paper 08 Jun 2021

Submitted as: development and technical paper | 08 Jun 2021

Review status: this preprint is currently under review for the journal GMD.

PyCO2SYS v1.7: marine carbonate system calculations in Python

Matthew P. Humphreys1, Ernie R. Lewis2, Jonathan D. Sharp3,4, and Denis Pierrot5 Matthew P. Humphreys et al.
  • 1NIOZ Royal Netherlands Institute for Sea Research, Department of Ocean Systems (OCS), Texel, the Netherlands
  • 2Environmental and Climate Sciences Department, Brookhaven National Laboratory, Upton, NY, USA
  • 3Cooperative Institute for Climate, Ocean, and Ecosystem Studies, University of Washington, Seattle, WA, USA
  • 4Pacific Marine Environmental Laboratory, National Oceanic and Atmospheric Administration, Seattle, WA, USA
  • 5Atlantic Oceanographic and Meteorological Laboratory, National Oceanic and Atmospheric Administration, Miami, FL, USA

Abstract. Oceanic dissolved inorganic carbon (TC) is the largest pool of carbon that interacts considerably with the atmosphere on human timescales. Oceanic TC is increasing through uptake of anthropogenic carbon dioxide (CO2), and seawater pH is decreasing as a consequence. Both the exchange of CO2 between ocean and atmosphere and the pH response are governed by a set of parameters that interact through chemical equilibria, collectively known as the marine carbonate system. To investigate these processes, at least two of the marine carbonate system's parameters are typically measured – most commonly, two from TC, total alkalinity (AT), pH, and seawater CO2 fugacity (fCO2; or its partial pressure, pCO2, or its dry-air mole fraction, xCO2) – from which the remaining parameters can be calculated and the equilibrium state of seawater solved. Several software tools exist to carry out these calculations, but no fully functional and rigorously validated tool was previously available for Python, a popular scientific programming language. Here, we present PyCO2SYS, a Python package intended to fill this capability gap. We describe the elements of PyCO2SYS that have been inherited from the existing CO2SYS family of software and explain subsequent adjustments and improvements. For example, PyCO2SYS uses automatic differentiation to solve the marine carbonate system and calculate chemical buffer factors, ensuring that the effect of every solute and reaction is accurately included in all its results. We validate PyCO2SYS with internal consistency tests and comparisons against other software, showing that PyCO2SYS produces results that are either virtually identical or different for known reasons, with the differences negligible for all practical purposes. We discuss new insights that arose during the development process, for example that the marine carbonate system cannot be unambiguously solved from the total alkalinity and carbonate ion parameter pair. Finally, we consider potential future developments to PyCO2SYS and discuss the outlook for this and other software for solving the marine carbonate system. The code for PyCO2SYS is distributed via GitHub ( under the GNU General Public License v3, archived on Zenodo (Humphreys et al., 2021), and documented online (

Matthew P. Humphreys et al.

Status: open (until 03 Aug 2021)

Comment types: AC – author | RC – referee | CC – community | EC – editor | CEC – chief editor | : Report abuse

Matthew P. Humphreys et al.

Matthew P. Humphreys et al.


Total article views: 288 (including HTML, PDF, and XML)
HTML PDF XML Total BibTeX EndNote
239 48 1 288 1 2
  • HTML: 239
  • PDF: 48
  • XML: 1
  • Total: 288
  • BibTeX: 1
  • EndNote: 2
Views and downloads (calculated since 08 Jun 2021)
Cumulative views and downloads (calculated since 08 Jun 2021)

Viewed (geographical distribution)

Total article views: 150 (including HTML, PDF, and XML) Thereof 150 with geography defined and 0 with unknown origin.
Country # Views %
  • 1
Latest update: 15 Jun 2021
Short summary
The ocean helps to migitate our imact on Earth's climate by absorbing about a quarter of the carbon dioxide (CO2) released by human activities each year. However, once absorbed, chemical reactions between CO2 and water reduce seawater pH ("ocean acidification"), which may have adverse effects on marine ecosystems. Our Python package, PyCO2SYS, models the chemical reactions of CO2 in seawater, allowing us to quantify the corresponding changes in pH and related chemical properties.