diff --git a/README.org b/README.org index c58e126..09d533c 100644 --- a/README.org +++ b/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 -Li and I spatial probability distributions around =PS4^{3-}= units in -Li2S-P2S5-LiI glass trajectories. +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 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= - - 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. +The generated cube files can be visualized as isosurfaces using Mayavi. -2. =cube2mayavi.py= - - Reads the generated cube file. - - Visualizes the spatial probability density as an isosurface using Mayavi. - - Displays the reference =PS4^{3-}= tetrahedron. +* Workflow -The scripts are intended to analyze the local geometrical relationship -between I^- ions and =PS4^{3-}= units in Li2S-P2S5-LiI glasses. +#+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= | 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. | +| =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, 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 -atom columns: +=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 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 -=PS4^{3-}= unit share the same molecule ID (=mol=). +The script assumes that P and S atoms belonging to the same PS₄³⁻ unit +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. -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. +For every frame in the trajectory, the following procedure is performed. -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. -- A second S atom is used to fix the rotation around the z axis. +** 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 @@ -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. | -| =-cut=, =--cutoff= | Spatial cutoff radius in angstrom. | +| =-m=, =--mesh= | Number of grid points along the x, y, and z directions. | +| =-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, -cutoff radius, and probability-density distribution. It should therefore -be adjusted for each dataset. +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 -The cube files contain: +Each generated cube file contains: -- A reference =PS4^{3-}= tetrahedron: - - P atom at the origin +- A reference PS₄³⁻ tetrahedron + - 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 | -| S | Yellow | -| Li probability density | Blue | -| I probability density | Red | -| P-S bonds | Gray | +| P atom | Purple | +| S atom | Yellow | +| P–S bond | Gray | +| Li⁺ density | Blue | +| 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. -- 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. +- 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 is used in research, please cite the corresponding -publication or presentation describing the Li2S-P2S5-LiI glass analysis. +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 research use. +This repository is intended for academic and research use.