lat — LAMMPS Analysis Tool
面向 LAMMPS data / lammpstrj 的轨迹分析工具。命令风格对齐 GROMACS(-s 拓扑、-f 轨迹、单横线参数),
输出统一为带审计头的 CSV,适合脚本批处理、回归与作图。
特性
- 直接读 LAMMPS:
*.data/*.lmp+*.lammpstrj,自动识别atom_style,按质量推断元素。 - GROMACS 兼容输入:
.tpr/.gro/.pdb+.xtc/.trr/.gro可直接分析,便于交叉验证。 - 周期几何一致性:所有距离、质心、整分子复原、网格与曲面都走同一套最小镜像实现。
- 可复现输出:文件名即意图;CSV 头记录命令、选择、参数、警告与标量;同名输出自动备份。
- 自解释:
lat --help列出模块,lat <module> -h给出参数与默认值,lat describe -module <name>给出完整契约。
安装
需要 Python ≥ 3.9。
pip install lammps-analysis-tools
安装后命令是 lat:
lat --version
lat --help
升级:
pip install --upgrade lammps-analysis-tools
从源码或离线安装:
git clone https://github.com/tgraphite/LammpsAnalysisTools.git
cd LammpsAnalysisTools
bash install.sh
export PATH="$HOME/.local/bin:$PATH"
install.sh 会建独立虚拟环境、安装依赖,并把 lat 放到 ~/.local/bin;系统 Python < 3.9 时会用
uv 引导一个私有 Python 3.11。也可以直接 pip install .。
依赖:numpy、scipy、pyyaml、matplotlib、MDAnalysis、ase。
快速开始
# 径向分布函数 + 配位数
lat rdf -s system.data -f run.lammpstrj -sel1 "type 2" -sel2 "type 5" -cutoff 10 -o out
# 沿 z 的密度剖面
lat density -s system.data -f run.lammpstrj -axis z -nbins 200 -o out
# 均方位移与扩散系数
lat msd -s system.data -f run.lammpstrj -sel "type 2" -o out
# 画图(输入是上一步的 CSV)
lat plot1d -f out.rdf.out.csv -o rdf.png
结果写入当前目录或 -o 指定的基名:
out.rdf.out.csv
out.rdf.cn.out.csv
支持输入
| 拓扑 | 轨迹 | |
|---|---|---|
| LAMMPS(首选) | .data / .lmp:Masses、Atoms;含 Bonds 才能做氢键/整分子分析 |
.lammpstrj(dump) |
| GROMACS | .tpr / .gro / .pdb |
.xtc / .trr / .gro |
- 自动识别
atomic、charge、molecular、full,支持full/kk等加速器后缀;六列歧义时用-style。 - 类型→元素默认按质量 ±0.2% 匹配;不确定时用
-types显式指定,或让 dump 带element列。 - 坐标支持
x/y/z、xu/yu/zu、xs/ys/zs、xsu/ysu/zsu;带ix/iy/iz可解包。 - 反应轨迹原子数逐帧变化时会报错,并提示用
-frame_range/-stride限定到一致窗口。
模块总览
| 模块 | 用途 | 手册 |
|---|---|---|
rdf |
径向分布函数 g(r) 与配位数 | rdf |
density |
一维/二维密度剖面 | density |
msd |
均方位移与扩散系数 | msd |
gyrate |
回转半径 Rg | gyrate |
rms |
RMSD / RMSF | rms |
contact |
两组间接触数与距离 | contact |
hbond |
氢键数量、寿命与空间分布 | hbond |
agg |
SSIP / CIP / AGG 离子聚合形态 | agg |
cluster |
配位数与团簇尺寸分布 | cluster |
pistack |
π–π 堆积 | pistack |
freevol |
自由体积、孔径分布、连通性 | freevol |
sasa |
溶剂可及表面积 | sasa |
residence |
配体滞留时间 | residence |
transport |
扩散、Nernst–Einstein、Green–Kubo | transport |
occupancy |
区域占据、穿越、首次通过 | occupancy |
select |
检查选择、导出 .ndx | select |
describe |
模块清单与契约 | describe |
plot1d |
一维 CSV 绘图 | plot1d |
plot2d |
二维 CSV 绘图 | plot2d |
完整手册(公共参数、输入、选择语法、输出契约):docs/manual。
公共参数
| 参数 | 说明 |
|---|---|
-s, -topo |
拓扑文件(分析模块必填) |
-f, -traj |
轨迹文件 |
-o |
输出基名;缺省用拓扑文件名 |
-unit |
长度单位:real、metal、lj;缺省用配置 |
-style |
强制 LAMMPS atom_style |
-types |
type→元素映射文件,每行 type element |
-index, -n |
GROMACS .ndx,为选择提供命名组 |
-frame_range |
帧窗口 start:stop[:stride],stop 不含 |
-stride |
每隔多少帧取一帧 |
-v |
显示 INFO 进度 |
-debug |
额外写 JSON 审计 |
-h |
模块帮助(含默认值) |
-V, --version |
版本号 |
PBC 始终开启,所有距离使用最小镜像。时间轴是帧号,不解析文件中的物理时间。
选择语法
MDAnalysis 风格子集,支持 and、or、not 与括号;相邻关键字隐含 and。
| 关键字 | 含义 | LAMMPS | GROMACS |
|---|---|---|---|
all |
全部原子 | 是 | 是 |
type |
原子类型 | 是 | 是 |
element |
元素符号 | 是(需推断或 -types) |
是 |
mol |
分子 ID | 是(需分子信息) | 是 |
id |
原子 id | 是 | 是 |
index |
0-based 原子序号 | 是 | 是 |
name |
原子名 | 否 | 是 |
resname |
残基名 | 否 | 是 |
resid |
残基号 | 否 | 是 |
-sel "type 2"
-sel "type 2 or type 5"
-sel1 "resname LI" -sel2 "resname FSI"
-sel "all and not type 1"
单选择模块用 -sel;双选择模块用 -sel1/-sel2。先运行 lat select 验证命中。
输出
- 结果全部写入 CSV;stdout 为空,进度/警告/错误走 stderr。
- 文件名:
<basename>.<tag>[.<mode>].out.csv。 - 文件头以
#开头,包含 program、module、command、selections、definitions、frame_range、 scalars、warning、title、xlabel、ylabel、columns,最后是# --- data ---。 - 标量(首壳配位数、D、R²、寿命、积分等)在
# scalars:行,分号分隔。 - 同名文件先备份为
.bak.1、.bak.2……,不会静默覆盖。 - 退出码:0 成功,1 参数/输入/计算错误,130 中断;警告不改变退出码。
绘图
plot1d / plot2d 只读 CSV,计算与绘图解耦。
lat plot1d -f out.rdf.out.csv -o rdf.png
lat plot1d -f out.agg.labels.out.csv -columns A_SSIP,A_CIP,A_AGG -o spec.png
lat plot1d -f out.agg.labels.out.csv -stack -o spec_stack.png
lat plot2d -f out.density.2d.out.csv -o density2d.png
-smooth(none/gaussian/savgol)只在绘图阶段生效,CSV 始终是原始值;
-bar 与 -stack 互斥,且不做平滑。
配置
默认值来自 lat.yaml:源码树是 config/lat.yaml,安装后是包内 data/lat.yaml。
命令行覆盖配置。
| 环境变量 | 作用 |
|---|---|
LAT_CONFIG |
使用自定义配置文件 |
LAT_VENV |
install.sh 创建的虚拟环境路径 |
LAT_BIN |
install.sh 放置 lat 的目录 |
PYTHON |
install.sh 使用的解释器 |
LAT_NO_UPDATE_CHECK |
设为 1 关闭自动更新检查 |
LAT_UPDATE_URL |
自定义 JSON 版本端点 |
LAT_UPDATE_INDEX |
自定义 PEP 503 简单索引(如内网镜像) |
LAT_UPDATE_INTERVAL_HOURS |
覆盖检查间隔(默认 24 小时) |
LAT_UPDATE_TIMEOUT_S |
覆盖单源网络超时(默认 1.5 秒) |
更新检查
lat 在交互终端启动时做一次只提示、不安装的版本检查:
- 默认每 24 小时最多检查一次;结果缓存在
$XDG_CACHE_HOME/lat/update.json。 - 检查在后台线程执行,单源超时 1.5 秒,不阻塞命令,也不影响退出码。
- 同时查询 PyPI、
PIP_INDEX_URL、LAT_UPDATE_URL/LAT_UPDATE_INDEX,取最高版本。 - 只在 stderr 打印一行提示,例如:
[lat NOTICE] new version 1.2.0 available (current 1.1.0); upgrade with: pip install -U lammps-analysis-tools - 非交互终端、
CI环境、--version/-h/describe自动跳过。 - 关闭:
LAT_NO_UPDATE_CHECK=1,或配置update.enabled: false。 - 手动检查:
lat --check-update;单次跳过:lat --no-update-check <module> ...。
lat 不会自动下载或执行任何更新;升级始终由你通过 pip/uv 完成。
文档
- 逐模块手册:docs/manual
- 公共参数与输出契约:common.md
- 版本变更:CHANGELOG.md
常见问题
选择命中 0 个原子? 用 lat select 检查表达式;LAMMPS 拓扑通常没有 resname/name。
元素推断失败? 补 Masses,或让 dump 带 element 列,或用 -types。
氢键报 “no donor”? 给体只认 N/O/F/S/Cl/Br/I 上的 H;C–H 不是给体。
MSD 提示没有 image flags? 轨迹只有 wrapped 坐标,MSD 可能饱和;改用带 xu/yu/zu 或 ix/iy/iz 的 dump。
freevol 报三斜盒? 体素网格只支持正交且固定的盒子;改用分子/原子对分析或正交化盒子。
许可
Proprietary。详见 LICENSE。
Metadata
Release files for lammps-analysis-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_analysis_tools-1.1.0.tar.gz | 102.8 kB | Without provenance | Details for lammps_analysis_tools-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| lammps_analysis_tools-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for lammps_analysis_tools-1.1.0-py3-none-any.whl |
Total release size: 242.2 kB
Release files / lammps_analysis_tools-1.1.0.tar.gz
| Download URL | lammps_analysis_tools-1.1.0.tar.gz |
|---|---|
| Size | 102.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
52c998f0fa811051c26d9e53f7af8b3f576623bb73d02bb4d678df218792c7ee
|
|
BLAKE2b-256 checksum How to use checksums |
885d3d9ff2520f6cd1569851dcbc1f6bd68ccd46812afa8baefbc1eedff9e901
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Release files / lammps_analysis_tools-1.1.0-py3-none-any.whl
| Download URL | lammps_analysis_tools-1.1.0-py3-none-any.whl |
|---|---|
| Size | 139.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9cd64266f8b644ff5d2c6a779498d83d5b6cadff8e4e1162172ac9c60a1c8b0
|
|
BLAKE2b-256 checksum How to use checksums |
60766e727ad6fcd98c7dadaf59dcaa8a9d4e2da2533c0329511777a4a2d07d35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.5
|
Security for lammps-analysis-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.