语言版本: 中文 | English

文档（完善中）: https://bud-primordium.github.io/ThermoElasticSim/

ThermoElasticSim 是一个专门用于计算金属铝（Al）在零温和有限温度下弹性常数的分子动力学模拟工具。该项目基于 EAM (Embedded Atom Method) 势函数，结合了 Python 的易用性和 C++ 的高性能计算能力，通过结构优化和分子动力学（MD）模拟，采用显式变形法和应力涨落法，精确计算材料的弹性性质。

项目采用算符分离架构实现了多种MD系综，包括NVE、NVT（Berendsen、Andersen、Nosé-Hoover链）、NPT（MTK）等，为有限温弹性常数计算提供了可靠的统计力学基础。

1. 零温弹性常数计算（FCC金属 + Diamond）

   • 支持铝（Al）和铜（Cu）材料
   • 支持金刚石（C, diamond，Tersoff 1988）
   • 确定平衡晶格构型
   • 施加独立应变，计算应力响应
   • 求解弹性常数（C11、C12、C44）
   • 多种系统尺寸和收敛性分析

2. 有限温弹性常数计算（FCC铝）

   • MTK-NPT预平衡确定有限温平衡态
   • Nosé-Hoover链NVT采样应力涨落
   • 统计平均计算温度依赖弹性常数

3. 分子动力学系综

   • NVE：算符分离Velocity-Verlet积分
   • NVT：Berendsen弱耦合、Andersen随机碰撞、Nosé-Hoover链恒温器
   • NPT：Martyna-Tobias-Klein可逆积分器

4. 弹性波传播模拟

   • 解析计算：Christoffel方程求解任意方向波速
   • 特殊方向：[100]、[110]、[111]波速精确解
   • 各向异性可视化：2D极坐标图、3D速度面
   • 动力学模拟：MD平面波激发与传播
   • 多种测速算法：互相关、到达时间拟合、k-ω谱分析
   • 波源激发：高斯脉冲、Tone Burst

5. 计算架构

   • C++/Python混合编程，核心计算C++实现
   • EAM势函数及维里应力张量计算
   • 周期性边界条件和最小镜像原理
   • 多种数值优化器

• 更多教学场景与可视化绑定（轨迹/能量/应力）

项目采用经过验证的EAM (Embedded Atom Method) 势函数进行FCC金属的分子动力学模拟：

EAM_Dynamo_MendelevKramerBecker_2008_Al__MO_106969701023_006

• OpenKIM数据库收录：MO_106969701023_006
• 理论基础：Mendelev MI, Kramer MJ, Becker CA, Asta M. Analysis of semi-empirical interatomic potentials appropriate for simulation of crystalline and liquid Al and Cu. Philosophical Magazine. 2008;88(12):1723–50. doi:10.1080/14786430802206482
• 适用范围：晶体和液体铝的结构和动力学性质
• 验证精度：零温弹性常数与文献值误差小于1.3%，有限温与实验值吻合较好

EAM_Dynamo_MendelevKramerBecker_2008_Cu__MO_945691923444_006

• OpenKIM数据库收录：MO_945691923444_006
• 理论基础：同上文献，Mendelev等人2008年工作
• 适用范围：晶体和液体铜的结构和动力学性质
• 验证精度：零温C44误差0.23%，单轴弹性常数偏高，正在进一步完善中

Tersoff_LAMMPS_Tersoff_1988_C__MO_579868029681_004

• OpenKIM数据库收录：MO_579868029681_004
• 理论基础：Tersoff J. Empirical Interatomic Potential for Carbon, with Applications to Amorphous Carbon. Phys. Rev. Lett. 61, 2879 (1988). doi:10.1103/PhysRevLett.61.2879
• 适用范围（摘要）：以经验势准确刻画碳的结构与能量学（含金刚石、石墨的弹性、声子、多型体、缺陷与迁移势垒），并用于多种路径形成的非晶碳研究。
• 模型特性：C++ 后端解析实现（能量/力/三体维里）；三元簇分解的 virial 记账；张拉为正的应力约定。
• 零温平衡晶格常数：a0 = 3.5656 Å（与参考一致）
• 验证精度（相对于 OpenKIM 参考）：
  • 单轴弹性常数（C11、C12）：误差 ≤ 0.02%
  • 剪切常数（C44）：误差 ≈ 4.6%

ThermoElasticSim/
├── pyproject.toml          # 项目配置（依赖管理、构建设置）
├── CMakeLists.txt          # C++ 构建配置
├── README.md
├── src/
│   └── thermoelasticsim/
│       ├── _cpp/           # C++ 源码和 pybind11 绑定
│       │   ├── bindings/   # 模块化的绑定文件
│       │   └── *.cpp       # 核心计算实现
│       ├── core/           # 核心数据结构
│       ├── potentials/     # 势能模型
│       ├── elastic/        # 弹性常数计算
│       ├── md/             # 分子动力学
│       └── utils/          # 工具函数
├── tests/                  # 测试文件（镜像 src 结构）
├── examples/               # 使用示例
└── docs/                   # 文档

