pycalphad

pycalphad：TDB 平衡计算

何时使用

用于在固定总元素摩尔组成、指定压力和一组有限温度下计算平衡相分数与相组成。随附的辅助脚本会执行真实的 pycalphad 平衡计算、检查质量平衡、以更高采样密度重复计算，并分别导出每个稳定组成集合。

平衡受所选数据库、组元、相和条件约束。它不预测析出速率、残留的亚稳显微组织，也不预测数据库中缺失的相的性质。数值检查成功并不代表数据库具有实验精度。

工作流

1. 确认 TDB 的来源、许可证、评估/出版物、有效温度/压力与组成范围，以及必需元素。对真实合金请使用用户自己的数据库。随附的 assets/ideal-cu-ni.tdb 是原创的假设性教学模型，并非经过评估的 Cu-Ni 数据库。
2. 检查数据库中的元素和相。有意选择相关的相；记录被排除的相，因为它们可能使计算变成亚稳约束结果。在亚点阵模型要求之处包含 VA。空位不是独立的总摩尔分数。保留 TDB 中耦合的有序/无序定义，但当有序模型已包含无序贡献时，不要将两者同时选为独立候选相；辅助脚本会拒绝此类经过滤的候选列表。
3. 复制 assets/equilibrium.json。准确指定 N-1 个元素摩尔分数和一个作为因变量的非空位元素。因变量分数为 1 - sum(independent fractions)；分数不会被静默归一化。设置 K 和 Pa。使用此辅助脚本前，请先转换重量百分比或质量分数。
4. 若已知，请根据数据库的评估声明其温度区间；若未知，则将 database_temperature_range_k 设为 null。这是用户提供的证据，而非从每个 TDB 函数自动推断出的范围。超出所声明区间的请求会失败。请另行检查压力和组成的有效性。
5. 运行计算。检查吉布斯能量是否有限、相分数之和是否为 1、重构的总组成，以及将 pdens（相组成采样密度）加倍后的稳定性。在相变附近，进一步细化温度和采样密度。
6. 交付相分数时需附上其摩尔基准、相组成、数据库哈希、条件、被排除的相，以及任何数值或评估方面的局限。

有关解析示例、基准转换、原生 Model/Workspace/property/plot 契约、混溶间隙处理和收敛限制，请阅读 references/model-and-validation.md。

执行已测试的示例

从集合根目录：

uv run --no-project --python 3.12 --with pycalphad==0.11.2 --with numpy==2.5.3 \
  python skills/pycalphad/scripts/equilibrate.py \
  skills/pycalphad/assets/ideal-cu-ni.tdb \
  skills/pycalphad/assets/equilibrium.json equilibrium-result

已在 Python 3.12、pycalphad 0.11.2 和 NumPy 2.5.3 上测试。请使用新的输出目录。 所有热力学计算均在本地进行；该脚本不会上传 TDB。

对于所提供的假设性模型，在 X(Ni)=0.5 和 101325 Pa 下：

温度	平衡结果
900 K	仅 FCC_A1
1100 K	0.5 FCC_A1 + 0.5 LIQUID；X(Ni) 分别约为 0.527307 和 0.472693
1300 K	仅 LIQUID

该测试套件验证了共切线解析组成、非中心杠杆定律情形、吉布斯能量、质量平衡、两个单相极限，以及实际同相混溶间隙顶点。这些验证的是计算工作流，而非真实 Cu-Ni 冶金学。

输出与验收

• report.json：设置与版本、TDB/settings 的 SHA-256、被排除的数据库相、 请求的、求解器施加的以及重建的总体成分、各温度的 基线/精修结果，以及各项检查。实验有效性不由该辅助工具评估。
• phase-equilibria.csv：每个温度、每个采样运行中每个稳定顶点一行， 包含相名称、摩尔相分数和元素摩尔分数。其 Gibbs 能列是全系统摩尔 Gibbs 能，对每个顶点重复； 它不是单个相的能量。

未使用的 pycalphad 顶点名称为空、值为 NaN；这些顶点会被省略。已命名 顶点若含有无效值则会导致失败。具有相同相名称的多个顶点 会被保留，因为混溶间隙可能包含同一相的两个成分集。 顶点索引不会跨温度连续追踪同一物理相。

在稳定的 0.11.2 中，pycalphad 将独立摩尔分数裁剪到 [1e-10, 1-1e-10]。 每个结果记录 solver_bulk_mole_fractions 以及与请求总体成分的 最大绝对差，即 composition_condition_adjustment_absolute_error。 质量平衡检查仍与请求的成分比较；因此更严格的 容差可能在端点处失败。不要根据裁剪后的多组分计算 声称得到精确的纯组分或超痕量结果。

all_checks_passed 要求每次运行的相总和与总体成分残差在 mass_balance_tolerance 以内、相总量在 phase_fraction_tolerance 以内稳定， 且当 pdens 加倍时系统 Gibbs 能在 gibbs_energy_tolerance_j_per_mol 以内稳定。 此比较并不证明全局最小值，也不追踪同一相混溶间隙内 单个成分集的移动；也应检查它们导出的成分。 未通过的检查仍会显示在报告中，而不会被重新标记为收敛。

边界与上游契约

该辅助工具处理元素摩尔分数、单一成分、单一压力和最多 1000 个显式正温度。它通过 pycalphad 的相兼容规则验证所选相； 不兼容或被自动过滤的有序/无序相集会生成显式错误。它不会 静默移除请求的相。

带电物种约束、外部施加的化学势、自定义模型、 活度参考态变更以及数据库优化需要额外的建模， 超出该辅助工具经过测试的范围。不要将这一教学性资产外推到 真实材料选择或热处理决策。

• Equilibrium dataset semantics
• Phase fractions and composition basis
• Equilibrium and sampling API
• Ordering examples
• Stable 0.11.2 source

上游 latest 文档目前描述的是 0.11.3 开发构建。随附的 辅助工具和参考文档的原生示例已于 2026-10-01 针对稳定版 0.11.2 进行验证；该发行版的源码已与安装的 wheel 进行核对。 未使用远程热力学计算或数据库获取 API。Database 加载 本地路径、类文件对象或 TDB 文本；不支持将 URL 作为下载快捷方式。