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

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

Load MD trajectory from VASP XDATCAR file

xdatcar = Xdatcar("XDATCAR") md_structures = xdatcar.structures

Define multiple sites and track Li+ ion movements between them

trajectory = (TrajectoryBuilder() .withstructure(mdstructures[0]) # Use first frame as reference .withmobilespecies("Li") .withsphericalsites(centres=[[0.0, 0.0, 0.0], [0.5, 0.5, 0.5], [0.0, 0.5, 0.0]], radii=1.5) .build())

trajectory.trajectoryfromstructures(md_structures)

Get site occupancies over time

print(trajectory.atomstrajectory) # Which site each atom occupies print(trajectory.sitestrajectory) # Which atoms in each site ```

For detailed examples and tutorials, see the documentation.

Installation

Standard Installation

bash pip install site-analysis

Development Installation

For development or to access the latest features:

```bash

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:

```bash

Using pytest (recommended)

pytest

Using unittest

python -m unittest discover ```

The code requires Python 3.10 or above.