PyCO2SYS: marine carbonate system calculations in Python

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 MATLAB. Documentation is online: pyco2sys.readthedocs.io. Changes in v1.3.0 New features Added bicarbonate ion (type 7) and aqueous CO2 (type 8) as options for known input marine carbonate system variables. Added module test with functions to perform internal consistency checks on PyCO2SYS.CO2SYS calculations and compare results with those from other sources. Added module api with a wrapper for PyCO2SYS.CO2SYS to allow inputs as Pandas Series and/or Xarray DataArrays. Improved calculations The Revelle factor and all other buffer factors added in v1.2 are now evaluated using automatic differentiation, which means that the effects of all equilibrating species are taken into account. The original, non-automatic functions that do not account for nutrient effects are still available in buffers.explicit. Can switch between calculation methods using new optional input buffers_mode. Corrected Revelle factor calculations: Added missing "Peng correction" to Revelle factor calculation at output conditions. Note that this correction is currently also missing from CO2SYS for MATLAB! Decreased DIC perturbation size for more accurate finite-difference "explicit" evaluation. Finite-difference calculation now references the correct DIC value. Implemented better initial guesses for pH in all iterative solvers in solve.get following M13 and OE15. Switched to using exact slopes in iterative solvers in solve.get, evaluated using Autograd in new submodule solve.delta. Updated entire package to be Autograd-able. Return NaN instead of negative DIC if an impossible pH-alkalinity combination is given as input (i.e. pH is too high). Return NaN where DIC and one of its components is given if the component is impossibly large. Internal reorganisation Major internal reorganisation that is probably not fully captured in these notes. Renamed modules: assemble is now engine. concentrations is now salts. extra is now buffers.explicit. Module equilibria now contains sub-modules: p1atm for calculating constants at atmospheric pressure. pcx for determining pressure correction factors. pressured for calculating constants at given pressure. Module solve now contains sub-modules: initialise to generate first-guess estimates of pH for the TA-pH solvers. get to calculate a new system variable from various input pairs. Added module solubility for mineral solubility calculations. Relocated _CaSolubility function from root to solubility.CaCO3. Separated out its internal calculations into a set of subfunctions also in the solubility module. Added calcium molinity TCa as an input, instead of being evaluated internally. Added calcium molininty TCa (estimated from salinity) into the main CO2dict output from PyCO2SYS.CO2SYS. Relocated _RevelleFactor function from root to buffers.RevelleFactor. Relocated _FindpHOnAllScales function from root to convert.pH2allscales. Added module constants for storing values of universal physical constants. Lists of equilibrium constants and total concentrations now passed around internally as dicts, for safety. Total sulfate and bisulfate dissociation constant renamed from TS and KS to TSO4 and KSO4 internally to avoid confusion with sulfide species. The as-close-as-possible MATLAB clone in PyCO2SYS.original no longer produces a dict but just the original DATA, HEADERS and NICEHEADERS outputs. Miscellaneous Documentation substantially expanded and switched to using Material for MkDocs. Validation section added with internal consistency checks and an external comparison of PyCO2SYS calculations with CO2SYS for MATLAB. All code now formatted with Black (except for module original). Version number now reported with PyCO2SYS.say_hello() in homage to the original MS-DOS program