Registry /
data / pymatgen-analysis-diffusion
Install & Compatibility
Where this runs
tested against v2025.11.15 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 29.8s · import 0.000s · 593MB
633MB installed
● package 633MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MSDAnalyzer
✓ from pymatgen.analysis.diffusion.aimd.msd import MSDAnalyzer
✗ from pymatgen.analysis.diffusion.aimd.msd import MSDAnalyzer
This quickstart demonstrates how to use `MSDAnalyzer` to calculate the diffusivity of a species from a list of `pymatgen.core.Structure` objects representing a trajectory. It creates a mock trajectory, initializes the analyzer, and then computes the diffusion coefficient.
from pymatgen.core import Structure, Species, Lattice
from pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer
import numpy as np
# 1. Create dummy structures to simulate a trajectory
lattice = Lattice.cubic(10.0)
species_list = [Species("Li"), Species("O")] * 4 # 8 atoms total
# Generate a list of structures for the trajectory
structures = []
for i in range(5):
# Slightly perturb coordinates for each step
coords = np.random.rand(8, 3) + i * 0.05 # Simulate some movement
s = Structure(lattice, species_list, coords)
structures.append(s)
# Define simulation parameters
time_step = 2.0 # Time step between structures in picoseconds (ps)
step_skip = 1 # Use every step
# 2. Initialize MSDAnalyzer for a specific species (e.g., Li)
li_species = [Species("Li")]
msd_analyzer = MSDAnalyzer(
structures=structures,
species=li_species,
time_step=time_step,
step_skip=step_skip
)
# 3. Calculate diffusivity
temperature = 300 # Kelvin
diffusivity_data = msd_analyzer.get_diffusivity(temperature=temperature, initial_drift_correct=True)
print(f"Calculated diffusivity for Li at {temperature}K:")
print(f" Diffusivity: {diffusivity_data['diffusivity']:.2e} cm^2/s")
print(f" Error: {diffusivity_data['error']:.2e} cm^2/s")
# Optional: Get MSD data for plotting
# time_points, msd_values = msd_analyzer.get_msd_plot()
# print(f"First 5 MSD values: {msd_values[:5]}")
Debug
Known issues
gotchaThe `time_step` parameter in `MSDAnalyzer` (and related classes) expects units of picoseconds (ps). Incorrect units will lead to incorrect diffusion coefficients.fixEnsure your `time_step` is accurately converted to picoseconds from your simulation output (e.g., from femtoseconds for most AIMD codes).
affects: All versions
gotchaDiffusion analysis, especially for calculating reliable diffusion coefficients, requires sufficiently long simulation trajectories. Very short trajectories will result in large statistical errors and unreliable results.fixRun AIMD simulations for a sufficient duration (typically hundreds of picoseconds to nanoseconds, depending on material and temperature) to obtain converged MSD curves and robust diffusion coefficients.
affects: All versions
gotchaWhen analyzing AIMD trajectories, system-wide drift (e.g., center of mass motion) can artificially inflate Mean Squared Displacement (MSD) values. The `MSDAnalyzer` offers an `initial_drift_correct` option.fixSet `initial_drift_correct=True` (which is the default in recent versions) when initializing `MSDAnalyzer` or calling `get_diffusivity` if your trajectory might suffer from system drift. This corrects for the initial drift of the center of mass.
affects: All versions
breakingAs an add-on to `pymatgen`, this library is subject to breaking changes in its API if the underlying `pymatgen` objects (e.g., `Structure`, `Trajectory`) or their methods change significantly. Compatibility with `pymatgen` versions is crucial.fixAlways check the `requires-python` and `dependencies` in `pyproject.toml` or `setup.py` for the exact `pymatgen` version range supported. Update both `pymatgen` and `pymatgen-analysis-diffusion` in tandem, and review `pymatgen`'s release notes for breaking changes that might affect data structures passed to diffusion analysis.
affects: All versions (especially across major `pymatgen` releases)
Upgrade
Version history
2025.11.15latest on PyPI · released Nov 14, 2025
Audit
Dependencies
pymatgenrequiredCore dependency for material structures and analysis tools. Requires >=2023.8.15.
numpyrequiredNumerical operations.
scipyrequiredScientific computing routines.
montyrequiredUtilities for materials science code.
scikit-learnrequiredMachine learning utilities, possibly for clustering or data processing.