lammps-trajan 0.0.5

LAMMPS trajectory file analysis utility

Trajan

LAMMPS trajectory analysis utility for LAMMPS, 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:

pip install lammps-trajan

Install directly from GitHub (bleeding-edge)

For the latest development version:

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

Clone & install locally

For local experimentation or contributing:

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:

trajan [file] [analyzer] [options]

1. Density Analysis

Calculates the system density over the trajectory. You must provide the atomic masses or element symbols.

Example:

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:

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:

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:

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:

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:

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:

pip install .[dev]

🔖 License

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

👤 Author

Vasilii Maksimov University of North Texas ✉️ [e-mail]

🌐 Links

• 🔬 LAMMPS Official Site
• 📆 PyPI Page
• 🐙 GitHub Repository