moonbit-extractor

GitHub：zhaoyuanjuns/moonbit-extractor
GitLink：zyjzyj78/moonbit-extractor

moonbit-extractor 是一个用 MoonBit 编写的萃取分离计算工具箱，面向化工教学、实验数据整理和工艺方案初算。它把液液萃取、固液浸取和三元相图中常见的计算过程整理成可复用库，并提供一个可脚本化的命令行程序。

项目只处理平衡级模型，不替代严格热力学模拟。使用实测相平衡数据时，结果的可靠性取决于数据范围、基准和实验质量。

功能

分配系数、选择性、萃取因子和回收率
恒定分配系数或表格相平衡下的单级液液萃取
任意溶剂分配和等量溶剂分配的错流多级萃取
恒流、恒定分配系数的逆流多级物料衡算
固液浸取的单级洗涤、错流多级洗涤和目标洗液量反算
一维相平衡表的校验、插值、反插值、斜率和积分
三元组成归一化、三角形坐标变换、混合点和杠杆规则
联络线表插值、邻近联络线选择和两相分割
McCabe–Thiele 风格萃取级数计算，支持非线性表格相平衡和末级分数级
非理想级效率分布与实际接触级估算
目标萃余浓度的溶剂量反算，以及单级、错流、逆流方案比较
三元两相区多边形、混合线交点和边界投影
批量情景、灵敏度、统计汇总、衡算审计和区间包络
CSV 相平衡数据与联络线数据读取
可在脚本中使用的 CLI 文本输出

环境

项目按 MoonBit 工具链 moonc v0.10.3 验证，CI 也固定使用该版本，避免包描述格式随工具链升级产生非预期差异。确认本机版本：

moon version --all

拉取源码后执行：

moon update
moon check --deny-warn
moon test --deny-warn

CLI 使用 native 后端，需要系统中有 C 编译器：

moon run --target native cmd/extractor -- --help

快速计算

分配系数

moon run --target native cmd/extractor -- distribution 0.10 0.40

其中 x=0.10、y=0.40，输出 K_D = y/x = 4。

单级液液萃取

moon run --target native cmd/extractor -- single 100 0.10 50 2

参数依次为载体相流量 L、进料浓度 xF、溶剂相流量 V、分配系数 K，可再给出入口溶剂浓度 yS。上述算例得到 x=0.05、y=0.10，溶质回收率为 0.5。

逆流多级萃取

moon run --target native cmd/extractor -- countercurrent 100 0.12 50 2 2

这里使用两个理想级。CLI 会列出各级平衡浓度、出口浓度、回收率和总物料衡算残差。

固液浸取

moon run --target native cmd/extractor -- leach 100 50 0.20 50 0.40

参数依次为不溶性干固体质量 B、初始附液质量 M0、初始溶质分数 x0、洗液质量 W、持液比 R，可再给出洗液溶质分数 xW。

McCabe–Thiele 线性平衡级数

moon run --target native cmd/extractor -- stages-linear 100 50 0.12 0.04 2

命令输出理论级数和逐级踏步点。非线性相平衡请从库 API 构造 EquilibriumTable 后调用 mccabe_thiele_stages。

溶剂量方案比较

moon run --target native cmd/extractor -- solvent-design 100 0.10 2 0.025 3

输出达到同一萃余相目标时，单级、三段等量错流和三级逆流所需的溶剂量。比较基于理想平衡级；放大设计还应计入级效率和安全裕量。

局部灵敏度

moon run --target native cmd/extractor -- sensitivity 100 0.10 50 2

输出回收率对溶剂流量和分配系数的中心差分归一化灵敏度，并对一组分配系数情景执行物料衡算审计。

库 API 示例

依赖项目在 moon.pkg 中导入根包后，可以通过门面 API 完成常用计算：

test {
  let result = @moonbit_extractor.single_stage_constant_k(
    feed_flow=100.0,
    feed_concentration=0.1,
    solvent_flow=50.0,
    distribution=2.0,
  )
  assert_true(result.recovery.is_close(0.5))
}

直接使用子包也可以获得更清楚的领域边界：

domain：组成、平衡点、联络线和错误类型
interpolation：线性表与相平衡表
liquid：液液萃取物料衡算
leaching：固液浸取与洗涤
ternary：三元相图几何和杠杆规则
stages：图解级数计算
data：CSV 数据读取
design：溶剂量反算、流程比较和局部灵敏度
analysis：批量情景、统计汇总、衡算审计和不确定度包络

表格相平衡

test {
  let points = [
    @domain.EquilibriumPoint::new(x=0.0, y=0.0),
    @domain.EquilibriumPoint::new(x=0.1, y=0.2),
    @domain.EquilibriumPoint::new(x=0.2, y=0.3),
  ]
  let equilibrium = @interpolation.EquilibriumTable::new(points)
  let result = @liquid.single_stage_table(
    feed_flow=100.0,
    feed_concentration=0.1,
    solvent_flow=50.0,
    equilibrium~,
  )
  assert_true(result.balance_residual.abs() < 1.0e-8)
}

CSV 格式见 examples/equilibrium-linear.csv 和 examples/tie-lines-synthetic.csv。示例数据是为测试构造的无量纲数据，不代表具体物系。

计算基准和假设

液液萃取 API 默认使用一致的无溶质基准：

L 是载体相或萃余相的无溶质流量；
V 是溶剂相的无溶质流量；
x、y 是每单位对应无溶质相所含的溶质量；
平衡级内两相充分接触并达到给定的 y*(x)；
未计入载体与溶剂的互溶、夹带、体积变化和传质效率。

固液浸取模型假定溶质完全溶解在液相，级内液相浓度均一，溢流不含不溶性固体，底流按固定持液比带出溶液。若物料存在吸附平衡、可溶惰性组分或持液比随浓度变化，应建立更合适的模型。

算法推导、输入约束和适用边界见 docs/ALGORITHMS.md。

数据要求

相平衡表的 x 必须严格递增，默认禁止超出数据范围外推。调用者可以明确选择截断或线性外推，但工艺计算中应优先补充数据而不是依赖外推。

三元组成按“载体、溶质、溶剂”排序，三个分数都应非负且总和为 1。联络线 CSV 的列顺序为：

r_carrier,r_solute,r_solvent,e_carrier,e_solute,e_solvent

开发检查

moon fmt --check
moon check --target all --deny-warn
moon test --deny-warn
moon info

CI 还会构建 native CLI 并运行几个烟雾算例。提交公开仓库前请先阅读 docs/RELEASE_CHECKLIST.md。

项目状态

当前版本为 0.1.0。核心范围已经可运行，后续计划包括：

非理想相平衡模型与参数回归接口
基于实验数据的级效率参数回归与夹带修正
逆流非线性方程组求解
三元相图 SVG/Canvas 输出
带单位和不确定度的数据层

来源和许可证

本项目为原创 MoonBit 实现，不是对现有软件库的移植。公式属于化工原理中的通用物料衡算和几何关系；实现来源、生态检索和示例数据说明见 docs/SOURCES.md。

源码采用 Apache License 2.0。