Metadata-Version: 2.4
Name: site_analysis
Version: 1.8.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.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pymatgen-core
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"
Requires-Dist: pymatgen; 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 uses [`pymatgen`](https://pymatgen.org) `Structure` objects as its input format for MD trajectories. 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/).

Executable Jupyter notebook tutorials are available in the [`tutorials/`](https://github.com/bjmorgan/site-analysis/tree/main/tutorials) directory. These are not included when installing via `pip` — to run them locally, clone the repository:

```bash
git clone https://github.com/bjmorgan/site-analysis.git
cd site-analysis/tutorials
jupyter notebook
```

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