lammps-trajan 0.0.16

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
  • vDOS: Vibrational Density of States Calculation
• 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

DISCLAMER: This usage manual is compressed. For more details refer to the help (-h/--help) options of the handlers.

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

Options:

• elements: Space separated list of element names for each type present in the trajectory file. In case a custom mass has been used a numerical value canbe specified.
• -u / --units: LAMMPS unit set for conversion.

---

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

Options:

• types: Integer values representing atomic types of a bonded triplet with the atom of second type in the middle.
• -c / --cutoffs: Maximum distances allowed for nearest species of a triplet to be considered bonded.
• -b / --bincount: Number of bins for the bond angle histogram.

---

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

Options:

• types: Integer values representing atomic types of network formers and connectors separated by a zero.
• -c / --cutoffs: Maximum distances between each former and connector (in Angstroms) for them to be considered bonded.

---

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

Options:

• -c / --cutoffs: Maximum atomic separation distance considered for the generation of the radial distribution functions.
• -p / --pair: Atomic type pairs for selecting specific partial distribution functions.
• -b / --bincount: Number of bins for the radial distribution functions.
• -bs / --batch-size: Number of atoms whose neighbors are analyzed at a time.
• -cn / --coordination-number: Command line switch to invoke the coordination number calculation for each of the analyzed atomic pairs.
• -t / --total: Calculate the total correlation function based on the atom type mappings or custom neutron scattering lengths.
• -br / --broaden: When this flag is the idealized total correlation function is broadened to match experimental results.
• -s / --scatter: Command line switch to invoke scattering factors' calculation. This flag can be supplied with maximum of two values: dq (momentum resolution) and Qmax (maximum momentum transfer)

---

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

5. Vibrational Density of States (vdos)

Combines the per-atom mass and velocity data of a simulation to generate the vibrational frequency analysis.

Example:

trajan glass.lammpstrj vdos 0.05 -m 100 -t 0.05

Options:

• timestep: Difference in simulation time between recorded timesteps.
• -m / --max_timelag: Maximum velocity autocorrelation function time difference in simulation units.
• -u / --units: LAMMPS unit set for conversion.
• -l / --lag-step: Velocity autocorrelation function resolution in simulation time units.
• -t / --taper: Fraction of velocity autocorrelation function to be tapered down to 0 for a clean FFT.
• -r / --resolution: Desired vDOS frequency resolution in cm^-1.

6. Infrared Absorption Intensity / Optical Conductivity (ftir)

Combines the per-atom charge and velocity data of a simulation to generate the vibrational frequency analysis.

Example:

trajan glass.lammpstrj ftir 0.05 -m 100 -t 0.05

Options:

• timestep: Difference in simulation time between recorded timesteps.
• -m / --max_timelag: Maximum charge flux autocorrelation function time difference in simulation units.
• -u / --units: LAMMPS unit set for conversion.
• -l / --lag-step: Total charge flux autocorrelation function resolution in simulation time units.
• -t / --taper: Fraction of total charge flux autocorrelation function to be tapered down to 0 for a clean FFT.
• -r / --resolution: Desired vDOS frequency resolution in cm^-1.
• -q / --quantum-coorection: Quantum-mechanical correction for high frequency mode emission.
• -df , --degrees-of-freedom : Scaling factor for DOF calculation for temperature evaluation.

📚 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.
  • vdos.py: Velocity autocorrelation function calculator + FFT
  • ftir.py: Total charge flux autocorrelation function calculator + FFT

🥪 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