> 该包用于保留早期数值实现、参考数据和回归验证。当前项目的主入口是根目录的分样/处理历史核对；本页不能代表新的贡献重点。

# 保留的水相平衡支持包

包职责与主任务关系见 [equilibrium/README.md](../equilibrium/README.md)。

用 MoonBit 实现的有限水相平衡库与本地 CLI：从分析总量和 pH/碱度/电荷边界求溶解物种，输出守恒残差、活度迭代轨迹、矿物 SI 与输入敏感性。适用于明确组分的稀水溶液教学和初步筛选。

当前支持 Ca–C 碳酸盐、Ca–S 硫酸盐与 Zn–水解三个完整场景，及纯水校验。核心平衡和敏感性计算都在 MoonBit 内完成，Python 文件适配器只处理输入/输出；独立 Python 参考程序使用不同数值路线核验。**这不是科学空白，也不能保证比赛不判重。** 实质近邻和工程贡献见 [独立贡献说明](independent-contribution.md)。

## 快速运行

需要 MoonBit 工具链和 Python 3.9+；Python 脚本只用标准库。若项目目录已有 `.moon`，适配器会自动使用它；否则使用 PATH 中的 `moon`。

```bash
python3 scripts/aqueous.py solve --fixture carbonate --output /tmp/carbonate-result.json --species-csv /tmp/carbonate-species.csv
python3 scripts/aqueous.py solve --fixture sulfate --output /tmp/sulfate-result.json
python3 scripts/aqueous.py solve --fixture hydrolysis --output /tmp/hydrolysis-result.json
python3 scripts/aqueous.py sensitivity --input examples/carbonate-sensitivity.json --output /tmp/carbonate-sensitivity.json
```

直接使用 MoonBit（本地 `.moon` 使用者先设置如下路径；系统安装者直接执行后续 moon 命令）：

```bash
export MOON_HOME="$PWD/.moon"
export PATH="$MOON_HOME/bin:$PATH"
moon check --deny-warn
moon test --deny-warn
moon run equilibrium/cmd/main demo sulfate
moon run equilibrium/cmd/main fixture-json hydrolysis
```

`demo [carbonate|sulfate|hydrolysis|water]` 求解内置案例，默认 carbonate。底层另有 `solve-json`、`inspect-json`、`sensitivity-json`，每次接收一个 JSON 字符串参数。读取文件建议使用上述适配器，避免手工转义大 JSON。

## 三个完整使用场景

| 场景与决策 | 输入 | 输出与实际含义 |
|---|---|---|
| 钙–碳酸盐水样：筛查方解石结垢候选，评估碱度误差 | Ca 2 mmol/L、无机碳 3 mmol/L、Cl 1 mmol/L、TA 3 meq/L | pH≈8.04864，Calcite SI≈0.77233；输出 CO2、HCO3−、CO3²−、钙配对物种及 TA 扰动结果，供后续结垢试验选择工况。 |
| 硫酸钙溶液：区分总钙与自由钙、筛查石膏饱和 | Ca、S(VI) 各 10 mmol/L，电荷平衡 | 游离 Ca≈7.35390 mmol/L，CaSO4(aq)≈2.64609 mmol/L，Gypsum SI≈−0.24740；不能拿总钙、总硫直接代替活度计算 SI。 |
| 稀锌硝酸盐滴定：观察加碱后的溶解态锌分配 | Zn 10 µmol/L、NO3 20 µmol/L、NaOH 19 µmol/L，电荷平衡 | pH≈8.67714，游离 Zn≈2.32874 µmol/L，Zn(OH)2(aq)≈6.46927 µmol/L；同时报告 Zn(OH)2(e) 固相 SI，过饱和时该水相组成只是候选/亚稳诊断，不能作为除锌率。 |

每个场景的角色、输入含义、操作、结果解释、敏感性、下一步决策和边界在 [完整场景说明](equilibrium-scenarios.md)。以上均为合成、有限组分案例，没有冒充实测水样。

## 文件与 CSV 输入

```bash
python3 scripts/aqueous.py inspect --input examples/sulfate.json --output /tmp/sulfate-inspection.json
python3 scripts/aqueous.py solve --input examples/carbonate.json --totals-csv examples/carbonate-totals.csv --output /tmp/from-csv.json
```

