#+TITLE: PS₄³⁻-Centered Li⁺/I⁻ Spatial Density Analysis in Li₂S–P₂S₅–LiI Glasses
#+AUTHOR: Minami Sakuma
#+OPTIONS: toc:2 num:nil

* Overview

This repository provides Python scripts for analyzing the spatial
distributions of Li⁺ and I⁻ around PS₄³⁻ tetrahedra in
Li₂S–P₂S₅–LiI glass trajectories.

The workflow aligns individual PS₄³⁻ units into a common reference frame,
accumulates the positions of nearby Li⁺ ions and I⁻ ions, and exports
three-dimensional spatial-density fields in Gaussian cube format.

The generated cube files can be visualized as isosurfaces using Mayavi.

* Workflow

#+begin_example
LAMMPS trajectory
      |
      v
dump2cube.py
      |
      +-- PS₄_Li.cube : Li⁺ spatial-density field
      |
      +-- PS₄_I.cube  : I⁻ spatial-density field
      |
      v
cube2mayavi.py
      |
      v
3D isosurface visualization
#+end_example

* Files

| File | Description |
|---+---|
| =dump2cube.py= | Reads a LAMMPS trajectory, aligns PS₄³⁻ units, and generates Li⁺/I⁻ cube files. |
| =cube2mayavi.py= | Reads a Gaussian cube file and visualizes the density field using Mayavi. |
| =050Li3PS4-050LiI.lammpstrj= | Example LAMMPS trajectory for a Li₂S–P₂S₅–LiI glass. |
| =050Li3PS4-050LiI_PS4_I.cube= | Example cube file containing the I⁻ spatial-density field. |

* Requirements

** Python packages

The scripts require Python 3 and the following packages:

- NumPy
- Mayavi
- VTK
- Traits
- PyQt5 or PySide6

Mayavi is most easily installed through conda-forge.

#+begin_src bash
conda create -n ps4-density python=3.10
conda activate ps4-density
conda install -c conda-forge numpy mayavi pyqt
#+end_src

If NumPy is not installed, it can also be installed with pip.

#+begin_src bash
pip install numpy
#+end_src

* Input Trajectory Format

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

#+begin_example
ITEM: ATOMS id type element mol x y z
#+end_example

The trajectory must contain the following elements:

- Li
- P
- S
- I

The script assumes that P and S atoms belonging to the same PS₄³⁻ unit
share the same molecule ID (=mol=).

The current workflow has been tested primarily for orthorhombic
simulation cells. Periodic boundary conditions are applied when
calculating relative atomic positions.

* Analysis Method

For every frame in the trajectory, the following procedure is performed.

1. Each P atom is selected as the center of a reference PS₄³⁻ tetrahedron.
2. The four nearest I⁻ ions around the selected P atom are identified.
3. The nearest I⁻ ion is used to define the orientation of the PS₄³⁻ unit.
4. The four S atoms belonging to the PS₄³⁻ unit are rotated into a common
   reference coordinate system.
5. Li⁺ ions within the specified cutoff distance from P are collected.
6. The four nearest I⁻ ions are collected.
7. The accumulated Li⁺ and I⁻ positions are converted into
   three-dimensional histograms.
8. The histograms are exported in Gaussian cube format.

** Definition of the reference orientation

The PS₄³⁻ tetrahedron is aligned using the nearest I⁻ ion.

- The S atom farthest from the nearest I⁻ ion is aligned with the z axis.
- A second S atom is used to define the rotation around the z axis.
- The P atom is placed at the origin.

This alignment enables the spatial distributions of Li⁺ and I⁻ around
many PS₄³⁻ units and trajectory frames to be accumulated in a common
coordinate system.

* Usage

** Generate Cube Files

#+begin_src bash
python dump2cube.py \
  -i 050Li3PS4-050LiI.lammpstrj \
  -m 160 160 160 \
  -cut 8
#+end_src

Arguments:

| Argument | Description |
|---+---|
| =-i=, =--trjfile= | Input LAMMPS trajectory file. |
| =-m=, =--mesh= | Number of grid points along the x, y, and z directions. |
| =-cut=, =--cutoff= | Cutoff distance around the reference P atom in Å. |

For the example above, the expected output files are:

#+begin_example
050Li3PS4-050LiI_PS4_Li.cube
050Li3PS4-050LiI_PS4_I.cube
#+end_example

** Visualize the I⁻ Spatial-Density Field

#+begin_src bash
python cube2mayavi.py \
  -i 050Li3PS4-050LiI_PS4_I.cube \
  -atom I \
  -iso 1.26483e-09
#+end_src

** Visualize the Li⁺ Spatial-Density Field

#+begin_src bash
python cube2mayavi.py \
  -i 050Li3PS4-050LiI_PS4_Li.cube \
  -atom Li \
  -iso 1.0e-09
#+end_src

The appropriate isovalue depends on the number of trajectory frames,
the number of PS₄³⁻ units, the mesh size, and the cutoff distance.
Therefore, the =-iso= value should be adjusted for each dataset.

* Output

Each generated cube file contains:

- A reference PS₄³⁻ tetrahedron
  - One P atom located at the origin
  - Four S atoms in the aligned coordinate system
- A three-dimensional spatial-density field for Li⁺ or I⁻

The cube files can also be viewed with software supporting Gaussian cube
format, including:

- Mayavi
- VMD
- ParaView
- PyMOL

* Visualization Settings

The default colors in =cube2mayavi.py= are:

| Object | Color |
|---+---|
| P atom | Purple |
| S atom | Yellow |
| P–S bond | Gray |
| Li⁺ density | Blue |
| I⁻ density | Red |

For Li⁺ visualization, the script separates the density field into
an inner region and an outer region:

- Inner region: within 5 Å of the P atom
- Outer region: between 5 Å and 9 Å from the P atom

* Example Interpretation

The I⁻ cube file can be used to examine whether I⁻ ions are distributed
uniformly around PS₄³⁻ tetrahedra or occupy preferred directions.

An anisotropic I⁻ density distribution indicates that I⁻ ions form
characteristic local geometries relative to PS₄³⁻ units rather than being
randomly distributed in the glass network.

* Notes and Limitations

- The input trajectory must include =id type element mol x y z= columns.
- The P and S atoms of a PS₄³⁻ tetrahedron must have the same molecule ID.
- The cube field is generated from accumulated histogram counts and is
  intended for relative spatial-distribution analysis.
- The output file name is generated from the input trajectory name.
  The current implementation expects a filename containing =LiI=.
- Large trajectory and cube files may exceed GitHub's 100 MB file-size
  limit. Git LFS is recommended for large files.
- The visualization script opens an interactive Mayavi window. A GUI-capable
  Python environment is required.
- Before use, confirm that the trajectory format and simulation-cell
  definition are compatible with the parser implemented in =dump2cube.py=.

* Citation

If this repository contributes to published work, please cite the
corresponding paper, poster, presentation, or dataset describing the
Li₂S–P₂S₅–LiI glass simulations and PS₄³⁻-centered spatial-density
analysis.

* License

This repository is intended for academic and research use.
