Skip to content

Version history

Semantics

Version numbering aims to follow semantic versioning. Therefore:

  • New patch versions (e.g. 1.1.0 to 1.1.1) make minor changes that do not alter fuctionality or calculated results.
  • New minor versions (e.g. 1.0.1 to 1.1.0) add new functionality, but will not break your code. They will not alter the results of calculations with default settings (except for in the hopefully rare case of correcting a bug or typo).
  • New major versions (e.g. 1.1.1 to 2.0.0) may break your code and require you to rewrite things. They may alter the results of calculations with default settings.

Warning

Will (not) break your code refers only to how you use the main CO2SYS function as imported with:

from PyCO2SYS import CO2SYS
CO2dict = CO2SYS(*args, **kwargs)

The only things that may change in this function, in at least a minor version release, are:

  1. Additional inputs may be added to the kwargs, but always with default values such that the results do not change if they are not explicitly set.
  2. Additional calculated variables may be returned in the output CO2dict.

The structure of the underlying modules and their functions is not yet totally stable and, for now, may change in any version increment. Such changes will be described in the release notes below.

1.3

Adds bicarbonate ion and aqueous CO2 as inputs from which the carbonate system can be solved. Continues to reorganise code behind the scenes. Makes everything Autograd-able and uses this approach to calculate buffer constants. Validates results against CO2SYS for MATLAB.

1.3.0 (1 May 2020)

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.

1.2

Adds additional buffer factor calculations that are not currently included in CO2SYS for MATLAB. New releases are henceforth assigned DOIs from Zenodo.

1.2.1 (9 Apr 2020)

Changes in v1.2.1

  • Fixed typo in ESM10 equations that had been carried through into extra.buffers_ESM10 function (thanks Jim Orr!).

1.2.0 (8 Apr 2020)

Changes in v1.2.0

  • Added module extra containing functions to calculate variables not included in CO2SYS for MATLAB:
  • buffers_ESM10 calculates the buffer factors of ESM10, corrected for the typos noted by RAH18.
  • bgc_isocap calculates the "exact" isocapnic quotient of HDW18, Eq. 8.
  • bgc_isocap_approx calculates the approximate isocapnic quotient of HDW18, Eq. 7.
  • psi calculates the \psi factor of FCG94.
  • Added all functions in extra to the CO2dict output of the main CO2SYS function, and documented in the Github repo README.

1.1

Adds extra optional inputs for consistency with Pierrot et al.'s forthcoming MATLAB "v1.21". Continues to reorganise subfunctions into more Pythonic modules, while avoiding changing the actual mechanics of calculations.

1.1.1 (20 Mar 2020)

Changes in v1.1.1

  • Removed unnecessary WhoseTB input to assemble.equilibria.

1.1.0 (19 Mar 2020)

Changes in v1.1.0

  • Updated pH-solving iterative functions so that iteration stops separately for each row once it reaches the tolerance threshold.
  • Extracted all functions for solving the CO2 system into a separate module (solve).
  • Extracted other key subfunctions into module assemble.
  • Added total ammonium (NH3) and hydrogen sulfide (H2S) concentrations as optional inputs to be included in the alkalinity model.
  • Added optional input to choose between different equations for hydrogen fluoride dissociation constant (KFCONSTANT).
  • Added functions to enable carbonate ion as an input carbonate system variable.
  • Output is now only the CO2dict dict, not the original DATA, HEADERS and NICEHEADERS.
  • Eliminated all global variables throughout the entire program.

1.0

1.0.1 (28 Feb 2020)

Starts to make things more Pythonic.

Changes in v1.0.1

  • Extracted all equations for concentrations and equilibrium constants into functions in separate modules (concentrations and equilibria).
  • Eliminated all global variables from the _Constants function.
  • Moved the as-close-as-possible version into module original. The default from PyCO2SYS import CO2SYS now imports the more Pythonic implementation.

1.0.0 (3 Feb 2020)

An as-close-as-possible clone of MATLAB CO2SYS v2.0.5.

Release notes for v1.0.0

  • The first output DICT is new: a dict containing a separate entry for each variable in the original output DATA, with the keys named following the original output HEADERS.
  • The output DATA is transposed relative to the MATLAB version because Numpy is row-major while MATLAB is column-major.
  • Every combination of input options was tested against the MATLAB version with no significant differences (i.e. all differences can be attributed to floating point errors).