PyCO2SYS¶
PyCO2SYS v2
These are the docs for the forthcoming PyCO2SYS v2!
These instructions will not work for the current version 1.8 that can be installed through pip and conda - please see PyCO2SYS.readthedocs.io for documentation for the latest release.
If you are here to test PyCO2SYS v2, then create a test environment with Python v3.10 or greater, and then in that environment run
pip install git+https://github.com/mvdh7/PyCO2SYS@jax
This installs PyCO2SYS and its core requirements (JAX and NetworkX). If you wish to try out using PyCO2SYS with pandas and/or xarray, you'll need to install those into the environment separately.
PyCO2SYS is a Python toolbox for solving the marine carbonate system and calculating related seawater properties. It was originally based on CO2SYS for MATLAB1.
Installation¶
Don't follow these instructions
The installation instructions below are not yet active - see the box above if you're here to test PyCO2SYS!
JAX double precision
On import, PyCO2SYS should automatically set JAX in double precision mode. However, it's possible that this won't always happen, which will adversely affect the results. If a warning about this appears when running code, or to be on the safe side, set the environment variable JAX_ENABLE_X64=True to enforce this behaviour, for example:
conda env config vars set JAX_ENABLE_X64=True
With pip¶
Install from the Python Package Index:
pip install PyCO2SYS
With conda/mamba¶
Use pip on Windows
PyCO2SYS v2 cannot currently be installed through conda on Windows – use pip instead.
Install from the conda-forge channel:
conda install conda-forge::PyCO2SYS
How to use PyCO2SYS¶
Start with the
before moving on to
If you're really interested, also look at
If you're already familiar with PyCO2SYS v1, then
may help you to transition.
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.