[ali-ramadhan]

Closes #455.

The three pH scales

In seawater, some hydrogen ions are free and some are bound in bisulfate (HSO₄⁻) and hydrogen fluoride (HF). The three pH scales differ in which of them they count:

scale	counts the H⁺ that is	output
free	free	Val(:pHᶠ)
total	free or in HSO₄⁻	Val(:pHᵗ)
seawater	free, in HSO₄⁻, or in HF	Val(:pHˢ)

Counting more ions gives a larger [H⁺] and so a lower pH. The free pH is 0.04–0.13 above the total pH (more in warm, salty water), and the seawater pH is about 0.01 below it.

What was wrong

CarbonChemistry solves for the total [H⁺]. Its equilibrium constants (e.g. K₁ and K₂ from Lueker et al. (2000), K_B from Dickson (1990)) are total-scale constants, following Dickson et al. (2007). The pH outputs, however, treated that [H⁺] as the free one:

• Val(:pHᶠ) returned -log10(H), which is the total pH.
• Val(:pHᵗ) added [HSO₄⁻] to an [H⁺] that already includes it. HSO₄⁻ was counted twice, so the pH was 0.04–0.13 too low.
• Val(:pHˢ) counted HSO₄⁻ twice too.
• A pH = input was documented as the free pH, but it has always been used as the total pH.

The fix

Treat the solved [H⁺] as the total [H⁺] in all three outputs:

pHᵗ = -log10(H)                       # H is already the total [H⁺]
pHᶠ = -log10(H / (1 + sulfate / KS))  # take out the H⁺ in HSO₄⁻
pHˢ = -log10(H + HF)                  # add the H⁺ in HF

These use the same free [H⁺] and [HF] as the alkalinity balance in alkalinity_residual.jl. The docstrings and docs now say that a pH = input is the total pH, and the docs explain the three scales.

What this changes for users

1. Val(:pHᵗ) now returns exactly what Val(:pHᶠ) used to return.
2. Val(:pHᶠ) now returns the actual free pH, which is 0.04–0.13 higher.
3. Observational products like GLODAP and CODAP-NA report the total pH, so Val(:pHᵗ) is usually the one to compare against.

Val(:pHᶠ) now returns a different number, so this is a breaking change.

fCO₂, pCO₂, Val(:CO₂) (and so the air–sea CO₂ flux) and calcium_carbonate_saturation use [H⁺] directly, so they don't change.

[jagoosw]

Thank you!

[ali-ramadhan]

Thanks for the quick review @jagoosw! I'll wait a bit until a few more PRs are merged before tagging v0.21.0 if that's okay. Hoping to merge in the customer replicate tracer names (+ associated bug fixes).