Skip to main content

LammpsForcefieldTools

PyPI Python License: GPL-2.0

把分子/晶体结构自动转换为可运行的 LAMMPS 力场与拓扑输入,同时提供 GROMACS 兼容输出。命令行入口为 lft。

lft -f molecule.mol2          # 生成 molecule.data + molecule.in
lmp -in molecule.in           # 直接运行

功能特性

能力 说明
结构读入 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 时:

  1. 结构自带电荷 → 直接使用;
  2. 非周期且 ≤50 原子 → resp;
  3. 非周期且 51–200 原子 → am1-bcc;
  4. 非周期且 >200 原子 → mmff94;
  5. 周期结构 → 必须显式提供电荷,否则报错。

--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)

Source distribution for lammps-forcefield-tools 1.1.0
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)

Table of built distributions (wheels) for lammps-forcefield-tools 1.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page