polyhedral-analysis

polyhedral-analysis is a Python module for analysing coordination polyhedra in crystal structures and molecular dynamics trajectories. Built on top of pymatgen, it works with any structure that pymatgen can read.

Features

• Coordination polyhedron construction from distance cutoffs, nearest neighbours, or closest-centre assignment
• Continuous symmetry measures (CSM) against reference geometries (tetrahedron, octahedron, cube, etc.)
• Best-fit geometry identification across all reference polyhedra for a given coordination number
• Bond lengths, angles, volumes, and edge connectivity graphs
• Corner-, edge-, and face-sharing neighbour analysis
• Off-centre displacement and radial distortion parameters
• Vertex vector orientation analysis with orientation distribution plotting
• Trajectory analysis for tracking polyhedral distortions over molecular dynamics runs

Installation

pip install polyhedral-analysis

Requirements

• Python 3.11+
• numpy
• pymatgen >= 2024.7.18
• scipy
• bsym

Quick start

from pymatgen.io.vasp import Poscar
from polyhedral_analysis.configuration import Configuration
from polyhedral_analysis.polyhedra_recipe import PolyhedraRecipe

# Define a recipe for octahedral coordination
recipe = PolyhedraRecipe(
    method='distance cutoff',
    coordination_cutoff=3.0,
    central_atoms='Ti',
    vertex_atoms=['O', 'F'],
)

# Load a structure and build polyhedra
structure = Poscar.from_file('POSCAR').structure
config = Configuration(structure=structure, recipes=[recipe])

# Inspect a polyhedron
poly = config.polyhedra[0]
print(poly.coordination_number)     # 6
print(poly.best_fit_geometry)       # {'geometry': 'Octahedron', 'symmetry_measure': ...}
print(poly.volume)                  # polyhedral volume
print(poly.coordination_distances())  # list of bond lengths

Documentation

Full documentation — including a getting started guide, core concepts, and guides for recipes, symmetry measures, neighbour analysis, and trajectory analysis — is available at polyhedral-analysis.readthedocs.io.