lps-lii-ps4-density-analysis/README.org

Li2S-P2S5-LiI Glass: PS4-Centered Ion Density Analysis

• Overview
• Files
• Requirements
• Input Trajectory Format
• Analysis Procedure
• Usage
  • Generate Cube Files
  • Visualize I^- Probability Density
  • Visualize Li+ Probability Density
• Output
• Visualization Colors
• Notes
• Citation
• License

Overview

This repository contains Python scripts for analyzing and visualizing Li and I spatial probability distributions around PS4^{3-} units in Li2S-P2S5-LiI glass trajectories.

The workflow consists of two steps:

1. dump2cube.py

   • Reads a LAMMPS trajectory.
   • Aligns each PS4^{3-} tetrahedron using the nearest I^- ion.
   • Accumulates Li and I positions in the aligned coordinate system.
   • Outputs three-dimensional probability-density data in Gaussian cube format.

2. cube2mayavi.py

   • Reads the generated cube file.
   • Visualizes the spatial probability density as an isosurface using Mayavi.
   • Displays the reference PS4^{3-} tetrahedron.

The scripts are intended to analyze the local geometrical relationship between I^- ions and PS4^{3-} units in Li2S-P2S5-LiI glasses.

Files

File	Description
dump2cube.py	Converts a LAMMPS trajectory into Li/I probability-density cube files.
cube2mayavi.py	Visualizes a cube file with Mayavi.
050Li3PS4-050LiI.lammpstrj	Example LAMMPS trajectory.
050Li3PS4-050LiI_PS4_I.cube	Example I^- probability-density cube file.

Requirements

The scripts require Python 3 and the following packages:

• NumPy
• Mayavi
• VTK
• Traits
• PyQt5 or PySide6, depending on the Mayavi installation

Example installation using conda:

conda create -n ps4-density python=3.10
conda activate ps4-density
conda install -c conda-forge numpy mayavi pyqt

Alternatively, NumPy can be installed using pip:

pip install numpy

Mayavi installation is generally more stable with conda-forge.

Input Trajectory Format

dump2cube.py assumes a LAMMPS trajectory containing the following atom columns:

ITEM: ATOMS id type element mol x y z

The trajectory must contain at least the following elements:

• Li
• P
• S
• I

The script assumes that P and S atoms belonging to the same PS4^{3-} unit share the same molecule ID (mol).

Analysis Procedure

For each trajectory frame:

1. Each P atom is selected as the center of a reference PS4^{3-} unit.
2. The four nearest I^- ions are identified.
3. The nearest I^- ion is used to define the orientation of the PS4^{3-} unit.
4. The PS4^{3-} tetrahedron is rotated into a common reference frame.
5. Li positions within the cutoff distance are accumulated.
6. The positions of the four nearest I^- ions are accumulated.
7. Three-dimensional histograms are written as cube files.

The reference orientation is defined as follows:

• The S atom farthest from the nearest I^- ion is aligned with the z axis.
• A second S atom is used to fix the rotation around the z axis.

Usage

Generate Cube Files

python dump2cube.py \
  -i 050Li3PS4-050LiI.lammpstrj \
  -m 160 160 160 \
  -cut 8

Arguments:

Argument	Description
-i, --trjfile	Input LAMMPS trajectory file.
-m, --mesh	Number of grid points in x, y, and z directions.
-cut, --cutoff	Spatial cutoff radius in angstrom.

Expected output files:

050Li3PS4-050LiI_PS4_Li.cube
050Li3PS4-050LiI_PS4_I.cube

Visualize I^- Probability Density

python cube2mayavi.py \
  -i 050Li3PS4-050LiI_PS4_I.cube \
  -atom I \
  -iso 1.26483e-09

Visualize Li+ Probability Density

python cube2mayavi.py \
  -i 050Li3PS4-050LiI_PS4_Li.cube \
  -atom Li \
  -iso 1.0e-09

The appropriate isovalue depends on the trajectory length, mesh size, cutoff radius, and probability-density distribution. It should therefore be adjusted for each dataset.

Output

The cube files contain:

• A reference PS4^{3-} tetrahedron:

  • P atom at the origin
  • Four S atoms in the aligned coordinate system
• A three-dimensional spatial probability-density field for Li or I

The cube files can be visualized using:

• Mayavi
• VMD
• PyMOL
• ParaView
• Other software supporting Gaussian cube files

Visualization Colors

The default visualization settings in cube2mayavi.py are:

Object	Color
P	Purple
S	Yellow
Li probability density	Blue
I probability density	Red
P-S bonds	Gray

Notes

• The trajectory is treated using periodic boundary conditions.
• Coordinates are converted to fractional coordinates before alignment.
• The current implementation assumes an orthorhombic simulation box for the trajectory parsing procedure.
• The script includes a triclinic-cell lattice conversion function, but the exact input format should be checked before applying it to triclinic LAMMPS trajectories.
• Large trajectory and cube files can exceed the standard GitHub file-size limit. Git LFS is recommended when files are larger than 100 MB.

Citation

If this repository is used in research, please cite the corresponding publication or presentation describing the Li2S-P2S5-LiI glass analysis.

License

This repository is intended for academic research use.