marine-carbonate-chemistry

海洋碳酸盐化学

将两个独立的海水碳酸盐测量值转化为可复现的形态分布表、矿物饱和度估算，以及计算假设记录。 目标版本为 PyCO2SYS 1.8.3.4，已在 Python 3.13 和 NumPy 2.5.3 下测试。截至 2026-10-01 审查，这仍是 PyPI 上的稳定版本。v2 文档 对应的是带有破坏性变更的 beta 版本；对于此固定版本，请使用 v1 文档。

适用场景

• 分析采水瓶样品、船载碳酸盐测量或酸化实验。
• 根据一对有效的测量值计算总标度 pH、海水 pCO2/fCO2、碳酸根离子、文石/方解石 饱和状态，或 Revelle 因子。
• 将在实验室条件下确定的体系转换到指定的海洋条件。
• 量化所述测量不确定度对计算结果的影响。

本工作流涉及海水碳酸盐平衡。淡水、含有大量未表征碱度的孔隙水、超出所选校准范围的 卤水，以及反应/输运模型需要额外的化学处理和验证。不要仅根据碳酸盐平衡推断海气通量 或大气碳去除。

确立测量契约

在运行求解器之前，确定两个测量变量、其单位、质量标志，以及它们的温度/压力基准。 保留单独的源数据表，其中包含站位、深度、时间戳、方法、标准物质和原始 QC 代码，并通过样品 ID 关联。 不要将缺失值或被拒绝的测量值变为零。

量	所需约定
总碱度（TA）、DIC、营养盐	微摩尔每 kg 海水，而非每升或每 kg 水
盐度	实用盐度，而非以 g/kg 表示的超绝对盐度
温度	原位/测量温度，单位为摄氏度，而非位温或保守温度
压力	海水压力，单位为 dbar；表层样品为 0，而非 1 个大气压
pH	在所述测量条件下声明的总标度、海水标度、自由标度或 NBS 标度
pCO2 / fCO2	海水分压 / 逸度，单位为微大气压；二者是不同的量

对于封闭样品，TA 和 DIC 在求解器的温度/压力转换过程中保持不变。pH 和气体参数会变化。 在不同条件下测量的两个输入不能简单地共用一个 temperature 值。首先确立一致的测量基准。 温度校正无法修复由气体交换、生物活动、蒸发或矿物溶解/沉淀引起的样品变化。

使用两个独立的碳酸盐参数。pCO2 加 fCO2 不是独立的一对。三个或更多测量值可进行 超定检查：求解独立的参数对，并将预测的第三参数与实测值进行比较，包括其不确定度。 不要对不一致的解取平均来掩盖校准或标度不匹配。

安装

在用户的工作目录中创建专用环境：

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

在 Windows 上，环境的解释器为 .venv/Scripts/python.exe。以下命令使用 POSIX 解释器路径。将 shell 变量 SKILL_DIR 设置为此已安装 skill 的目录。将输入和 生成的输出保留在工作目录中。

工作流

1. 准备成对测量数据。 使用 references/input-and-results.md 中的 schema。在创建输入文件之前，先解决单位和质量标记问题。显式提供磷酸盐和硅酸盐； 零是需要论证的假设，而不是缺失数据代码。
2. 选择平衡常数。 阅读 references/chemistry-decisions.md，了解 pH 标度、 碳酸常数、硼酸盐、饱和解释和不确定度限制。 与研究已验证的约定保持一致并报告该约定。该辅助工具支持碳酸 选项 10 和 15；其他体系需要另行验证的直接 PyCO2SYS 调用。
3. 使用 scripts/solve_carbonate.py 求解。 它会验证完整输入表，求解 参数对，检查输出是否有限以及 DIC 物种平衡，然后将 carbonate.csv 和 provenance.json 写入新的输出目录。
4. 检查标记和一致性。 检查校准范围和气体压力标记、 碳酸盐平衡、可用时的实测第三参数残差以及对照。 成功求解并不验证样品、常数或测量方法。
5. 在预期条件下报告。 以 _out 结尾的结果描述所提供的 输出温度/压力。无后缀结果描述输入条件。气体结果 保留该辅助工具未校正的静水气体约定（见下文）。在结果表中 包含参数对、pH 标度、单位、常数、营养盐假设、不确定度范围、 软件版本以及被排除/标记的样品。

示例：封闭样品条件校正

以下数值是合成的，并非现场观测数据。将其保存为工作目录中的 samples.csv。 两个样品仅在 DIC 上不同；第二个表示 固定碱度下添加 CO2 的对比。它们的测量条件为 25 C 和 0 dbar； 还请求给出 10 C 和 1000 dbar 下的结果。

sample_id,par1,par2,salinity,temperature,pressure,total_phosphate,total_silicate,temperature_out,pressure_out,u_par1,u_par2
baseline,2300,2000,35,25,0,0,0,10,1000,2,2
added_co2,2300,2100,35,25,0,0,0,10,1000,2,2

从该工作目录运行：

.venv/bin/python "$SKILL_DIR/scripts/solve_carbonate.py" samples.csv \
  --par1-type alkalinity --par2-type dic --k-carbonic 10 \
  --output-dir carbonate-results

对于基线，已测试版本给出的输入条件总 pH 为 8.045886， pCO2 为 396.958 microatm，文石饱和度为 3.386201。在指定的输出 条件下，总 pH 为 8.241241，文石饱和度为 2.605691。这些四舍五入 数值是此精确设置的回归检查，并非通用的海水基准值。 仅考虑 TA 和 DIC 的独立 2 micromol/kg 不确定度时，u_pH_total 约为 0.004580。这不包括平衡常数和其他输入不确定度。 两行都带有 gas_pressure_correction_disabled_output：输出 pH 和矿物 饱和度包含压力效应，但报告的 pCO2/fCO2 不包含对 CO2 溶解度和逸度 的静水校正。不要将这些气体值与经过压力校正的次表层传感器测量值 直接比较。

对于 TA + 实测 pH，仅当来源明确标识总标度 pH 时，才使用 --par2-type ph --ph-scale total； 将 par2 和 u_par2 替换为实测 pH 及其绝对 标准不确定度。仅名为 pH 的列不足以确定其标度。

不确定度与解释

可选的 u_ 输入列包含绝对一标准差不确定度。 它们会传播到每个请求条件下的总 pH、pCO2 和文石饱和度。 该辅助工具假设误差独立，并将未列出的输入/常数视为精确值。 对于协方差、常数不确定度或强非线性不确定度，请遵循 决策指南并验证定制的传播，而不是将这些输出称为 完整的不确定度预算。

Omega < 1 表示相对于指定矿物处于热力学 undersaturation。 它不建立溶解速率或生物体响应。在 不匹配样品之间出现较低 pH 本身并不是人为酸化趋势的证据。

来源与验证边界

• PyCO2SYS v1 参数、单位、设置与结果键
• 不确定度传播
• 上游验证
• 稳定版本
• Humphreys et al. (2022), PyCO2SYS v1.8

仓库测试会检验固定版本的求解器、独立配对往返、碳平衡、 pH 标度等价性、条件校正、Revelle 因子导数、气压 约定、不确定度求积、CSV 错误以及示例。该辅助工具调用 本地 pyco2.sys Python API；它没有 HTTP 端点或身份验证。测试建立的是 软件行为，而非独立的实地数据验证；上游的验证页面也 包含历史示例，其中包括已移除的 pyco2.test 接口。