#+TITLE: Li2S-P2S5-LiI Glass: PS4-Centered Ion Density Analysis
#+AUTHOR: Minami Sakuma
#+OPTIONS: toc:2 num:nil

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

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

Alternatively, NumPy can be installed using pip:

#+begin_src bash
pip install numpy
#+end_src

Mayavi installation is generally more stable with conda-forge.

* Input Trajectory Format

=dump2cube.py= assumes 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 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

#+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 in x, y, and z directions. |
| =-cut=, =--cutoff= | Spatial cutoff radius in angstrom. |

Expected output files:

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

** Visualize I^- Probability Density

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

** Visualize Li+ Probability Density

#+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 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.