lps-lii-ps4-iodide-geometry/README.org

PS₄³⁻-Centered I⁻ Geometry Analysis in Li₂S–P₂S₅–LiI Glasses

• Overview
• Analysis Concept
• Workflow
• Files
• Requirements
  • Python packages
• Input Trajectory Format
• Analysis Procedure
• Normalization
• Usage
  • Generate Cube Files
  • Visualize Classified I⁻ Density Fields
• Output
• Notes and Limitations
• License

Overview

This repository contains Python scripts for analyzing the local geometrical relationship between I⁻ ions and PS₄³⁻ tetrahedra in Li₂S–P₂S₅–LiI glass trajectories.

For each P atom, nearby I⁻ ions are classified according to the number of S atoms from the same PS₄³⁻ tetrahedron located within a specified I–S cutoff distance.

The resulting I⁻ spatial-density distributions are exported as Gaussian cube files and visualized as three-dimensional isosurfaces using Mayavi.

Analysis Concept

For a given I⁻ ion and a given PS₄³⁻ tetrahedron, the number of nearby S atoms is defined as:

s_count = number of S atoms within 4.7 Å from I⁻

The I⁻ configuration is classified as follows:

Classification	s_count	Geometrical interpretation
Zero-type	0	I⁻ is not close to any S atom of the reference PS₄³⁻ unit.
Corner-type	1	I⁻ is located near one S vertex of the PS₄³⁻ tetrahedron.
Edge-type	2	I⁻ is located near two S atoms forming one tetrahedral edge.
Three-type	3	I⁻ is located near three S atoms of the same PS₄³⁻ unit.

The terms corner-type and edge-type describe geometrical proximity only. They do not imply bond sharing or atom sharing between I⁻ and PS₄³⁻ units.

Workflow

LAMMPS trajectory
      |
      v
dump2cube_edge_corner.py
      |
      +-- PS₄_I_All.cube
      +-- PS₄_I_zero.cube
      +-- PS₄_I_corner.cube
      +-- PS₄_I_edge.cube
      +-- PS₄_I_three.cube
      |
      v
cube2mayavi_edge_corner.py
      |
      v
Colored 3D isosurface visualization

Files

File	Description
dump2cube_edge_corner.py	Reads a LAMMPS trajectory, aligns PS₄³⁻ units, classifies nearby I⁻ ions, and generates cube files.
cube2mayavi_edge_corner.py	Visualizes multiple classified I⁻ cube files using different colors.
050Li3PS4-050LiI.lammpstrj	Example LAMMPS trajectory for a Li₂S–P₂S₅–LiI glass.
050Li3PS4-050LiI_PS4_I_All.cube	Spatial density of the four nearest I⁻ ions around each P atom.
050Li3PS4-050LiI_PS4_I_zero.cube	Spatial density of zero-type I⁻ configurations.
050Li3PS4-050LiI_PS4_I_corner.cube	Spatial density of corner-type I⁻ configurations.
050Li3PS4-050LiI_PS4_I_edge.cube	Spatial density of edge-type I⁻ configurations.
050Li3PS4-050LiI_PS4_I_three.cube	Spatial density of three-type I⁻ configurations.

Requirements

Python packages

The scripts require Python 3 and the following packages:

• NumPy
• Mayavi
• VTK
• Traits
• PyQt5 or PySide6

Mayavi is generally easiest to install through conda-forge.

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

Alternatively, NumPy can be installed with pip:

pip install numpy

Input Trajectory Format

dump2cube_edge_corner.py expects a LAMMPS trajectory containing the following atom columns:

ITEM: ATOMS id type element xu yu zu mol

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 PS₄³⁻ tetrahedron have the same molecule ID (mol).

Periodic boundary conditions are applied when calculating relative atomic positions.

Analysis Procedure

For every trajectory frame, the following procedure is performed.

1. Each P atom is selected as the center of a reference PS₄³⁻ tetrahedron.
2. The nearest I⁻ ion is used to define the orientation of the PS₄³⁻ unit.
3. The S atom farthest from the nearest I⁻ ion is aligned with the z axis.
4. A second S atom is used to fix the rotation around the z axis.
5. The closest I⁻ ions are rotated into the common PS₄³⁻ reference frame.
6. I⁻ ions are classified using the number of S atoms within 4.7 Å.
7. The classified I⁻ coordinates are accumulated over all P atoms and trajectory frames.
8. Three-dimensional histograms are exported as Gaussian cube files.

Normalization

The density fields for zero-type, corner-type, edge-type, and three-type I⁻ configurations are normalized by the total number of I⁻ coordinates used for the overall I⁻ distribution.

Therefore, the relative density of each classified field reflects both:

• the spatial distribution of the configuration, and
• the relative occurrence of that configuration.

Usage

Generate Cube Files

python dump2cube_edge_corner.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 along the x, y, and z directions.
-cut, --cutoff	Spatial cutoff distance around the reference P atom in Å.

Expected output files:

050Li3PS4-050LiI_PS4_I_All.cube
050Li3PS4-050LiI_PS4_I_zero.cube
050Li3PS4-050LiI_PS4_I_corner.cube
050Li3PS4-050LiI_PS4_I_edge.cube
050Li3PS4-050LiI_PS4_I_three.cube

Visualize Classified I⁻ Density Fields

python cube2mayavi_edge_corner.py \
  -i 050Li3PS4-050LiI_PS4_I_zero.cube \
     050Li3PS4-050LiI_PS4_I_corner.cube \
     050Li3PS4-050LiI_PS4_I_edge.cube \
     050Li3PS4-050LiI_PS4_I_three.cube \
  -iso 1.2e-09

The script assigns colors based on the file name:

Classification	Color
Zero-type	Blue
Corner-type	Green
Edge-type	Red
Three-type	Yellow

The reference PS₄³⁻ tetrahedron is shown with:

Object	Color
P atom	Purple
S atoms	Yellow
P–S bonds	Gray

Output

Each Gaussian cube file contains:

• A reference PS₄³⁻ tetrahedron

  • P atom at the origin
  • Four S atoms in the aligned coordinate system
• A three-dimensional spatial-density field of the selected I⁻ category

The cube files can be visualized using:

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

Notes and Limitations

• The I–S cutoff for classification is fixed at 4.7 Å in the script.
• The cube files represent accumulated spatial-density distributions.
• The current analysis uses the nearest I⁻ ion to define the orientation of each PS₄³⁻ tetrahedron.
• The script searches the 15 nearest I⁻ ions around each P atom when classifying zero-, corner-, edge-, and three-type configurations.
• The output filename is generated from the input trajectory name. The current implementation expects an input filename containing LiI.
• The current trajectory parser is primarily intended for orthorhombic simulation cells.
• The Mayavi visualization requires a GUI-capable Python environment.

License

This repository is intended for academic and research use.