https://github.com/bjmorgan/site-analysis
Analysing molecular dynamics simulations of crystalline materials using site occupations
https://github.com/bjmorgan/site-analysis
Last synced: 5 months ago
JSON representation
Analysing molecular dynamics simulations of crystalline materials using site occupations
- Host: GitHub
- URL: https://github.com/bjmorgan/site-analysis
- Owner: bjmorgan
- License: mit
- Created: 2019-07-12T10:41:16.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2026-01-17T13:17:58.000Z (6 months ago)
- Last Synced: 2026-02-15T14:16:11.712Z (5 months ago)
- Language: Python
- Homepage:
- Size: 12.9 MB
- Stars: 18
- Watchers: 0
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# site-analysis
[](https://site-analysis.readthedocs.io/en/latest/?badge=latest)
[](https://badge.fury.io/py/site-analysis)
[](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 “sites” 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.