Metadata-Version: 2.4
Name: lammps-trajan
Version: 0.0.2
Summary: LAMMPS trajectory file analysis utility
Project-URL: Homepage, https://github.com/superde1fin/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 neutron total correlation functions $T(r)$ with experimental broadening.

## 🔧 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)$)
- **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](https://github.com/superde1fin/trajan.git)
```

### Clone & install locally

For local experimentation or contributing:

```bash
git clone [https://github.com/superde1fin/trajan.git](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
```
*If your trajectory uses custom masses, you can specify values directly:*
```bash
trajan glass_melt.lammpstrj density 28.085 15.999 22.99
```

**Options:**
- `-u` / `--units`: LAMMPS unit set (default: `metal`). Supports `real` and `metal`.

---

### 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
```
*This calculates the angle distribution for Type 1 - Type 2 - Type 1, assuming a bond cutoff of 1.8 Å.*

**Options:**
- `types`: Three integers representing the atomic types (e.g., `1 2 1`).
- `-c` / `--cutoffs`: Maximum distance for atoms to be considered bonded.
- `-b` / `--bincount`: Number of histogram bins (default: 1000).

---

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

**Syntax:** `[Formers] 0 [Connectors]`

**Example:**
```bash
trajan silica.lammpstrj qunit 1 0 2 -c 1.8
```
*In this example, Type 1 is the network former (e.g., Si) and Type 2 is the connector (e.g., O). The cutoff is 1.8 Å.*

**Complex Example (Aluminosilicate):**
```bash
# Types: 1=Si, 2=Al, 3=O
trajan glass.lammpstrj qunit 1 2 0 3 -c 1.8 1.9
```
*Note: Cutoffs must be provided for every Former-Connector pair in order.*

---

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

**Basic RDF Example:**
```bash
trajan glass.lammpstrj rdf -p 1 2 -p 1 1 -c 10.0
```

**Neutron Total Correlation Function Example:**
To calculate $T(r)$, you must map atom types to their neutron scattering lengths (or element names).

```bash
trajan glass.lammpstrj rdf -t Si O Na -br 25.0
```
*This calculates the total correlation function using standard scattering lengths for Si, O, and Na, and applies experimental broadening with $Q_{max} = 25.0$ Å⁻¹.*

**The Physics:**
When `-t` is invoked, Trajan calculates:
$$
T(r) = 4\pi r \rho_0 G_{total}(r)
$$
If `-br` (broadening) is used, the function is convolved with a Lorch window function to simulate the termination effects of experimental scattering data at finite $Q_{max}$.

**Options:**
- `-c` / `--cutoff`: Max distance (default: 10 Å).
- `-p` / `--pair`: Specific pairs to analyze (e.g., `-p 1 2`). Ignored if `-t` is used.
- `-t` / `--total`: Calculate total correlation function. Provide list of elements or scattering lengths.
- `-br` / `--broaden`: Apply experimental broadening ($Q_{max}$ in Å⁻¹).
- `-bs` / `--batch-size`: Atom batch size for memory management (default: 1000).

## 📚 Documentation

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

```bash
trajan rdf --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, handling periodic boundary conditions, 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 for broadening.

## 🥪 Development

Install dev dependencies:

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

## 🔖 License

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

## 👤 Author

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

## 🌐 Links

- 🔬 [LAMMPS Official Site](https://lammps.sandia.gov)
- 🐙 [GitHub Repository](https://github.com/superde1fin/trajan)
