site-analysis 1.2.6
Analysis tools for tracking ion migration through crystallographic sites
Requires Python: >=3.10

# site-analysis

<img src='https://github.com/bjmorgan/site-analysis/blob/main/logo/site-analysis-logo.png' width='180'>

![Build Status](https://github.com/bjmorgan/site-analysis/actions/workflows/build.yml/badge.svg)
[![Coverage Status](https://coveralls.io/repos/github/bjmorgan/site-analysis/badge.svg?branch=main)](https://coveralls.io/github/bjmorgan/site-analysis?branch=main)
[![Documentation Status](https://readthedocs.org/projects/site-analysis/badge/?version=latest)](https://site-analysis.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://badge.fury.io/py/site-analysis.svg)](https://badge.fury.io/py/site-analysis)
[![status](https://joss.theoj.org/papers/0a447aeb167964e77c8d381f7d1db89a/status.svg)](https://joss.theoj.org/papers/0a447aeb167964e77c8d381f7d1db89a)

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

The code is built on top of [`pymatgen`](https://pymatgen.org) 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
# (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](https://site-analysis.readthedocs.io/en/latest/).

## 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](https://site-analysis.readthedocs.io/en/latest/).

## Testing

Automated testing of the latest build happens on [GitHub Actions](https://github.com/bjmorgan/site-analysis/actions).

To run tests locally:

```bash
# Using pytest (recommended)
pytest

# Using unittest
python -m unittest discover
```

The code requires Python 3.10 or above.