lammps-analysis-tools 1.0.0__tar.gz

lammps-analysis-tools-1.0.0/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 tgraphite. All rights reserved.
+
+This software and its accompanying documentation (the "Software") are
+proprietary. No permission is granted to use, copy, modify, merge, publish,
+distribute, sublicense, or sell copies of the Software without the prior
+written permission of the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lammps-analysis-tools-1.0.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+# only the runtime package and its data ship in the sdist/wheel
+recursive-include src/lat/data *.yaml *.md
+
+# development material never ships
+prune tests
+prune docs
+prune config
+global-exclude __pycache__ *.py[cod] *.egg-info

lammps-analysis-tools-1.0.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.1
+Name: lammps-analysis-tools
+Version: 1.0.0
+Summary: Trajectory analysis for LAMMPS data/dump files, with GROMACS-compatible commands
+Author: tgraphite
+License: Proprietary
+Project-URL: Homepage, https://github.com/tgraphite/LammpsAnalysisTools
+Project-URL: Documentation, https://github.com/tgraphite/LammpsAnalysisTools/tree/main/docs/manual
+Project-URL: Repository, https://github.com/tgraphite/LammpsAnalysisTools
+Project-URL: Issues, https://github.com/tgraphite/LammpsAnalysisTools/issues
+Keywords: molecular dynamics,LAMMPS,GROMACS,trajectory analysis,RDF,hydrogen bonds,free volume,SASA
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Requires-Dist: pyyaml>=5.4
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: MDAnalysis>=2.4
+Requires-Dist: ase>=3.22
+
+# lat — LAMMPS Analysis Tool
+
+[![PyPI](https://img.shields.io/pypi/v/lammps-analysis-tools.svg)](https://pypi.org/project/lammps-analysis-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/lammps-analysis-tools.svg)](https://pypi.org/project/lammps-analysis-tools/)
+
+面向 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](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/rdf.md) |
+| `density` | 一维/二维密度剖面 | [density](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/density.md) |
+| `msd` | 均方位移与扩散系数 | [msd](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/msd.md) |
+| `gyrate` | 回转半径 Rg | [gyrate](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/gyrate.md) |
+| `rms` | RMSD / RMSF | [rms](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/rms.md) |
+| `contact` | 两组间接触数与距离 | [contact](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/contact.md) |
+| `hbond` | 氢键数量、寿命与空间分布 | [hbond](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/hbond.md) |
+| `agg` | SSIP / CIP / AGG 离子聚合形态 | [agg](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/agg.md) |
+| `cluster` | 配位数与团簇尺寸分布 | [cluster](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/cluster.md) |
+| `pistack` | π–π 堆积 | [pistack](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/pistack.md) |
+| `freevol` | 自由体积、孔径分布、连通性 | [freevol](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/freevol.md) |
+| `sasa` | 溶剂可及表面积 | [sasa](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/sasa.md) |
+| `residence` | 配体滞留时间 | [residence](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/residence.md) |
+| `transport` | 扩散、Nernst–Einstein、Green–Kubo | [transport](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/transport.md) |
+| `occupancy` | 区域占据、穿越、首次通过 | [occupancy](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/occupancy.md) |
+| `select` | 检查选择、导出 .ndx | [select](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/select.md) |
+| `describe` | 模块清单与契约 | [describe](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/describe.md) |
+| `plot1d` | 一维 CSV 绘图 | [plot1d](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/plot1d.md) |
+| `plot2d` | 二维 CSV 绘图 | [plot2d](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/plot2d.md) |
+
+完整手册（公共参数、输入、选择语法、输出契约）：[docs/manual](https://github.com/tgraphite/LammpsAnalysisTools/tree/main/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` 使用的解释器 |
+
+## 文档
+
+- 逐模块手册：[docs/manual](https://github.com/tgraphite/LammpsAnalysisTools/tree/main/docs/manual)
+- 公共参数与输出契约：[common.md](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/common.md)
+- 版本变更：[CHANGELOG.md](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/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](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/LICENSE)。

lammps-analysis-tools-1.0.0/README.md

@@ -0,0 +1,198 @@
+# lat — LAMMPS Analysis Tool
+
+[![PyPI](https://img.shields.io/pypi/v/lammps-analysis-tools.svg)](https://pypi.org/project/lammps-analysis-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/lammps-analysis-tools.svg)](https://pypi.org/project/lammps-analysis-tools/)
+
+面向 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](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/rdf.md) |
+| `density` | 一维/二维密度剖面 | [density](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/density.md) |
+| `msd` | 均方位移与扩散系数 | [msd](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/msd.md) |
+| `gyrate` | 回转半径 Rg | [gyrate](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/gyrate.md) |
+| `rms` | RMSD / RMSF | [rms](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/rms.md) |
+| `contact` | 两组间接触数与距离 | [contact](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/contact.md) |
+| `hbond` | 氢键数量、寿命与空间分布 | [hbond](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/hbond.md) |
+| `agg` | SSIP / CIP / AGG 离子聚合形态 | [agg](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/agg.md) |
+| `cluster` | 配位数与团簇尺寸分布 | [cluster](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/cluster.md) |
+| `pistack` | π–π 堆积 | [pistack](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/pistack.md) |
+| `freevol` | 自由体积、孔径分布、连通性 | [freevol](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/freevol.md) |
+| `sasa` | 溶剂可及表面积 | [sasa](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/sasa.md) |
+| `residence` | 配体滞留时间 | [residence](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/residence.md) |
+| `transport` | 扩散、Nernst–Einstein、Green–Kubo | [transport](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/transport.md) |
+| `occupancy` | 区域占据、穿越、首次通过 | [occupancy](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/occupancy.md) |
+| `select` | 检查选择、导出 .ndx | [select](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/select.md) |
+| `describe` | 模块清单与契约 | [describe](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/describe.md) |
+| `plot1d` | 一维 CSV 绘图 | [plot1d](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/plot1d.md) |
+| `plot2d` | 二维 CSV 绘图 | [plot2d](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/plot2d.md) |
+
+完整手册（公共参数、输入、选择语法、输出契约）：[docs/manual](https://github.com/tgraphite/LammpsAnalysisTools/tree/main/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` 使用的解释器 |
+
+## 文档
+
+- 逐模块手册：[docs/manual](https://github.com/tgraphite/LammpsAnalysisTools/tree/main/docs/manual)
+- 公共参数与输出契约：[common.md](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/manual/common.md)
+- 版本变更：[CHANGELOG.md](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/docs/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](https://github.com/tgraphite/LammpsAnalysisTools/blob/main/LICENSE)。

lammps-analysis-tools-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lammps-analysis-tools"
+version = "1.0.0"
+description = "Trajectory analysis for LAMMPS data/dump files, with GROMACS-compatible commands"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "Proprietary"}
+authors = [{name = "tgraphite"}]
+keywords = [
+    "molecular dynamics",
+    "LAMMPS",
+    "GROMACS",
+    "trajectory analysis",
+    "RDF",
+    "hydrogen bonds",
+    "free volume",
+    "SASA",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.22",
+    "scipy>=1.8",
+    "pyyaml>=5.4",
+    "matplotlib>=3.5",
+    "MDAnalysis>=2.4",
+    "ase>=3.22",
+]
+
+[project.urls]
+Homepage = "https://github.com/tgraphite/LammpsAnalysisTools"
+Documentation = "https://github.com/tgraphite/LammpsAnalysisTools/tree/main/docs/manual"
+Repository = "https://github.com/tgraphite/LammpsAnalysisTools"
+Issues = "https://github.com/tgraphite/LammpsAnalysisTools/issues"
+
+[project.scripts]
+lat = "lat.cli:main"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+lat = ["data/*.yaml", "data/manual/*.md"]

lammps-analysis-tools-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+