Calculate everything with pyco2.sys
¶
Syntax¶
From v1.6.0, the recommended way to run PyCO2SYS is to calculate everything you need at once with the toplevel pyco2.sys
function. The syntax is:
import PyCO2SYS as pyco2
results = pyco2.sys(
par1=None, par2=None, par1_type=None, par2_type=None, **kwargs
)
The simplest possible syntax above only requires values for two carbonate system parameters (par1
and par2
) and the types of these parameters (par1_type
and par2_type
). Everything else is assigned default values. To override the default values, add in the relevant kwargs
from below.
sys == CO2SYS_nd
pyco2.sys
is and will remain identical to pyco2.CO2SYS_nd
, which was introduced in v1.5.0 (and which still works in exactly the same way).
From v1.7.0, it is possible to run pyco2.sys
without providing any carbonate system parameters or with just one parameter (see below). All of the other optional arguments can still be used. In this case, the results
dict contains all the equilibrium constants and total salt contents under the specified conditions, e.g.:
# Convert a pH value to all pH scales, but don't solve the whole system:
results = pyco2.sys(par1=8.1, par1_type=3, **kwargs)
# Convert an fCO2 value to another temperature, but don't solve:
results = pyco2.sys(
par1=400, par1_type=5, temperature=12, temperature_out=25, **kwargs
)
# Evaluate all equilibrium constants and total salts at default conditions:
results = pyco2.sys()
You can also use pyco2.sys
to propagate uncertainties through your marine carbonate system calculations.
Arguments¶
Each argument to pyco2.sys
described on this page can either be a single scalar value, or a NumPy array containing a series of values. A combination of different multidimensional array shapes and sizes is allowed as long as they can all be broadcasted with each other.
pyco2.sys
arguments
For all arguments and results in μmol·kg^{−1}, the "kg" refers to the total solution, not H_{2}O. These are therefore most accurately termed substance content or molinity values (as opposed to concentration or molality).
Carbonate system parameters¶
Either two, one or no carbonate system parameters can be provided.
par1
andpar2
: values of two different carbonate system parameters.par1_type
andpar2_type
: which types of parameterpar1
andpar2
are.
If two parameters are provided, these can be any pair of:
 Total alkalinity (type
1
) in μmol·kg^{−1}.  Dissolved inorganic carbon (type
2
) in μmol·kg^{−1}.  pH (type
3
) on the Total, Seawater, Free or NBS scale^{1}. Which scale is given by the argumentopt_pH_scale
.  Any one of:
 Partial pressure of CO_{2} (type
4
) in μatm,  Fugacity of CO_{2} (type
5
) in μatm,  Aqueous CO_{2} (type
8
) in μmol·kg^{−1}, or  Dry mole fraction of CO_{2} (type
9
) in ppm.
 Partial pressure of CO_{2} (type
 Any one of:
 Carbonate ion (type
6
) in μmol·kg^{−1},  Saturation state w.r.t. calcite (type
10
), or  Saturation state w.r.t. aragonite (type
11
).
 Carbonate ion (type
 Bicarbonate ion (type
7
) in μmol·kg^{−1}.
If one parameter is provided, then the full marine carbonate system cannot be solved, but some results can be calculated. The single parameter must be given as par1
plus the relevant par1_type
, and it can be any of:
 pH (type
3
) on any scale, as above. In this case, the pH values are converted to all the other pH scales at the input conditions only.  Any one of types
4
(pCO_{2}),5
(fCO_{2}),8
([CO_{2}(aq)]) or9
(xCO_{2}) above. In this case, the others in this group of parameters are all calculated at the input conditions. If output temperatures are provided, then they are also all calculated at this condition by converting pCO_{2} to the new temperature following TSW09.
If no carbonate system parameters are provided, then all the equilibrium constants and total salt contents are returned, under the given conditions.
Hydrographic conditions¶
salinity
: practical salinity (default 35).temperature
: temperature at whichpar1
andpar2
arguments are provided in °C (default 25 °C).pressure
: water pressure at whichpar1
andpar2
arguments are provided in dbar (default 0 dbar).
If you also want to calculate outputs at a different temperature and pressure from the original measurements, then you can also use:
temperature_out
: temperature at which results will be calculated in °C ("output conditions").pressure_out
: water pressure at which results will be calculated in dbar ("output conditions").
For example, if a sample was collected at 1000 dbar pressure (~1 km depth) at an in situ water temperature of 2.5 °C and subsequently measured in a lab at 25 °C, then the correct values would be temperature=25
, temperature_out=2.5
, pressure=0
, and pressure_out=1000
.
If neither temperature_out
nor pressure_out
is provided, then calculations will only be performed at the conditions specified by temperature
and pressure
, and none of the results with keys ending with _out
will be returned in the CO2_results
dict. If only one of temperature_out
or pressure_out
is provided, then we assume that the other one has the same values for the input and output calculations.
Nutrients and other solutes¶
Some default to zero if not provided:
total_silicate
: total silicate in μmol·kg^{−1}.total_phosphate
: total phosphate in μmol·kg^{−1}.total_ammonia
: total ammonia in μmol·kg^{−1}.total_sulfide
: total hydrogen sulfide in μmol·kg^{−1}.total_alpha
: total Hα (a userdefined extra contributor to alkalinity) in μmol·kg^{−1}.total_beta
: total Hβ (a userdefined extra contributor to alkalinity) in μmol·kg^{−1}.
If using nonzero total_alpha
and/or total_beta
, then you should also provide the corresponding equilibrium constant values k_alpha
and/or k_beta
.
Others, PyCO2SYS estimates from salinity if not provided:
total_borate
: total borate in μmol·kg^{−1}.total_calcium
: total calcium in μmol·kg^{−1}.total_fluoride
: total fluoride in μmol·kg^{−1}.total_magnesium
: total magnesium in μmol·kg^{−1}.total_sulfate
: total sulfate in μmol·kg^{−1}.
If total_borate
is provided, then the opt_total_borate
argument is ignored.
Throughout, the kg in μmol·kg^{−1} refers to the total solution, not H_{2}O.
Magnesian calcite¶
PyCO2SYS calculates the saturation state with respect to magnesian calcite of varying Mg content following four different relationships (see Results section on carbonate mineral saturation).
calcite_Mg_percent
: the percent of Mg in calcite (i.e. 100 * molMg / (molMg + molCa)).
Atmospheric pressure¶
pressure_atmosphere
/pressure_atmosphere_out
: atmospheric pressure in atm.
This is used for conversions between pCO_{2}, fCO_{2} and xCO_{2}. If no value is provided, then 1 atm is assumed.
Settings¶

opt_pH_scale
: which pH scale was used for any pH entries inpar1
orpar2
, as defined by ZW01:1
: Total, i.e. \mathrm{pH} = \log_{10} ([\mathrm{H}^+] + [\mathrm{HSO}_4^]) (default).2
: Seawater, i.e. \mathrm{pH} = \log_{10} ([\mathrm{H}^+] + [\mathrm{HSO}_4^] + [\mathrm{HF}]).3
: Free, i.e. \mathrm{pH} = \log_{10} [\mathrm{H}^+].4
: NBS, i.e. relative to NBS/NIST reference standards.

opt_k_carbonic
: which set of equilibrium constant parameterisations to use to model carbonic acid dissociation:1
: RRV93 (0 < T < 45 °C, 5 < S < 45, Total scale, artificial seawater).2
: GP89 (−1 < T < 40 °C, 10 < S < 50, Seawater scale, artificial seawater).3
: H73a and H73b refit by DM87 (2 < T < 35 °C, 20 < S < 40, Seawater scale, artificial seawater).4
: MCHP73 refit by DM87 (2 < T < 35 °C, 20 < S < 40, Seawater scale, real seawater).5
: H73a, H73b and MCHP73 refit by DM87 (2 < T < 35 °C, 20 < S < 40, Seawater scale, artificial seawater).6
: MCHP73 aka "GEOSECS" (2 < T < 35 °C, 19 < S < 43, NBS scale, real seawater).7
: MCHP73 without certain species aka "Peng" (2 < T < 35 °C, 19 < S < 43, NBS scale, real seawater).8
: M79 (0 < T < 50 °C, S = 0, freshwater only).9
: CW98 (2 < T < 30 °C, 0 < S < 40, NBS scale, real estuarine seawater).10
: LDK00 (2 < T < 35 °C, 19 < S < 43, Total scale, real seawater).11
: MM02 (0 < T < 45 °C, 5 < S < 42, Seawater scale, real seawater).12
: MPL02 (−1.6 < T < 35 °C, 34 < S < 37, Seawater scale, field measurements).13
: MGH06 (0 < T < 50 °C, 1 < S < 50, Seawater scale, real seawater).14
: M10 (0 < T < 50 °C, 1 < S < 50, Seawater scale, real seawater).15
: WMW14 (0 < T < 45 °C, 0 < S < 45, Seawater scale, real seawater).16
: SLH20 (−1.67 < T < 31.80 °C, 30.73 < S < 37.57, Total scale, field measurements) (default).17
: SB21 (15 < T < 35 °C, 19.6 < S < 41, Total scale, real seawater).
The brackets above show the valid temperature (T) and salinity (S) ranges, original pH scale, and type of material measured to derive each set of constants.

opt_k_bisulfate
: which equilibrium constant parameterisation to use to model bisulfate ion dissociation: 
opt_total_borate
: which boron:salinity relationship to use to estimate total borate (ignored if thetotal_borate
argument is provided): 
opt_k_fluoride
: which equilibrium constant parameterisation to use for hydrogen fluoride dissociation: 
opt_buffers_mode
: how to calculate the various buffer factors (or not).1
: using automatic differentiation, which accounts for the effects of all equilibrating solutes (default).2
: using explicit equations reported in the literature, which only account for carbonate, borate and water alkalinity.0
: not at all.
For opt_buffers_mode
, 1
is the recommended and most accurate calculation, and it is a little faster to compute than 2
. If 0
is selected, then the corresponding outputs have the value np.nan
.

opt_gas_constant
: what value to use for the gas constant (R):1
: DOEv2 (consistent with other CO2SYS software before July 2020).2
: DOEv3.3
: 2018 CODATA (default).

opt_pressured_kCO2
: whether to correct the CO_{2} solubility constant for hydrostatic pressure following W74 (see discussion in section 2.1.3 of OE15):0
: do not apply the correction (default and the only option before v1.8.2).1
: apply the correction.
Override equilibrium constants¶
All the equilibrium constants needed by PyCO2SYS are estimated internally from temperature, salinity and pressure, and returned in the results. However, you can also directly provide your own values for any of these constants instead.
To do this, the arguments have the same keywords as the corresponding results dict keys. For example, to provide your own water dissociation constant value at input conditions of 10^{14}, use k_water=1e14
.
If nonzero using total_alpha
and/or total_beta
, you should also supply the corresponding stoichiometric dissociation constant values as k_alpha
/k_alpha_out
and/or k_beta
/k_beta_out
. If not provided, these default to pK = 7.
Results¶
The results of pyco2.sys
calculations are stored in a dict of NumPy arrays. The keys to the dict are listed in the section below.
Scalar arguments, and results that depend only on scalar arguments, will be returned as scalars in the dict. Arraylike arguments, and results that depend on them, will all be broadcast to the same consistent shape.
The keys ending with _out
are only available if at least one of the temperature_out
or pressure_out
arguments was provided.
pyco2.sys
results dict
Dissolved inorganic carbon¶
"dic"
: dissolved inorganic carbon in μmol·kg^{−1}."carbonate"
/"carbonate_out"
: carbonate ion at input/output conditions in μmol·kg^{−1}."bicarbonate"
/"bicarbonate_out"
: bicarbonate ion at input/output conditions in μmol·kg^{−1}."aqueous_CO2"
/"aqueous_CO2_out"
: aqueous CO_{2} at input/output conditions in μmol·kg^{−1}."pCO2"
/"pCO2_out"
: seawater partial pressure of CO_{2} at input/output conditions in μatm."fCO2"
/"fCO2_out"
: seawater fugacity of CO_{2} at input/output conditions in μatm."xCO2"
/"xCO2_out"
: seawater dry mole fraction of CO_{2} at input/output conditions in ppm."fugacity_factor"
/"fugacity_factor_out"
: fugacity factor at input/output conditions for converting between CO_{2} partial pressure and fugacity."vp_factor"
/"vp_factor_out"
: vapour pressure factor at input/output conditions for converting between xCO_{2} and pCO_{2}.
Alkalinity and its components¶
"alkalinity"
: total alkalinity in μmol·kg^{−1}."alkalinity_borate"
/"alkalinity_borate_out"
: borate alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_phosphate"
/"alkalinity_phosphate_out"
: phosphate alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_silicate"
/"alkalinity_silicate_out"
: silicate alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_ammonia"
/"alkalinity_ammonia_out"
: ammonia alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_sulfide"
/"alkalinity_sulfide_out"
: hydrogen sulfide alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_alpha"
/"alkalinity_alpha_out"
: Hα alkalinity at input/output conditions in μmol·kg^{−1}."alkalinity_beta"
/"alkalinity_beta_out"
: Hβ alkalinity at input/output conditions in μmol·kg^{−1}."peng_correction"
: the "Peng correction" for alkalinity (applies only foropt_k_carbonic = 7
) in μmol·kg^{−1}.
pH and water¶
"pH"
/"pH_out"
: pH at input/output conditions on the scale specified by inputopt_pH_scale
."pH_total"
/"pH_total_out"
: pH at input/output conditions on the Total scale."pH_sws"
/"pH_sws_out"
: pH at input/output conditions on the Seawater scale."pH_free"
/"pH_free_out"
: pH at input/output conditions on the Free scale."pH_nbs"
/"pH_nbs_out"
: pH at input/output conditions on the NBS scale."hydrogen_free"
/"hydrogen_free_out"
: "free" proton at input/output conditions in μmol·kg^{−1}."hydroxide"
/"hydroxide_out"
: hydroxide ion at input/output conditions in μmol·kg^{−1}."fH"
/"fH_out"
: activity coefficient of H^{+} at input/output conditions for pHscale conversions to and from the NBS scale.
Carbonate mineral saturation¶
"saturation_calcite"
/"saturation_calcite_out"
: saturation state of calcite at input/output conditions."saturation_aragonite"
/"saturation_aragonite_out"
: saturation state of aragonite at input/output conditions."saturation_Mg_calcite_biogenic"
/"saturation_Mg_calcite_biogenic_out"
: saturation state of magnesian calcite (biogenic, minimally treated) at input/output conditions."saturation_Mg_calcite_biogenic_treated"
/"saturation_Mg_calcite_biogenic_treated_out"
: saturation state of magnesian calcite (biogenic, treated) at input/output conditions."saturation_Mg_calcite_synthetic"
/"saturation_Mg_calcite_synthetic_out"
: saturation state of magnesian calcite (synthetic) at input/output conditions."saturation_Mg_calcite_fish"
/"saturation_Mg_calcite_fish_out"
: saturation state of magnesian calcite (fish, fixed 47.9% Mg) at input/output conditions.
Buffer factors¶
Whether these are evaluated using automatic differentiation, with explicit equations, or not at all is controlled by the input opt_buffers_mode
.
"revelle_factor"
/"revelle_factor_out"
: Revelle factor at input/output conditions^{2}."psi"
/"psi_out"
: ψ of FCG94 at input/output conditions."gamma_dic"
/"gamma_dic_out"
: buffer factor γ_{DIC} of ESM10 at input/output conditions^{3}."beta_dic"
/"beta_dic_out"
: buffer factor β_{DIC} of ESM10 at input/output conditions."omega_dic"
/"omega_dic_out"
: buffer factor ω_{DIC} of ESM10 at input/output conditions."gamma_alk"
/"gamma_alk_out"
: buffer factor γ_{TA} of ESM10 at input/output conditions."beta_alk"
/"beta_alk_out"
: buffer factor β_{TA} of ESM10 at input/output conditions."omega_alk"
/"omega_alk_out"
: buffer factor ω_{TA} of ESM10 at input/output conditions."isocapnic_quotient"
/"isocapnic_quotient_out"
: isocapnic quotient of HDW18 at input/output conditions."isocapnic_quotient_approx"
/"isocapnic_quotient_approx_out"
: isocapnic quotient approximation of HDW18 at input/output conditions.
Biological properties¶
Seawater properties related to the marine carbonate system that have a primarily biological application.
"substrate_inhibitor_ratio"
/"substrate_inhibitor_ratio_out"
: substrate:inhibitor ratio of B15 at input/output conditions in mol(HCO_{3}^{−})·μmol(H^{+})^{−1}.
Chemical speciation¶
Molality of each individual chemical species involved in pH equilibria.
"HCO3"
/"HCO3_out"
: bicarbonate [\text{HCO}_3^] at input/output conditions in μmol·kg^{−1}."CO3"
/"CO3_out"
: carbonate [\text{CO}_3^{2}] at input/output conditions in μmol·kg^{−1}."CO2"
/"CO2_out"
: aqueous carbon dioxide [\text{CO}_2(\text{aq})] at input/output conditions in μmol·kg^{−1}."BOH4"
/"BOH4_out"
: tetrahydroxyborate [\text{B(OH)}_4^] at input/output conditions in μmol·kg^{−1}."BOH3"
/"BOH3_out"
: boric acid [\text{B(OH)}_3] at input/output conditions in μmol·kg^{−1}."OH"
/"OH_out"
: hydroxide [\text{OH}^] at input/output conditions in μmol·kg^{−1}."Hfree"
/"Hfree_out"
: "free" protons [\text{H}^+] at input/output conditions in μmol·kg^{−1}."H3PO4"
/"H3PO4_out"
: phosphoric acid [\text{H}_3\text{PO}_4] at input/output conditions in μmol·kg^{−1}."H2PO4"
/"H2PO4_out"
: dihydrogen phosphate [\text{H}_2\text{PO}_4^] at input/output conditions in μmol·kg^{−1}."HPO4"
/"HPO4_out"
: monohydrogen phosphate [\text{HPO}_4^{2}] at input/output conditions in μmol·kg^{−1}."PO4"
/"PO4_out"
: phosphate [\text{PO}_4^{3}] at input/output conditions in μmol·kg^{−1}."H4SiO4"
/"H4SiO4_out"
: orthosilicic acid [\text{Si(OH)}_4] at input/output conditions in μmol·kg^{−1}."H3SiO4"
/"H3SiO4_out"
: trihydrogen orthosilicate [\text{SiO(OH)}_3^] at input/output conditions in μmol·kg^{−1}."NH3"
/"NH3_out"
: ammonia [\text{NH}_3] at input/output conditions in μmol·kg^{−1}."NH4"
/"NH4_out"
: ammonium [\text{NH}_4^+] at input/output conditions in μmol·kg^{−1}."HS"
/"HS_out"
: bisulfide [\text{HS}^] at input/output conditions in μmol·kg^{−1}."H2S"
/"H2S_out"
: hydrogen sulfide [\text{H}_2\text{S}] at input/output conditions in μmol·kg^{−1}."HSO4"
/"HSO4_out"
: bisulfate [\text{HSO}_4^] at input/output conditions in μmol·kg^{−1}."SO4"
/"SO4_out"
: sulfate [\text{SO}_4^{2}] at input/output conditions in μmol·kg^{−1}."HF"
/"HF_out"
: hydrofluoric acid [\text{HF}] at input/output conditions in μmol·kg^{−1}."F"
/"F_out"
: fluoride [\text{F}^] at input/output conditions in μmol·kg^{−1}.
Totals estimated from salinity¶
"total_borate"
: total borate in μmol·kg^{−1}."total_fluoride"
: total fluoride μmol·kg^{−1}."total_sulfate"
: total sulfate in μmol·kg^{−1}."total_calcium"
: total calcium in μmol·kg^{−1}.
Equilibrium constants¶
All equilibrium constants are returned on the pH scale of input pHSCALEIN
except for "KFinput"
/"KFoutput"
and "KSO4input"
/"KSO4output"
, which are always on the Free scale.
"k_CO2"
/"k_CO2_out"
: Henry's constant for CO_{2} at input/output conditions."k_carbonic_1"
/"k_carbonic_1_out"
: first carbonic acid dissociation constant at input/output conditions."k_carbonic_2"
/"k_carbonic_2_out"
: second carbonic acid dissociation constant at input/output conditions."k_water"
/"k_water_out"
: water dissociation constant at input/output conditions."k_borate"
/"k_borate_out"
: boric acid dissociation constant at input/output conditions."k_fluoride"
/"k_fluoride_out"
: hydrogen fluoride dissociation constant at input/output conditions."k_bisulfate"
/"k_bisulfate_out"
: bisulfate dissociation constant at input/output conditions."k_phosphoric_1"
/"k_phosphoric_1_out"
: first phosphoric acid dissociation constant at input/output conditions."k_phosphoric_2"
/"k_phosphoric_2_out"
: second phosphoric acid dissociation constant at input/output conditions."k_phosphoric_3"
/"k_phosphoric_3_out"
: third phosphoric acid dissociation constant at input/output conditions."k_silicate"
/"k_silicate_out"
: silicic acid dissociation constant at input/output conditions."k_ammonia"
/"k_ammonia_out"
: ammonia equilibrium constant at input/output conditions."k_sulfide"
/"k_sulfide_out"
: hydrogen sulfide equilibrium constant at input/output conditions."k_alpha"
/"k_alpha_out"
: HA equilibrium constant at input/output conditions."k_beta"
/"k_beta_out"
: HB equilibrium constant at input/output conditions.
The ideal gas constant used in the calculations is also returned. Note the unusual unit:
"gas_constant"
: ideal gas constant in ml·bar^{−1}·mol^{−1}·K^{−1}.
Function arguments¶
All the function arguments not already mentioned here are also returned as results with the same keys.