Marine Carbonate Chemistry

Turn two independent seawater carbonate measurements into a reproducible speciation table, mineral saturation estimates, and a record of the calculation assumptions. Targets PyCO2SYS 1.8.3.4, tested with Python 3.13 and NumPy 2.5.3. As reviewed on 2026-10-01, this remains the stable PyPI release. The v2 documentation is for a beta with breaking changes; use the v1 documentation for this pin.

When to use

• Analyze bottle samples, shipboard carbonate measurements, or acidification experiments.
• Calculate total-scale pH, seawater pCO2/fCO2, carbonate ion, aragonite/calcite saturation state, or the Revelle factor from a valid measured pair.
• Convert a system determined at laboratory conditions to specified ocean conditions.
• Quantify how stated measurement uncertainties affect the calculated results.

This workflow concerns seawater carbonate equilibria. Freshwater, porewaters with substantial uncharacterized alkalinity, brines outside the selected calibration range, and reaction/transport models require additional chemistry and validation. Do not infer an air-sea flux or atmospheric carbon removal from a carbonate equilibrium alone.

Establish the measurement contract

Before running a solver, identify the two measured variables, their units, quality flags, and their temperature/pressure basis. Retain a separate source table containing station, depth, timestamps, methods, reference materials, and original QC codes, joined by sample ID. Do not turn missing values or rejected measurements into zero.

TA and DIC remain constant during the solver's temperature/pressure conversion for a closed sample. pH and gas parameters change. Two inputs measured at different conditions cannot simply share one temperature value. Establish a consistent measurement basis first. Temperature correction does not repair sample changes caused by gas exchange, biology, evaporation, or mineral dissolution/precipitation.

Use two independent carbonate parameters. pCO2 plus fCO2 is not an independent pair. Three or more measurements enable an overdetermination check: solve independent pairs and compare predicted versus measured third parameters, including their uncertainty. Do not average inconsistent solutions to hide a calibration or scale mismatch.

Install

Create a dedicated environment in the user's working directory:

uv venv --python 3.13 .venv
uv pip install --python .venv/bin/python "PyCO2SYS==1.8.3.4" "numpy==2.5.3"

On Windows the environment's interpreter is .venv/Scripts/python.exe. The commands below use the POSIX interpreter path. Set the shell variable SKILL_DIR to this installed skill's directory. Keep inputs and generated outputs in the working directory.

Workflow

1. Prepare paired measurements. Use the schema in references/input-and-results.md. Resolve units and quality flags before creating the input file. Supply phosphate and silicate explicitly; zero is an assumption to justify, not a missing-data code.
2. Choose equilibrium constants. Read references/chemistry-decisions.md for pH scales, carbonic-acid constants, borate, saturation interpretation, and uncertainty limits. Match the study's validated convention and report it. The helper supports carbonic-acid options 10 and 15; other systems require a separately verified direct PyCO2SYS call.
3. Solve with scripts/solve_carbonate.py. It validates the full input table, solves the pair, checks finite outputs and DIC species balance, then writes carbonate.csv and provenance.json into a new output directory.
4. Review flags and consistency. Inspect calibration-range and gas-pressure flags, carbonate balance, measured-third-parameter residuals when available, and controls.

…