Metadata-Version: 2.4
Name: site_analysis
Version: 1.7.0
Summary: Analysis tools for tracking ion migration through crystallographic sites
Author-email: "Benjamin J. Morgan" <b.j.morgan@bath.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://github.com/bjmorgan/site_analysis
Project-URL: Bug Tracker, https://github.com/bjmorgan/site_analysis/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pymatgen
Requires-Dist: tqdm
Requires-Dist: monty
Provides-Extra: fast
Requires-Dist: numba; extra == "fast"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-tqdm; extra == "dev"
Requires-Dist: scipy-stubs; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: nbsphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: numba; extra == "dev"
Dynamic: license-file

# 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)
[![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 operates on molecular dynamics trajectories represented as lists of pymatgen `Structure` objects. Any trajectory source that can produce pymatgen structures can be used as input.

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 as a list of pymatgen Structure objects.
# Here we load from a VASP XDATCAR file, but any source of
# pymatgen Structure objects can be used as input.
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
```

For faster polyhedral site analysis, install with numba acceleration:

```bash
pip install site-analysis[fast]
```

### 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.

## Contributing

Bug reports, feature requests, and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
