Arguments and results¶
This page provides a comprehensive overview of the keyword arguments that can be provided to pyco2.sys and the results it can compute.
Content, not concentration
For all arguments and results in μmol kg–1, the "kg" refers to the total solution, not H2O. These are therefore accurately termed substance content or molinity values (as opposed to concentration or molality).
Keyword shortcuts
Formally, all keyword arguments and results keys for pyco2.sys are lowercase except for chemical formulae, which are always written in their correct case.
But you don't need to remember this - all keyword arguments and results keys are case-insensitive!
Some keys also have alternative "shortcuts" - click on the (1) symbol next to the parameter names. These shortcuts can be used both when creating a CO2System with pyco2.sys and when accessing results from it. Shortcut keys are stored in a dict at pyco2.engine.shortcuts.
- Shortcuts!
Keyword arguments¶
Each argument to pyco2.sys can be either 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.
Pandas DataFrames and xarray Datasets can be provided using the data kwarg (see User guide / Quick-start guide / Data structures).
Carbonate system parameters¶
Up to two carbonate system parameters can be provided.
Carbonate system parameters
If two parameters are provided, these can be any pair of:
alkalinity(1): total alkalinity in μmol kg–1.dic(2): dissolved inorganic carbon in μmol kg–1.pH: pH on the total, seawater, free or NBS scale. Which scale is given byopt_pH_scale.HCO3: bicarbonate ion in μmol kg–1.- Any one of:
pCO2: partial pressure of CO2 in μatm,fCO2: fugacity of CO2 in μatm,CO2: aqueous CO2 in μmol kg–1, orxCO2: dry-air mole fraction of CO2 in ppm.
- Any one of:
CO3: carbonate ion in μmol kg–1,saturation_calcite(3): saturation state with respect to calcite, orsaturation_aragonite(4): saturation state with respect to aragonite.
- Shortcuts:
talk,alk,ta - Shortcut:
tco2 - Shortcut:
oc - Shortcut:
oa
If one parameter is provided, then the full marine carbonate system cannot be solved, but some results can be calculated. The single parameter can be any of:
pCO2,fCO2,CO2orxCO2: the others in this group of parameters can be calculated and adjusted to different temperatures.pH, which can be converted to different scales.
If no carbonate system parameters are provided, then all equilibrium constants and total salt contents can still be calculated.
Hydrographic conditions¶
If not provided, these revert to default values.
Hydrographic conditions
salinity(1): practical salinity (default 35).temperature(2): temperature in °C (default 25 °C) at which the carbonate system parameters are provided.pressure(3): hydrostatic pressure in dbar (default 0 dbar) at which the carbonate system parameters are provided.pressure_atmosphere: atmospheric pressure in atm (default 1 atm).
As in previous versions of (Py)CO2SYS, there is no built-in way to handle the (rare) case where both known parameters are temperature- and/or pressure-sensitive and the two known parameters are at a different temperature and/or pressure from each other.
- Shortcuts:
sal,s - Shortcuts:
temp,t - Shortcuts:
pres,p
Nutrients and other solutes¶
Nutrients default to zero if not provided, while other solutes are calculated from salinity.
Nutrients and other solutes
Some default to zero if not provided:
total_silicate(1): total silicate in μmol kg–1 (default 0 μmol kg–1) (\([\mathrm{Si(OH)}_4] + [\mathrm{SiO(OH)}_3^-]\)).total_phosphate(2): total phosphate in μmol kg–1 (default 0 μmol kg–1) (\([\mathrm{H}_3\mathrm{PO}_4] + [\mathrm{H}_2\mathrm{PO}_4^-] + [\mathrm{HPO}_4^{2-}] + [\mathrm{PO}_4^{3-}]\)).total_ammonia(3): total ammonia in μmol kg–1 (default 0 μmol kg–1) (\([\mathrm{NH}_3] + [\mathrm{NH}_4^+]\)).total_sulfide(4): total hydrogen sulfide in μmol kg–1 (default 0 μmol kg–1) (\([\mathrm{H}_2\mathrm{S}] + [\mathrm{HS}^-]\)).total_nitrite(5): total nitrite in μmol kg–1 (default 0 μmol kg–1) (\([\mathrm{HNO}_2] + [\mathrm{NO}_2^-]\)).
Others are calculated from salinity if not provided:
total_borate(6): total borate in μmol kg–1 (\([\mathrm{B(OH)}_3] + [\mathrm{B(OH)}_4^-]\)).total_fluoride(7): total fluoride in μmol kg–1 (\([\mathrm{HF}] + [\mathrm{F}^-]\)).total_sulfate(8): total sulfate in μmol kg–1 (\([\mathrm{HSO}_4^-] + [\mathrm{SO}_4^{2-}]\)).Ca: dissolved calcium in μmol kg–1 (\([\mathrm{Ca}^{2+}]\)).
If these are provided then their parameterisation settings are ignored.
- Shortcuts:
silicate,tsi - Shortcuts:
phosphate,tp - Shortcuts:
ammonia,tnh3 - Shortcuts:
sulfide,th2s - Shortcuts:
nitrite,tno2 - Shortcuts:
borate,tb - Shortcuts:
fluoride,tf - Shortcuts:
sulfate,tso4
Settings¶
pH scale¶
If pH is provided as an known marine carbonate system parameter, the pH scale that it is reported on can be specified with opt_pH_scale. All equilibrium constants will also be calculated on the same scale.
pH scale
-
opt_pH_scale: which pH scale was used forpH, as defined by ZW01:1: total (default), i.e. \(\mathrm{pH} = -\log_{10} ([\mathrm{H}^+] + [\mathrm{HSO}_4^-])\).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_fH: how the hydrogen ion activity coefficient is calculated, for conversions to/from the NBS scale:
Carbonic acid dissociation¶
Carbonic acid dissociation
-
opt_k_carbonic: which set of equilibrium constant parameterisations to use for carbonic acid dissociation. The valid temperature (T) and salinity (S) ranges, original pH scale, and type of material measured to derive each set of constants are shown.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 (default) (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).17: SB21 (15 < T < 35 °C, 19.6 < S < 41, total scale, real seawater).18: PLR18 (–6 < T < 25 °C, 33 < S < 100, total scale, real seawater).
-
opt_factor_k_H2CO3: first carbonic acid dissociation constant pressure correction: -
opt_factor_k_HCO3: second carbonic acid dissociation constant pressure correction:
Other dissociation constants¶
Other dissociation constants
-
opt_k_HSO4: which parameterisation to use to model bisulfate dissociation: -
opt_k_HF: which parameterisation to use for hydrogen fluoride dissociation: -
opt_k_BOH3: which parameterisation to use for boric acid dissociation: -
opt_k_phosphate: which parameterisation to use for phosphoric acid dissociation: -
opt_k_NH3: which parameterisation to use for ammonium dissociation: -
opt_k_Si: which parameterisation to use for silicate dissociation: -
opt_k_calcite: which parameterisation to use for the saturation state with respect to : -
opt_k_aragonite: which parameterisation to use for the saturation state with respect to : -
opt_k_H2O: which parameterisation to use for water dissociation: -
opt_k_HNO2: which parameterisation to use for nitrous acid dissociation:
Other dissociation constant pressure corrections¶
Other dissociation constant pressure corrections
Total salt contents¶
These settings are ignored if their values are provided as arguments.
Total salt contents
-
opt_total_borate: which boron:salinity relationship is used to calculate total borate (ignored if thetotal_borateargument is provided): -
opt_Ca: which calcium:salinity relationship is used to calculate dissolved calcium (ignored if theCaargument is provided):
Other settings¶
Other settings
-
opt_gas_constant: what value to use for the universal gas constant (gas_constant):1: DOEv2 (consistent with other CO2SYS software before July 2020).2: DOEv3.3: 2018 CODATA (default).
-
opt_fugacity_factor: how to convert between partial pressure and fugacity of CO2 (pCO2andfCO2):1: using a fugacity factor (default).2: assuming that partial pressure and fugacity are equal, for compatibility with GEOSECS.
-
opt_HCO3_root: if DIC and bicarbonate ion are the known carbonate system parameter pair, then there are two possible valid solutions (e.g., HLSP22):1: find the low-pH solution.2: find the high-pH solution (default).
Equilibrium constants¶
pK, not K
All equilibrium constants are provided and returned as pK values, where pK = –log10 K.
All of the equilibrium constants needed by PyCO2SYS are calculated internally from temperature, salinity and pressure, and returned in the results. However, values for any of these constants can be provided instead when calling pyco2.sys. They should be provided on the pH scale indicated by opt_pH_scale.
To do this, the arguments should have the same keywords as the corresponding results dict keys. For example, to provide a custom water dissociation constant value of pK* 14, use pk_H2O=14.
Results¶
See Advanced tips and tricks for a more detailed overview of the different ways that the results keys in the sections below can be solved for and accessed from a CO2System.
Find all possible results keys
co2s.keys() returns an iterable of all results that have currently been solved for, and co2s.keys_all() returns all keys that could possibly be solved for, in a given CO2System.
pyco2.sys arguments¶
All keyword arguments that can be provided to pyco2.sys and are not settings (i.e., do not begin with opt_) are also available as results with the same keyword.
Settings arguments can be found at co2s.opts. They should not be modified there - doing so will have unpredictable consequences for future calculations.
pH scales¶
pH scales
pH_total: pH on the total scale.pH_sws: pH on the seawater scale.pH_free: pH on the free scale.pH_nbs: pH on the NBS scale.fH: activity coefficient of H+ for conversions to and from the NBS scale.
Chemical speciation¶
Chemical speciation
H_free: "free" proton in μmol kg–1.OH: hydroxide ion in μmol kg–1.CO3: carbonate ion in μmol kg–1.HCO3: bicarbonate ion in μmol kg–1.CO2: aqueous CO2 in μmol kg–1.BOH4: tetrahydroxyborate \([\mathrm{B(OH)}_4^-]\) in μmol kg–1.BOH3: boric acid \([\mathrm{B(OH)}_3]\) in μmol kg–1.H3PO4: phosphoric acid \([\mathrm{H}_3\mathrm{PO}_4]\) in μmol kg–1.H2PO4: dihydrogen phosphate \([\mathrm{H}_2\mathrm{PO}_4^-]\) in μmol kg–1.HPO4: monohydrogen phosphate \([\mathrm{HPO}_4^{2-}]\) in μmol kg–1.PO4: phosphate \([\mathrm{PO}_4^{3-}]\) in μmol kg–1.H4SiO4: orthosilicic acid \([\mathrm{Si(OH)}_4]\) in μmol kg–1.H3SiO4: trihydrogen orthosilicate \([\mathrm{SiO(OH)}_3^-]\) in μmol kg–1.NH3: ammonia \([\mathrm{NH}_3]\) in μmol kg–1.NH4: ammonium \([\mathrm{NH}_4^+]\) in μmol kg–1.HS: bisulfide \([\mathrm{HS}^-]\) in μmol kg–1.H2S: hydrogen sulfide \([\mathrm{H}_2\mathrm{S}]\) in μmol kg–1.HSO4: bisulfate \([\mathrm{HSO}_4^-]\) in μmol kg–1.SO4: sulfate \([\mathrm{SO}_4^{2-}]\) in μmol kg–1.HF: hydrofluoric acid \([\mathrm{HF}]\) in μmol kg–1.F: fluoride \([\mathrm{F}^-]\) in μmol kg–1.HNO2: nitrous acid \([\mathrm{HNO}_2]\) in μmol kg–1.NO2: nitrite \([\mathrm{NO}_2^-]\) in μmol kg–1.
Chemical buffer factors¶
Buffer factors are evaluated using automatic differentiation of the complete alkalinity equation.
Buffer factors
revelle_factor(1): Revelle factor.psi: ψ of FCG94.gamma_dic: buffer factor γDIC of ESM10.beta_dic: buffer factor βDIC of ESM10.omega_dic: buffer factor ωDIC of ESM10.gamma_alkalinity: buffer factor γTA of ESM10.beta_alkalinity: buffer factor βTA of ESM10.omega_alkalinity: buffer factor ωTA of ESM10.Q_isocap(2): isocapnic quotient of HDW18.Q_isocap_approx: isocapnic quotient approximation of HDW18.dlnfCO2_dT: temperature derivative of ln(fCO2).dlnpCO2_dT: temperature derivative of ln(fCO2).substrate_inhibitor_ratio(3): substrate:inhibitor ratio of B15 in mol(HCO3−)·μmol(H+)−1.
- Shortcut:
revelle - Shortcut:
q - Shortcut:
sir
Equilibrium constants¶
All equilibrium constants are returned on the pH scale of opt_pH_scale except for pk_HF_free and pk_HSO4_free, which are always on the free scale. They are all stoichiometric constants, i.e., defined in terms of reactant contents rather than activities, with the exception of pk_CO2, which is a hybrid constant.
Equilibrium constants
pk_CO2(1): Henry's constant for CO2.pk_H2CO3(2): first carbonic acid dissociation constant.pk_HCO3(3): second carbonic acid dissociation constant.pk_H2O(4): water dissociation constant.pk_BOH3: boric acid dissociation constant.pk_HF_free: hydrogen fluoride dissociation constant.pk_HSO4_free: bisulfate dissociation constant.pk_H3PO4: first phosphoric acid dissociation constant.pk_H2PO4: second phosphoric acid dissociation constant.pk_HPO4: third phosphoric acid dissociation constant.pk_Si: silicic acid dissociation constant.pk_NH3: ammonia equilibrium constant.pk_H2S: hydrogen sulfide dissociation constant.pk_HNO2: nitrous acid dissociation constant.pk_calcite: solubility product for calcite.pk_aragonite: solubility product for aragonite.
- Shortcut:
pk0 - Shortcut:
pk1 - Shortcut:
pk2 - Shortcut:
pkw
Other results¶
Other results
fugacity_factor: fugacity factor for converting between CO2 partial pressure and fugacity.vp_factor: vapour pressure factor for converting between xCO2 and pCO2.gas_constant: ideal gas constant in ml bar−1 mol−1 K−1 (note the unusual unit).