site-analysis 1.2.7

Analysis tools for tracking ion migration through crystallographic sites

site-analysis

site-analysis is a Python module for analysing molecular dynamics simulations of solid-state ion transport, by assigning positions of mobile ions to specific “sites” within the host structure.

The code is built on top of pymatgen and takes VASP XDATCAR files as molecular dynamics trajectory inputs.

The code can use the following definitions for assigning mobile ions to sites:

1. Spherical cutoff: Atoms occupy a site if they lie within a spherical cutoff from a fixed position.
2. Voronoi decomposition: Atoms are assigned to sites based on a Voronoi decomposition of the lattice into discrete volumes.
3. Polyhedral decomposition: Atoms are assigned to sites based on occupation of polyhedra defined by the instantaneous positions of lattice atoms.
4. Dynamic Voronoi sites: Sites using Voronoi decomposition but with centres calculated dynamically based on framework atom positions.

Quick Start

from site_analysis.builders import TrajectoryBuilder
from pymatgen.io.vasp import Xdatcar

# Load MD trajectory from VASP XDATCAR file
# (This example uses the provided example_data/XDATCAR file.
#  For your own analysis, replace with your trajectory file path
#  and adjust the mobile species and site definitions accordingly.)
xdatcar = Xdatcar("example_data/XDATCAR")
md_structures = xdatcar.structures

# Define sites and track Li+ ion movements between them
trajectory = (TrajectoryBuilder()
              .with_structure(md_structures[0])  # Use first frame as reference
              .with_mobile_species("Li")
              .with_spherical_sites(centres=[[0.25, 0.25, 0.25],
                                             [0.75, 0.25, 0.25]],
                                    radii=1.5)
              .build())

trajectory.trajectory_from_structures(md_structures)

# Get site occupancies over time
print(trajectory.atoms_trajectory)  # Which site each atom occupies
print(trajectory.sites_trajectory)  # Which atoms in each site

For detailed examples and tutorials, see the documentation.

Installation

Standard Installation

pip install site-analysis

Development Installation

For development or to access the latest features:

# Clone the repository
git clone https://github.com/bjmorgan/site-analysis.git
cd site-analysis

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Documentation

Complete documentation, including tutorials, examples, and API reference, is available at Read the Docs.

Testing

Automated testing of the latest build happens on GitHub Actions.

To run tests locally:

# Using pytest (recommended)
pytest

# Using unittest
python -m unittest discover

The code requires Python 3.10 or above.