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

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

#+begin_example
s_count = number of S atoms within 4.7 Å from I⁻
#+end_example

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

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

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

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

Alternatively, NumPy can be installed with pip:

#+begin_src bash
pip install numpy
#+end_src

* Input Trajectory Format

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

#+begin_example
ITEM: ATOMS id type element xu yu zu mol
#+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 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

#+begin_src bash
python dump2cube_edge_corner.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= | Spatial cutoff distance around the reference P atom in Å. |

Expected output files:

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

** Visualize Classified I⁻ Density Fields

#+begin_src bash
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
#+end_src

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.