CSV 表头固定为 `element,value,unit`，必须为输入模型中的每个分析元素恰好提供一行。支持 `mol/L`、`mmol/L`、按元素质量计算的 `mg/L`；例如 C 的 mg/L 是 mg C/L，不是 mg HCO3/L。未知单位、缺行、重复行、负数和非有限值均拒绝。摩尔质量表在适配器内明确列出。

## 数值验证

```bash
python3 scripts/verify_local.py  # 一次复跑构建、测试、三场景及独立数值核验
python3 scripts/generate_thermodynamics.py --check
python3 scripts/generate_examples.py --check
python3 scripts/validate_reference.py
python3 scripts/validate_demo.py --problem examples/carbonate.json --result /tmp/carbonate-result.json
```

独立参考从保留的 PHREEQC 原始文件提取常数，用解析消元和标量区间二分求解，逐物种核验浓度、活度和 gamma，并比较 pH、I、电荷、碱度及 SI。它没有复用 MoonBit 的 Newton 实现、反应矩阵或输入常数求参考浓度。守恒复算与独立求解是两层检查。

当前核验包含 35 组工况、930 个物种字段对照、5 组敏感性及减半步长复核、旧 CO2/CaHCO3 常数错误注入、19 项非法输入/截断输出拒绝检查。完整结果在 [数值报告](../audit/2026-10-27/remediation/reference-report.json) 和 [逐物种表](../audit/2026-10-27/remediation/species-comparison.csv)。结果仅证明指定方程和数据口径的一致性，**没有运行 PHREEQC 可执行程序，也没有实验精度认证**。

跨后端验证：

```bash
python3 scripts/validate_reference.py --compare-target native
```

本机默认 MacOSX27.0 SDK 的 TAPI 链接器不能解析 `arm64e.x1-macos`；本次已使用本机现有 MacOSX26.5 SDK 完成 Native 测试与跨后端对照，不需要修改系统 SDK：

```bash
SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk moon test --target native --deny-warn
SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk python3 scripts/validate_reference.py --compare-target native
```

这一 SDK 路径只适用于本机。Linux CI 使用正常的系统 C 编译工具链；CI 配置存在不代表远端 CI 已执行。

## 数据、许可和模型限制

代码为 [Apache-2.0](../LICENSE)。PHREEQC 数据保留其 [User Rights Notice](../data/upstream/PHREEQC-NOTICE.txt)，没有被重新授权为 Apache-2.0。来源、原始文件哈希、标准态、温度、压力和适用范围见 [数据说明](data-sources.md)、[第三方通知](../THIRD_PARTY_NOTICES.md) 和 `data/thermodynamics.json`。

- 只支持 298.15 K、约 1 atm；没有温度或压力修正，其他温度拒绝。
- API 浓度为 mol/L；源常数为 mol/kg water，采用明确的稀溶液 `m≈c` 和水活度为 1 近似，没有密度换算。
- Davies 保守限制 I≤0.1 mol/L；极限 Debye–Hückel 限制 I≤0.01 mol/L，中性物种 gamma=1。
- 所有分析总量必须有限且大于 0；不存在的组分应从数据库移除，零总量不会被伪装成一个微小正解。
- 固定 pH 或 TA 会替代电荷方程，仍保留电荷残差。解释真实水样前必须交代反离子、滴定剂或边界库。
- SI 只是固定溶解组成下的诊断；未求沉淀量、固液相切换或反应动力学，没有气体分压、氧化还原、Pitzer/SIT 或完整天然水数据库。

[模型方程](model.md) · [JSON/API/CSV 契约](schema.md) · [单位约定](conventions.md)

## 申报材料状态

[一页 Markdown 申报书草稿](../PROJECT_APPLICATION.md) 已保留个人信息空栏；它是 AI 辅助草稿，**不能替代章程所要求的参赛者人工撰写和本人审核**。[本人复核清单](applicant-review.md) 未预先勾选。[修正记录](remediation.md) 明确区分已完成工程、待本人事项和赛事判定。

本地代码、案例和核验已提供；没有发布、推送、报名或提交。项目不是“无类似”的选题，采用“任何类似即淘汰”的严格门槛时仍不通过。