CITATION

• If you use any CO2SYS related software, please cite the original work by Lewis and Wallace (1998).
• If you use CO2SYS.m, please cite van Heuven et al (2011).
• If you use errors.m or derivnum.m, please cite Orr et al. (2018).

CO2SYS-MATLAB versions

• 1.1 (Sept 2011): van Heuven et al. (2011)
• 2.0 (20 Dec 2016): includes uncertainty propagation
• 2.0.1 (11 Oct 2017): supports TEOS-10 standards (conservattive temperature, absolute salinity)
• 2.0.2 (17 Oct 2017): Octave enhancements changed to be MATLAB compatible
• 2.0.3 (4 Jun 2018): examples added as Jupyter notebooks
• 2.0.4 (10 Nov 2018): defaults for standard uncertainties in constants (epK vector and eBt) made consistent with Orr et al. (2018), i.e., final published version
• 2.0.5 (23 Nov 2018): fixed bug in eBt propagation to deriv array (thanks A. Cochon)
• 2.1 (29 Jun 2020): fixed bug in derivnum affecting OUT results (linked to TEMPOUT); masked derivs of input vars in derivnum

ABOUT CO2SYS

Here you will find a MATLAB-version of CO2SYS, originally written for
DOS. CO2SYS calculates and returns a detailed state of the carbonate system for
oceanographic water samples, if supplied with sufficient input. Use the CO2SYS
function as you would use any other MATLAB inline function, i.e.,
a=func(b,c). For much detail about how to use CO2SYS, simply type "help CO2SYS"
in MATLAB. The help function also works for the two new uncertainty propagation
routines (errors and derivnum). For details on the internal workings of CO2SYS,
please refer to the original publication (Lewis and Wallace, 1998) available at
http://cdiac.ornl.gov/oceans/co2rprt.html. Since CO2SYS and the two new
routines each allow input of vectors, with just one call they can process many
samples. Each sample may have a different salinity, temperature, pH scale,
dissociation constants, etc.

HISTORY

The original version for DOS was written by Lewis and Wallace
(1998). That was translated to MATLAB by Denis Pierrot at CIMAS,
University of Miami, Miami, Florida. Then that code was vectorized,
refined, and optimized for computational speed by Steven van Heuven,
University of Groningen, The Netherlands. Although functionality was
added, the output of the CO2SYS function has not changed in form. All
versions of CO2SYS that are available at CDIAC (DOS, Excel, MATLAB)
should produce nearly identical results when supplied with identical
input. Indeed, close agreement between these different versions of
CO2SYS was demonstrated by Orr et al. (2015). More recently,
CO2SYS-MATLAB has been modified to include uncertainty propagation
(Orr et al., 2018): the main routine CO2SYS.m was altered slightly,
while two new routines were added (errors.m and derivnum.m)

If you discover inconsistencies or have a more general bug report for
CO2SYS.m, please notify S. van Heuven (svheuven at gmail.com), Denis
Pierrot (Denis.Pierrot at noaa.gov), or Alex Kozyr (kozyr at
ornl.gov). For any concerns about the uncertainty propagation routines
(errors.m and derivnum.m), please contact James Orr (james.orr at
lsce.ipsl.fr)

INSTALLING

Download the m-files in the src directory (CO2SYS.m, errors.m, and derivnum.m);
you may also wish to download the examples in the examples directory. Place
these files in a local directory that is in MATLAB's search path, or add the
directory where they are located to MATLAB's search path. The latter can be
done with MATLAB's addpath command, for example

addpath ("my_matlab_directory/my_subdir")

Then run either of the examples in Matlab, or start using the CO2SYS routine
straight away.

COMPATIBILITY

Besides their use in MATLAB, the three functions (CO2SYS.m, derivnum.m, and
errors.m) also work well under octave, GNU's MATLAB clone.

EXAMPLES

Example MATLAB scripts demonstrating use of CO2SYS can be found in the
examples directory. Using the two new routines is similar, adding only
a few new arguments, e.g., for input uncertainties. More elaborate
examples are also available in another form in the 'notebooks'
directory. Either click on those files to visualize them (as HTML) or
download those files and use them interactively as jupyter
notebooks. Within MATLAB or octave, you may also use the native help
facility, i.e., by typing "help errors" or "help derivnum" to find out
more.

REFERENCES

Lewis, E. and Wallace, D. W. R. (1998) Program Developed for CO2
System Calculations, ORNL/CDIAC-105, Carbon Dioxide Inf. Anal. Cent.,
Oak Ridge Natl. Lab., Oak Ridge, Tenn., 38 pp.,
https://salish-sea.pnnl.gov/media/ORNL-CDIAC-105.pdf

Orr, J. C., J.-P. Gattuso, and J.-M. Epitalon (2015) Comparison of ten
packages that compute ocean carbonate chemistry, Biogeosciences, 12,
1483–1510, https://doi.org/10.5194/bg-12-1483-2015 .

Orr, J.C., J.-M. Epitalon, A. G. Dickson, and J.-P. Gattuso (2018) Routine
uncertainty propagation for the marine carbon dioxide system, in prep. for
Mar. Chem., in press, https://doi.org/10.1016/j.marchem.2018.10.006.

van Heuven, S., D. Pierrot, J.W.B. Rae, E. Lewis, and D.W.R. Wallace (2011)
MATLAB Program Developed for CO2 System Calculations. ORNL/CDIAC-105b. Carbon
Dioxide Information Analysis Center, Oak Ridge National Laboratory, U.S.
Department of Energy, Oak Ridge, Tennessee. https://doi.org/10.3334/CDIAC/otg.CO2SYS_MATLAB_v1.1