LammpsForcefieldTools
把分子/晶体结构自动转换为可运行的 LAMMPS 力场与拓扑输入,同时提供 GROMACS 兼容输出。命令行入口为 lft。
lft -f molecule.mol2 # 生成 molecule.data + molecule.in
lmp -in molecule.in # 直接运行
- GitHub:https://github.com/tgraphite/LammpsForcefieldTools
- PyPI:https://pypi.org/project/lammps-forcefield-tools/
- 使用手册:docs/MANUAL.md
功能特性
| 能力 | 说明 |
|---|---|
| 结构读入 | MOL2、PDB/ENT、PQR、GRO、XYZ、CIF/mmCIF、结构 JSON |
| 连接性 | 显式键优先;无键结构按共价半径与价键上限自动建键 |
| 拓扑 | 键、角、二面角、improper、1-4 pair,支持周期镜像 |
| 原子类型 | GAFF 规则引擎;gaff+uff 自动回退;支持纯 UFF 与手动映射 |
| 电荷 | 输入、MMFF94、AM1-BCC、RESP/RESP2、MK、CM5/raw-CM5、ADCH;dft- 前缀先用 DFT 优化几何 |
| 量化 | 内置 pySCF:单点、PCM、Hessian、ESP;geometric 几何优化,无外部量化程序依赖 |
| 几何预优化 | 默认 UFF(全元素可用);mmff94 用同名优化器,dft 用 pySCF |
| 参数化 | 内置 GAFF 1.81 参数库(键/角/多项二面角/improper/LJ),离线可用;Hessian 键投影;手动参数 JSON |
| LAMMPS 输出 | 默认 moltemplate(.lt + system.lt);--lammpsdata 写 .data + .in(周期体系启用 PPPM) |
| GROMACS 输出 | .itp、.top、.gro、.mdp |
| 周期体系 | 镜像感知键合项;晶体必须显式提供电荷;LAMMPS 周期默认 PPPM |
| 诊断 | 重要警告直接显示;完整披露写入 <name>.lft/ |
安装
要求 Python 3.11+。
python -m pip install --upgrade pip
python -m pip install lammps-forcefield-tools
检查安装:
lft --version
lft --help
从源码安装:
git clone https://github.com/tgraphite/LammpsForcefieldTools.git
cd LammpsForcefieldTools
python -m pip install .
开发/测试安装:
python -m pip install -e ".[test]"
python -m pytest -q
安装包会自动拉取:numpy、scipy、pyscf、dftd3、cclib、openbabel-wheel、PyYAML。
快速开始
仓库自带一个带电荷的水分子示例:
cd examples
lft -f water.mol2
输出:
water.lt
system.lt
用 moltemplate 生成 LAMMPS 输入:
moltemplate.sh system.lt
lmp -in run.in # 由 run.in.EXAMPLE 改写,或自行 include system.in.init/data/settings
要传统的 data/in 文件:
lft -f water.mol2 --lammpsdata
运行 LAMMPS:
lmp -in water.in
生成 GROMACS 输入:
lft -f water.mol2 --output gromacs
# water.itp water.top water.gro water.mdp
生成后立即做引擎输入烟测:
lft -f water.mol2 --engine-smoke
模块
程序按处理阶段组织,命令行会把各阶段自动串联:
| 阶段 | Python 包 | 职责 |
|---|---|---|
| 结构 | lft.io |
读取常见分子/晶体格式,输出统一结构模型 |
| 领域模型 | lft.domain |
原子、晶胞、拓扑项、参数、单位 |
| 拓扑 | lft.topology |
建键、键合项枚举、周期镜像处理 |
| 力场 | lft.forcefields |
GAFF/UFF/manual 原子类型与非键参数 |
| 电荷 | lft.charges |
AM1-BCC、RESP、密度电荷、电荷文件 |
| 量化 | lft.qc |
pySCF 单点、PCM、Hessian、ESP |
| 参数化 | lft.parameterize |
经典参数与 Hessian 投影 |
| 后端 | lft.backends |
LAMMPS 与 GROMACS 文件生成 |
| 外部程序 | lft.runners |
gmx、lmp、moltemplate、Packmol 受控调用 |
| 校验 | lft.validation |
结构、电荷、能量与 ground truth 校验 |
通用参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-f, --structure |
必填 | 输入结构文件 |
-o, --output |
lammps |
lammps 或 gromacs |
--ff |
gaff+uff |
gaff、gaff+uff、uff、manual |
--charge |
自动 | 电荷方法名或电荷文件路径 |
--net-charge |
0 |
分子形式电荷 |
--mult, --multiplicity |
1 |
自旋多重度 |
--outdir |
当前目录 | 产物目录 |
--lammpsdata |
关闭 | 写 .data + .in,而不是 moltemplate 文件 |
--preopt |
auto |
几何预优化:auto/none/uff/mmff94/dft |
--current-geometry |
关闭 | 平衡值取当前几何(构象专用,会打印 INFO) |
--allow-missing-torsions |
关闭 | 无参二面角省略而非报错 |
--generic-improper |
omit |
无参 improper:omit/amber/k10 |
--force |
关闭 | 覆盖同名产物 |
--debug |
关闭 | 写出 <name>.lft/debug.txt 诊断包 |
--check-update |
— | 立即检查 PyPI/配置镜像并退出 |
--no-update-check |
关闭 | 本次运行跳过自动更新提示 |
-V, --version |
— | 显示版本 |
-h, --help |
— | 显示帮助 |
电荷自动选择
未指定 --charge 时:
- 结构自带电荷 → 直接使用;
- 非周期且 ≤50 原子 →
resp; - 非周期且 51–200 原子 →
am1-bcc; - 非周期且 >200 原子 →
mmff94; - 周期结构 → 必须显式提供电荷,否则报错。
--charge 也可以直接给文件路径:
lft -f molecule.xyz --charge charges.txt
lft -f crystal.pdb --charge charges.txt --ff uff
高级参数
以下参数默认值通常正确,完整说明见使用手册:
--parameter-mode、--qc、--qc-backend、--hessian-file、--hessian-method、--manual-file、--no-qc、--engine-smoke、--moltemplate。
输入与输出
输入格式
| 后缀 | 连接性 | 周期性 |
|---|---|---|
.mol2 |
@<TRIPOS>BOND(推荐) |
@<TRIPOS>CRYSIN |
.pdb、.ent、.pqr |
CONECT 或距离推断 |
CRYST1 |
.gro |
距离推断 | box 行 |
.xyz |
距离推断 | 注释行晶格(可选) |
.cif、.mmcif |
距离推断 | 晶胞参数 |
.json |
文件内 bonds |
文件内 cell |
输出文件
LAMMPS(默认):
<name>.data 坐标、拓扑、原子类型与系数
<name>.in units / pair_style / bond_style / 运行设置
GROMACS:
<name>.itp 原子、键、角、二面角、1-4 pair
<name>.top 力场默认项与系统定义
<name>.gro 坐标
<name>.mdp 最小运行参数
按需出现:
<name>.lft/notes.txt 警告与参数来源披露
<name>.lft/image_map.json 周期图镜像映射
<name>.lft/debug.txt --debug 诊断
<name>.lft/normalized_ir.json --debug 规范化结构
配置
可选全局配置文件 lft.config,格式为 key = value:
output = lammps
ff = gaff+uff
charge = resp
qc = b3lyp-d3bj/def2-svp
gmx = /usr/local/gromacs/bin/gmx
lmp = /opt/lammps/bin/lmp
查找顺序:$LFT_CONFIG → 安装根目录 → Python 包目录。优先级:命令行 > 配置文件 > 内置默认。
常用环境变量:
| 变量 | 作用 |
|---|---|
LFT_CONFIG |
配置文件路径 |
LFT_GMX |
GROMACS 可执行文件 |
LFT_LMP |
LAMMPS 可执行文件 |
LFT_OBABEL |
OpenBabel 可执行文件 |
LFT_AM1BCC_OPTIMIZE |
AM1-BCC 几何优化:yes/no/auto |
LFT_ATOMTYPE_EXTERNAL |
用外部 atomtype 做对照 |
LFT_NO_UPDATE_CHECK |
设为 1 关闭自动更新检查 |
LFT_UPDATE_CHECK |
设为 0 关闭自动更新检查 |
LFT_UPDATE_URL |
自定义 JSON 版本端点 |
LFT_UPDATE_INDEX |
自定义 PEP 503 简单索引 |
LFT_UPDATE_INTERVAL_HOURS |
覆盖检查间隔(默认 24) |
LFT_UPDATE_TIMEOUT_S |
覆盖单源超时(默认 1.5 秒) |
更新检查
lft 在交互终端启动时做一次只提示、不安装的版本检查:
- 默认每 24 小时最多检查一次;结果缓存在
$XDG_CACHE_HOME/lft/update.json。 - 检查在后台线程执行,单源超时 1.5 秒,不阻塞管线,也不影响退出码。
- 同时查询 PyPI、
PIP_INDEX_URL、LFT_UPDATE_URL/LFT_UPDATE_INDEX,取最高版本。 - 发现新版本时只在 stderr 打印一行提示,例如:
[lft NOTICE] new version 1.2.0 available (current 1.1.0): pip install -U lammps-forcefield-tools - 非交互终端、
CI、--version/--help自动跳过。 - 关闭:
LFT_NO_UPDATE_CHECK=1或update_check = off;手动检查:lft --check-update; 单次跳过:lft --no-update-check -f ...。 lft不会自动下载或执行更新;升级始终由你通过 pip/uv 完成。
文档
| 文档 | 内容 |
|---|---|
| 使用手册 | 安装、完整 CLI、电荷、周期、产物、排错 |
| 模块现状 | 模块成熟度、能力矩阵、验证结果与已知边界 |
| 更新日志 | 版本变更 |
已知限制
- 内置 GAFF 键合参数覆盖 GAFF 1.81 的键/角/二面角;极少数角(如
h4-c-h4)仍会用几何通用值,notes.txt会标注。 - UFF 键合项仍是规则占位值;UFF 仅作为 GAFF 不支持元素的后备,定量工作建议核对或
--manual-file覆盖。 - 纯经验电荷的预优化用 UFF(毫秒级);
dft-电荷会做 DFT 几何优化,成本随原子数快速增长(默认上限 50 原子)。 - 周期体系只接受显式电荷,不做 ESP/密度电荷拟合;周期结构暂不参与 1:1 测试。
- 周期 LAMMPS 输出默认 PPPM(
kspace_style pppm 1.0e-4);非周期使用 10 Å 直接截断。 - 不提供构象搜索、体系组装、MD 采样或力场重优化。
许可证
GNU General Public License v2.0,见 LICENSE。
Metadata
Release files for lammps-forcefield-tools 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| lammps_forcefield_tools-1.1.0.tar.gz | 444.9 kB | Without provenance | Details for lammps_forcefield_tools-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lammps_forcefield_tools-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for lammps_forcefield_tools-1.1.0-py3-none-any.whl |
Total release size: 818.7 kB
Release files / lammps_forcefield_tools-1.1.0.tar.gz
| Download URL | lammps_forcefield_tools-1.1.0.tar.gz |
|---|---|
| Size | 444.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cfe6294a4812dfa76c0e67257efc3cf181ca16e981fc8b71039484dde237d235
|
|
BLAKE2b-256 checksum How to use checksums |
2fec2b28eeedefd108885c9689577c506f6fb78776c1b0c46221c134798b288a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Release files / lammps_forcefield_tools-1.1.0-py3-none-any.whl
| Download URL | lammps_forcefield_tools-1.1.0-py3-none-any.whl |
|---|---|
| Size | 373.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
33b85920bccfdf0b2f466fbf4fe40e2629f549c6945a2493e38a47404d2e0abd
|
|
BLAKE2b-256 checksum How to use checksums |
4c6b6c4ba79a07a5f155a028bf9992bd2d64524cd170a52a16c01bf7f6c34923
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.2
|
Security for lammps-forcefield-tools 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.