⚗️ smallmatprep

小样本材料配方优化 · 信息论驱动的实验推荐引擎

📖 [中文] · [English]

---

🎯 这是什么

用最少的实验，找到最好的配方。

当你的历史实验数据只有几十条、组分列还满是"没放某原料"的结构零时，smallmatprep 会告诉你下一批最值得做的实验是哪些，并量化告诉你这批数据还能榨出多少信息。

L1  CRISP 约束插补   —— 区分"没放"与"缺失"，填出合法配方矩阵
L2  UWE 集成建模     —— 5 模型加权预测 μ + 不确定性 σ（含 aleatoric/epistemic 分解）
L3  自适应采集       —— μ + z·σ 打分，按数据形态自动选择策略

✨ 核心亮点

• 小样本友好：20–50 条标注数据即可启动闭环，结构零显式处理，无需稠密特征矩阵。
• 自适应路由：没有单一策略通吃所有数据形态（实测 4 个材料体系 + 合成池）——

  数据形态	自动选择
  小池 (<60)	gp_oob / gp_ucb
  大池，d ≤ 6（低维/离群）	quantile_ucb（μ+z·σ，无多样性）
  大池，d > 6（中高维）	gp_ucb

• 信息利用率上界：R²_ceiling ≈ 1 − σ²噪声/var(y)——n=47 时利用 36%、n=504 时到 85%，量化"算法到顶、瓶颈在数据"。
• 与主流 BO 头对头：极端离群池上 quantile_ucb 平均找到 89% 最优（58% 运行达 95%），标准 GP-UCB 仅 33%。

🚀 快速开始

pip install -r requirements.txt     # numpy / pandas / scikit-learn / scipy

import pandas as pd
from smallmatprep.active.loop import experiment_loop

df = pd.read_csv("your_data.csv")    # 行=配方，列=组分 + 目标
rec = experiment_loop(df, target="P2", comp_cols=["A", "B", ...],
                      n_recommend=10, report_path="recommendation.md")
print(rec[["rank", "score", "pred_mean", "pred_std", "formulation"]])

组分缺省（结构零）自动按 0 处理；无目标值的行自动剔除。 回测对比（工具 vs 随机）：python run_my_data.py

📊 复现基准

数据集	来源	状态
ge_refractory_alloy.csv / steel_strength.csv / glass_40samples.csv	公开数据集	✅ 随仓库提供
conductivity_5035.csv	Zenodo 7244939（CC BY 4.0，~37MB）	⬇️ 自行下载放入 data/
电解液配方数据集	企业合作私有数据	🔒 不发布

python benchmark_optimization.py   # 504 池头对头 vs GP-UCB/EI/random
python benchmark_multidataset.py   # 4 个材料体系交叉验证
python benchmark_extensions.py     # quantile/epistemic 消融
python report_suspicious_samples.py# 可疑样本诊断（免费数据质量工具）

📈 关键结果

场景	工具（auto）	主流 GP-UCB	random
电解液 504 池（极端离群）	89.1% / succ95 58%	84.6% / 33%	87.9% / 0%
GE 耐火合金（d=9）	96.1% / 100%（路由→GP）	96.1% / 100%	90.1% / 8%
钢（d=13）	98.9% / 92%（路由→GP）	98.9% / 92%	96.4% / 100%

数字 = 最终找到的最优占池最优 %；succ95 = 达到 95% 最优的运行比例。 完整结果见 BENCHMARK_RESULTS.md / BENCHMARK_EXTENSIONS.md / MULTIDATASET_BENCHMARK.md。

🗂️ 目录结构

├── smallmatprep/            # 核心包
│   ├── modeling/uwe.py      # UWE：μ / σ / σ_epi（aleatoric/epistemic 分解）
│   └── active/
│       ├── acquirers.py     # 8 种采集策略
│       ├── selector.py      # 维度感知自适应路由
│       ├── loop.py          # 闭环 + 推荐 + 候选生成
│       └── report.py        # Markdown 报告
├── data/                    # 公开数据集 + data/README.md
├── results/                 # 全部基准结果 CSV
├── run_my_data.py           # 你自己的数据模板
└── *.md                     # 设计/验证文档

📚 文档

• ARCHITECTURE.md — 三层架构与路由规则
• FEASIBILITY.md — 理论根基（CRISP=Dirichlet 后验均值、UWE、UCB）
• BENCHMARK_RESULTS.md / BENCHMARK_EXTENSIONS.md / MULTIDATASET_BENCHMARK.md — 头对头与跨数据集结果
• USAGE.md — 完整使用指南

⚠️ 说明

• 研究代码：来自本科材料信息学项目，主案例使用私有电解液数据集（未随仓库分发）。
• AI 辅助编码；所有结果可由仓库内脚本与固定随机种子复现。

📄 License

MIT © wenyu2026