Fix README.org

README.org

@@ -1,49 +1,60 @@
-#+TITLE: Li2S-P2S5-LiI Glass: PS4-Centered Ion Density Analysis
+#+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 contains Python scripts for analyzing and visualizing
+This repository provides Python scripts for analyzing the spatial
-Li and I spatial probability distributions around =PS4^{3-}= units in
+distributions of Li⁺ and I⁻ around PS₄³⁻ tetrahedra in
-Li2S-P2S5-LiI glass trajectories.
+Li₂S–P₂S₅–LiI glass trajectories.
 
-The workflow consists of two steps:
+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.
 
-1. =dump2cube.py=
+The generated cube files can be visualized as isosurfaces using Mayavi.
-   - 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=
+* Workflow
-   - 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
+#+begin_example
-between I^- ions and =PS4^{3-}= units in Li2S-P2S5-LiI glasses.
+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= | Converts a LAMMPS trajectory into Li/I probability-density cube files. |
+| =dump2cube.py= | Reads a LAMMPS trajectory, aligns PS₄³⁻ units, and generates Li⁺/I⁻ cube files. |
-| =cube2mayavi.py= | Visualizes a cube file with Mayavi. |
+| =cube2mayavi.py= | Reads a Gaussian cube file and visualizes the density field using Mayavi. |
-| =050Li3PS4-050LiI.lammpstrj= | Example LAMMPS trajectory. |
+| =050Li3PS4-050LiI.lammpstrj= | Example LAMMPS trajectory for a Li₂S–P₂S₅–LiI glass. |
-| =050Li3PS4-050LiI_PS4_I.cube= | Example I^- probability-density cube file. |
+| =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, depending on the Mayavi installation
+- PyQt5 or PySide6
 
-Example installation using conda:
+Mayavi is most easily installed through conda-forge.
 
 #+begin_src bash
 conda create -n ps4-density python=3.10
@@ -51,49 +62,61 @@ conda activate ps4-density
 conda install -c conda-forge numpy mayavi pyqt
 #+end_src
 
-Alternatively, NumPy can be installed using pip:
+If NumPy is not installed, it can also be installed with 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
+=dump2cube.py= expects a LAMMPS trajectory containing the following atom
-atom columns:
+columns:
 
 #+begin_example
 ITEM: ATOMS id type element mol x y z
 #+end_example
 
-The trajectory must contain at least the following elements:
+The trajectory must contain the following elements:
 
 - Li
 - P
 - S
 - I
 
-The script assumes that P and S atoms belonging to the same
+The script assumes that P and S atoms belonging to the same PS₄³⁻ unit
-=PS4^{3-}= unit share the same molecule ID (=mol=).
+share the same molecule ID (=mol=).
 
-* Analysis Procedure
+The current workflow has been tested primarily for orthorhombic
+simulation cells. Periodic boundary conditions are applied when
+calculating relative atomic positions.
 
-For each trajectory frame:
+* Analysis Method
 
-1. Each P atom is selected as the center of a reference =PS4^{3-}= unit.
+For every frame in the trajectory, the following procedure is performed.
-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:
+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.
 
-- The S atom farthest from the nearest I^- ion is aligned with the z axis.
+** Definition of the reference orientation
-- A second S atom is used to fix the rotation around the z axis.
+
+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
 
@@ -111,17 +134,17 @@ Arguments:
 | Argument | Description |
 |---+---|
 | =-i=, =--trjfile= | Input LAMMPS trajectory file. |
-| =-m=, =--mesh= | Number of grid points in x, y, and z directions. |
+| =-m=, =--mesh= | Number of grid points along the x, y, and z directions. |
-| =-cut=, =--cutoff= | Spatial cutoff radius in angstrom. |
+| =-cut=, =--cutoff= | Cutoff distance around the reference P atom in Å. |
 
-Expected output files:
+For the example above, the expected output files are:
 
 #+begin_example
 050Li3PS4-050LiI_PS4_Li.cube
 050Li3PS4-050LiI_PS4_I.cube
 #+end_example
 
-** Visualize I^- Probability Density
+** Visualize the I⁻ Spatial-Density Field
 
 #+begin_src bash
 python cube2mayavi.py \
@@ -130,7 +153,7 @@ python cube2mayavi.py \
   -iso 1.26483e-09
 #+end_src
 
-** Visualize Li+ Probability Density
+** Visualize the Li⁺ Spatial-Density Field
 
 #+begin_src bash
 python cube2mayavi.py \
@@ -139,56 +162,76 @@ python cube2mayavi.py \
   -iso 1.0e-09
 #+end_src
 
-The appropriate isovalue depends on the trajectory length, mesh size,
+The appropriate isovalue depends on the number of trajectory frames,
-cutoff radius, and probability-density distribution. It should therefore
+the number of PS₄³⁻ units, the mesh size, and the cutoff distance.
-be adjusted for each dataset.
+Therefore, the =-iso= value should be adjusted for each dataset.
 
 * Output
 
-The cube files contain:
+Each generated cube file contains:
 
-- A reference =PS4^{3-}= tetrahedron:
+- A reference PS₄³⁻ tetrahedron
-  - P atom at the origin
+  - One P atom located at the origin
   - Four S atoms in the aligned coordinate system
-- A three-dimensional spatial probability-density field for Li or I
+- A three-dimensional spatial-density field for Li⁺ or I⁻
 
-The cube files can be visualized using:
+The cube files can also be viewed with software supporting Gaussian cube
+format, including:
 
 - Mayavi
 - VMD
-- PyMOL
 - ParaView
-- Other software supporting Gaussian cube files
+- PyMOL
 
-* Visualization Colors
+* Visualization Settings
 
-The default visualization settings in =cube2mayavi.py= are:
+The default colors in =cube2mayavi.py= are:
 
 | Object | Color |
 |---+---|
-| P | Purple |
+| P atom | Purple |
-| S | Yellow |
+| S atom | Yellow |
-| Li probability density | Blue |
+| P–S bond | Gray |
-| I probability density | Red |
+| Li⁺ density | Blue |
-| P-S bonds | Gray |
+| I⁻ density | Red |
 
-* Notes
+For Li⁺ visualization, the script separates the density field into
+an inner region and an outer region:
 
-- The trajectory is treated using periodic boundary conditions.
+- Inner region: within 5 Å of the P atom
-- Coordinates are converted to fractional coordinates before alignment.
+- Outer region: between 5 Å and 9 Å from the P atom
-- The current implementation assumes an orthorhombic simulation box for
+
-  the trajectory parsing procedure.
+* Example Interpretation
-- The script includes a triclinic-cell lattice conversion function, but
+
-  the exact input format should be checked before applying it to
+The I⁻ cube file can be used to examine whether I⁻ ions are distributed
-  triclinic LAMMPS trajectories.
+uniformly around PS₄³⁻ tetrahedra or occupy preferred directions.
-- Large trajectory and cube files can exceed the standard GitHub file-size
+
-  limit. Git LFS is recommended when files are larger than 100 MB.
+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 is used in research, please cite the corresponding
+If this repository contributes to published work, please cite the
-publication or presentation describing the Li2S-P2S5-LiI glass analysis.
+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 research use.
+This repository is intended for academic and research use.