PyCO2SYS¶
PyCO2SYS is a Python toolbox for solving the marine carbonate system and calculating related seawater properties. Its core is a Python implementation of CO2SYS for MATLAB1.
Installation¶
With pip¶
Install from the Python Package Index:
pip install PyCO2SYS
Update an existing installation:
pip install PyCO2SYS --upgrade --no-cache-dir
With conda/mamba¶
Install from the conda-forge channel:
conda install PyCO2SYS -c conda-forge
Basic use¶
The import convention for PyCO2SYS is:
import PyCO2SYS as pyco2
and the only function you need is:
results = pyco2.sys(**kwargs)
Read How to use PyCO2SYS for more on pyco2.sys, its kwargs and its results.
Examples¶
You can see some working examples of PyCO2SYS in action on Github at PyCO2SYS-examples. You can run all of the notebooks there live in your browser via Binder, without installing anything on your computer.
Adding your notebooks showcasing PyCO2SYS to PyCO2SYS-examples is welcomed!
About¶
PyCO2SYS is maintained primarily by Dr Matthew Humphreys of NIOZ Royal Netherlands Institute for Sea Research (Texel) with support from the main developers of all previous versions of CO2SYS.
Citation¶
A paper describing PyCO2SYS is freely available:
PyCO2SYS manuscript
Humphreys, M. P., Lewis, E. R., Sharp, J. D., and Pierrot, D. (2022). PyCO2SYS v1.8: marine carbonate system calculations in Python. Geoscientific Model Development 15, 15-43. doi:10.5194/gmd-15-15-2022.
To cite the PyCO2SYS software itself:
PyCO2SYS code citation
Humphreys, M. P., Schiller, A. J., Sandborn, D. E., Gregor, L., Pierrot, D., van Heuven, S. M. A. C., Lewis, E. R., and Wallace, D. W. R. (2024). PyCO2SYS: marine carbonate system calculations in Python. Zenodo. doi:10.5281/zenodo.3744275.
The DOI above refers to all versions of PyCO2SYS. Please specify which version of PyCO2SYS you used. You can find the version number that you are using in Python with:
import PyCO2SYS as pyco2
pyco2.hello()
You should also consider citing the original work by Lewis and Wallace (1998), and specify which optional sets of constants you used in your calculations.
History¶
The original CO2SYS program for DOS was created by Ernie Lewis and Doug Wallace (LW98). This was translated into MATLAB by Denis Pierrot and subsequently optimised by Steven van Heuven (HPR11). Jim Orr and co-authors added further sets of equilibrium constants and implemented error propagation in a separate program (OEDG18). The latest MATLAB version was translated into Python as PyCO2SYS by Matthew Humphreys, benefitting enormously from all this previous work. Further (ongoing) modifications and additions to the PyCO2SYS code and documentation have been made by Matthew Humphreys, Luke Gregor, Daniel Sandborn and Abigail Schiller (HSS21).
License¶
PyCO2SYS is licensed under the GNU General Public License version 3 (GPLv3).
Contributing¶
Suggestions for new features, bug reports and contributions to PyCO2SYS are very welcome. Please follow the contributing guidelines.
To add a notebook to PyCO2SYS-examples, please follow the contributing guidelines of that repo.