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
量化 内置 pySCF:单点、PCM、Hessian、ESP,无外部量化程序依赖
参数化 经典参数 + Hessian 投影;手动参数 JSON
LAMMPS 输出 real 单位、atom_style full、.data + .in,可选 moltemplate
GROMACS 输出 .itp、.top、.gro、.mdp
周期体系 镜像感知键合项;晶体必须显式提供电荷
诊断 重要警告直接显示;完整披露写入 <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.data
water.in

运行 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 当前目录 产物目录
--force 关闭 覆盖同名产物
--debug 关闭 写出 <name>.lft/debug.txt 诊断包
-V, --version — 显示版本
-h, --help — 显示帮助

电荷自动选择

未指定 --charge 时:

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

--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 做对照

文档

文档 内容
使用手册 安装、完整 CLI、电荷、周期、产物、排错
模块现状 模块成熟度、能力矩阵、验证结果与已知边界
更新日志 版本变更

已知限制

  • 经典键合参数库尚不完整;未命中项使用确定性通用值,并在 notes.txt 中标注。
  • UFF/共轭二面角当前使用占位参数,定量工作前应核对或用 --manual-file 覆盖。
  • AM1-BCC 默认不做几何优化,电荷依赖输入构象。
  • 周期体系只接受显式电荷,不做 ESP/密度电荷拟合。
  • LAMMPS 输出固定 10 Å 直接截断,未启用 PPPM/PME。
  • 不提供构象搜索、体系组装、MD 采样或力场重优化。

许可证

GNU General Public License v2.0,见 LICENSE。

Metadata

Release files for lammps-forcefield-tools 0.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 0.1.0
File Size Uploaded Provenance Actions
lammps_forcefield_tools-0.1.0.tar.gz 358.7 kB Without provenance Details for lammps_forcefield_tools-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lammps-forcefield-tools 0.1.0
File Interpreter ABI Platform Actions
lammps_forcefield_tools-0.1.0-py3-none-any.whl Python 3 none any Details for lammps_forcefield_tools-0.1.0-py3-none-any.whl

Total release size: 662.1 kB

Release files / lammps_forcefield_tools-0.1.0.tar.gz

Download URL lammps_forcefield_tools-0.1.0.tar.gz
Size 358.7 kB
Tags Source
SHA-256 checksum
How to use checksums
39802b906c210ea428cc56d723ebace188d8d51c1907f43766d55b24e8c007b6
BLAKE2b-256 checksum
How to use checksums
1a1153f5b9ca8477a905945a0671e4140b601035e75aa77d3ed339bff8c461e1
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-0.1.0-py3-none-any.whl

Download URL lammps_forcefield_tools-0.1.0-py3-none-any.whl
Size 303.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ffc67c27aeef79c8ad1785bfad867bb118e536021e6c3c6a18055f6a051920e7
BLAKE2b-256 checksum
How to use checksums
648a962a779566b336f673a6a6542a80169727a8280a7a5ca348d76829f76d15
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 0.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

0.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