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 uses pymatgen 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

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.

Executable Jupyter notebook tutorials are available in the tutorials/ directory. These are not included when installing via pip — to run them locally, clone the repository:

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

Installation

Standard Installation

pip install site-analysis

For faster polyhedral site analysis and distance calculations, install with numba acceleration:

pip install site-analysis[fast]

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.12 or above.

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for guidelines.

Citation

If you use site-analysis in your research, please cite the paper published in the Journal of Open Source Software:

@article{Morgan2026,
  doi = {10.21105/joss.09606},
  url = {https://doi.org/10.21105/joss.09606},
  year = {2026},
  publisher = {The Open Journal},
  volume = {11},
  number = {122},
  pages = {9606},
  author = {Benjamin J. Morgan},
  title = {site-analysis: A Python package for site-projection analysis of molecular dynamics trajectories},
  journal = {Journal of Open Source Software}
}

To cite the specific version of the software you used, please also cite its release on Zenodo, where each version has its own DOI.