• Python 3.9+
• C++ 编译器（支持 C++11）
• uv（推荐）或 pip

# 0) 安装 uv（任选其一）
# macOS（Homebrew）
brew install uv
# macOS/Linux（通用脚本）
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 1) 克隆仓库
git clone https://github.com/bud-primordium/ThermoElasticSim.git
cd ThermoElasticSim

# 2) 创建并激活虚拟环境
uv venv && source .venv/bin/activate

# 3) 可编辑安装项目（自动构建 C++ 扩展）
uv pip install -e .

# 4) 验证 C++ 扩展
python -c "import thermoelasticsim._cpp_core as m; print('✓', m.__file__)"

# 开发者：先安装测试依赖
uv pip install -e ".[dev]"

# 运行测试（推荐用模块方式，避免 PATH 混淆）
python -m pytest
# 或：uv run --no-sync python -m pytest

# 可选：若坚持直接调用 pytest，请确保指向 venv：
.venv/bin/pytest

提示：如果你启用了 Conda 的 base 环境，可能存在 pytest 命令来自 base 的情况， 从而绕过当前 venv。使用 python -m pytest 可确保使用 venv 里的解释器与依赖。

• 自动化构建：scikit-build-core + pybind11。
• 可编辑模式：redirect，.so 在 site-packages；源码从 src/ 导入；构建产物在 build/{wheel_tag}。
• uv 提示：优先用 venv 内的 python/pytest；若用 uv run 跑测试，请加 --no-sync。

• ImportError: “pybind11 module _cpp_core is not available …”

  • 原因：尚未构建/安装 C++ 扩展，或被 uv run 的同步覆盖。
  • 解决：uv pip install -e ".[dev]" 后用 pytest（或 uv run --no-sync pytest）。

• NumPy 导入失败（缺少 C 扩展）

  • 项目依赖已升级到新版本栈：numpy>=2.0、numba>=0.60、scipy>=1.11。
  • 若镜像提供源码包导致装到 sdist，可强制轮子安装： uv pip install -U --only-binary=:all: "numpy>=2" "numba>=0.60" "scipy>=1.11"。

直接用 YAML 驱动程序，产物与 benchmark 一致：

# 零温完整（多尺寸扫描）
python -m thermoelasticsim.cli.run -c examples/modern_yaml/zero_temp_elastic.yaml

# 有限温完整（预热→NPT→NHC 生产）
python -m thermoelasticsim.cli.run -c examples/modern_yaml/finite_temp_elastic.yaml

# 弹性波模拟
python -m thermoelasticsim.cli.run -c examples/modern_yaml/elastic_wave.yaml            # 解析计算与可视化
python -m thermoelasticsim.cli.run -c examples/modern_yaml/elastic_wave_dynamics_L.yaml # 纵波传播模拟
python -m thermoelasticsim.cli.run -c examples/modern_yaml/elastic_wave_dynamics_T.yaml # 横波传播模拟

# 教学拆分单元
python -m thermoelasticsim.cli.run -c examples/modern_yaml/relax.yaml          # 零温弛豫（含 E–V/E–s 曲线）
python -m thermoelasticsim.cli.run -c examples/modern_yaml/nve.yaml            # NVE（温度/能量演化）
python -m thermoelasticsim.cli.run -c examples/modern_yaml/nvt_langevin.yaml   # NVT-Langevin
python -m thermoelasticsim.cli.run -c examples/modern_yaml/nvt_nhc.yaml        # NVT-NHC
python -m thermoelasticsim.cli.run -c examples/modern_yaml/nvt_andersen.yaml   # NVT-Andersen
python -m thermoelasticsim.cli.run -c examples/modern_yaml/nvt_berendsen.yaml  # NVT-Berendsen
python -m thermoelasticsim.cli.run -c examples/modern_yaml/npt.yaml            # NPT-MTK

所有 YAML 都有中文注释，解释材料/结构、势函数、步数/步长/采样、恒温/恒压参数，零温应变点等。

uv run python examples/legacy_py/zero_temp_al_benchmark.py
uv run python examples/legacy_py/finite_temp_al_benchmark.py

示例 YAML 已放在 examples/modern_yaml/，包含零温/有限温完整流程与若干教学拆分场景。 每个 YAML 都有中文注释说明可调参数与选择方式。

欢迎贡献代码、报告问题或提出建议！请遵循以下步骤：

1. Fork 仓库

2. 创建分支

   git checkout -b feature/新功能名称

3. 提交更改

   git commit -m "添加了新功能"

4. 推送到分支

   git push origin feature/新功能名称

5. 创建 Pull Request

本项目采用 GNU GPLV3 许可证 进行授权。有关详细信息，请参阅 LICENSE 文件。

如有任何问题或建议，请通过 issue 与项目维护者联系。