lammps-trajan 0.0.2

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 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:

pip install lammps-trajan

Install directly from GitHub (bleeding-edge)

For the latest development version:

pip install git+[https://github.com/superde1fin/trajan.git](https://github.com/superde1fin/trajan.git)

Clone & install locally

For local experimentation or contributing:

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:

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

If your trajectory uses custom masses, you can specify values directly:

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:

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:

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):

# 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:

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).

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:

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:

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
• 🐙 GitHub Repository