Metadata-Version: 2.4
Name: lammps-trajan
Version: 0.0.7
Summary: LAMMPS trajectory file analysis utility
Project-URL: Homepage, https://github.com/DuGroup-FGM2L/trajan
Project-URL: Source, https://github.com/superde1fin/trajan
Project-URL: Issues, https://github.com/superde1fin/trajan/issues
License: GPL-3.0-only
License-File: LICENSE
Requires-Python: >=3.6
Requires-Dist: importlib-metadata<6.7.0; python_version < '3.8'
Requires-Dist: numpy>=1.21.6
Requires-Dist: scipy>=1.7.3
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.1; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Trajan

LAMMPS trajectory analysis utility for [LAMMPS](https://lammps.sandia.gov), developed by Vasilii Maksimov at the Functional Glasses and Materials Modeling Laboratory (FGM²L) at the University of North Texas, under the supervision of Dr. Jincheng Du.

**Trajan** is a command-line utility for analyzing molecular dynamics trajectories generated by LAMMPS. It is designed with a focus on disordered systems and oxide glasses, offering specialized tools for calculating density evolution, bond angle distributions, $Q^n$ species distributions, radial distribution functions, and ring size distributions.

## 🔧 Features

- **Command-line interface** with `argparse`-based subcommands
- **Memory efficient**: Batch processing for neighbor list generation in large systems
- **Glass Science Toolkit**:
    - **Density**: Time-dependent density evolution
    - **Angle**: Bond angle distributions with cutoff support
    - **Q-unit**: Network connectivity analysis ($Q^n$ distribution)
    - **RDF**: Partial radial distribution functions and Neutron Total Correlation Functions ($T(r)$)
    - **Rings**: Primitive and Smallest ring size distribution analysis
- **Experimental comparison**: Includes Lorch window broadening for $T(r)$ to match experimental $Q_{max}$
- **Modular design**: New analysis methods can be added as handler classes

## 📦 Installation

### Install from PyPI

The package is published on PyPI. You can install the latest stable release with:

```bash
pip install lammps-trajan
```

### Install directly from GitHub (bleeding-edge)

For the latest development version:

```bash
pip install git+https://github.com/superde1fin/trajan.git
```

### Clone & install locally

For local experimentation or contributing:

```bash
git clone https://github.com/superde1fin/trajan.git
cd trajan

# Standard install
pip install .

# OR editable install (auto-reload while editing)
pip install -e .
```

*Requires Python ≥ 3.6, `numpy`, and `scipy`.*

## 🥪 Usage

The general syntax involves providing the trajectory file first, followed by the specific analyzer command:

```bash
trajan [file] [analyzer] [options]
```

### 1. Density Analysis
Calculates the system density over the trajectory. You must provide the atomic masses or element symbols.

**Example:**
```bash
trajan glass_melt.lammpstrj density Si O Na
```

---

### 2. Bond Angle Distribution (`angle`)
Calculates the distribution of bond angles for a specified triplet of atom types (Type1-Type2-Type3), where Type2 is the central atom.

**Example:**
```bash
trajan glass_melt.lammpstrj angle 1 2 1 -c 1.8 1.8 -b 500
```

---

### 3. Q-unit Distribution (`qunit`)
Calculates the distribution of $Q^n$ species. The input requires a list of "Former" types and "Connector" types separated by a `0`.

**Example:**
```bash
trajan silica.lammpstrj qunit 1 0 2 -c 1.8
```

---

### 4. Radial Distribution Functions (`rdf`)
Calculates partial Radial Distribution Functions $g(r)$ and the Neutron Total Correlation Function $T(r)$.

**Example:**
```bash
trajan glass.lammpstrj rdf -t Si O Na -br 25.0
```

---

### 5. Ring Size Distribution (`rings`)
Analyzes the network topology by identifying rings of various sizes. It supports both **Smallest** and **Primitive** ring algorithms.

**Syntax:** `[Base Atoms] 0 [Connectors]`

**Example:**
```bash
trajan glass.lammpstrj rings 1 0 2 -c 1.8 -m 12 -a p
```
*In this example, Type 1 atoms (e.g., Si) are the base nodes, and Type 2 (e.g., O) are connectors. The analysis looks for Primitive rings up to size 12.*

**Options:**
- `types`: Atom types for base and connectors separated by a `0`.
- `-c` / `--cutoffs`: Distance thresholds for bonding.
- `-cb` / `--connector-bonds`: Max number of bonds for each connector type (default: 2).
- `-m` / `--max-size`: Maximum ring size to detect (default: 10).
- `-a` / `--algorithm`: Algorithm choice: `p` for Primitive or `s` for Smallest rings.
- '-p' / `--paral-mode`: Parallelization choice: `a` for atoms or `f` for frame based (not yet implemented).

## 📚 Documentation

All subcommands support `-h` or `--help` flags for detailed usage:

```bash
trajan rings --help
```

## 🧠 Design Overview

The project follows a modular "Handler" architecture:

- `cli.py`: Main entry point; handles argument parsing and dispatches to specific handlers.
- `base_handler.py`: Core logic for parsing LAMMPS dump files and neighbor searching.
- `handlers/`: Contains the logic for specific analyses:
    - `density.py`: Simple mass/volume calculations.
    - `angle.py`: Vector algebra for bond angles.
    - `qunit.py`: Network topology analysis.
    - `rdfs.py`: Pairwise distances and Fourier transform logic.
    - `rings.py`: Graph-based ring searching using BFS and shortest path algorithms.

## 🥪 Development

Install dev dependencies:

```bash
pip install .[dev]
```

## 🔖 License

GNU General Public License v3.0 (GPLv3). See [LICENSE](LICENSED) for details.

## 👤 Author

Vasilii Maksimov
University of North Texas
✉️  VasiliiMaksimov@my.unt.edu

## 🌐 Links

- 🔬 [LAMMPS Official Site](https://lammps.sandia.gov)
- 📆 [PyPI Page](https://pypi.org/project/lammps-trajan)
- 🐙 [GitHub Repository](https://github.com/superde1fin/trajan)
