Pymatgen Diffusion Analysis

2025.11.15 · active · verified Fri Apr 17

Pymatgen-analysis-diffusion is an add-on module for the Materials Project's `pymatgen` library, specializing in the analysis of diffusion in solid-state materials. It provides tools for calculating mean squared displacement (MSD), determining diffusion coefficients from ab-initio molecular dynamics (AIMD) simulations, and analyzing diffusion paths. The current version is 2025.11.15, and releases are typically date-based, often aligning with updates to the core `pymatgen` library.

Common errors

```
ImportError: cannot import name 'MSDAnalyzer' from 'pymatgen_analysis_diffusion.aimd.msd'
```
cause Incorrect import path. Users often confuse add-on imports with core pymatgen imports.

fix Use the full package name for imports: `from pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer`
```
ValueError: Need at least two structures!
```
cause The input list of structures provided to `MSDAnalyzer` contains fewer than two structures, which is insufficient to calculate mean squared displacement.

fix Ensure the `structures` list passed to `MSDAnalyzer` contains at least two `pymatgen.core.Structure` objects to represent a trajectory over time.
```
TypeError: 'list' object has no attribute 'get_diffusivity'
```
cause Attempting to call a method like `get_diffusivity` directly on a list of structures, instead of on an instance of `MSDAnalyzer` or `DiffusionAnalyzer`.

fix First, instantiate the analyzer class (e.g., `msd_analyzer = MSDAnalyzer(...)`), then call the method on that instance (e.g., `msd_analyzer.get_diffusivity(...)`).

Warnings

gotcha The `time_step` parameter in `MSDAnalyzer` (and related classes) expects units of picoseconds (ps). Incorrect units will lead to incorrect diffusion coefficients.
Fix: Ensure your `time_step` is accurately converted to picoseconds from your simulation output (e.g., from femtoseconds for most AIMD codes).
gotcha Diffusion analysis, especially for calculating reliable diffusion coefficients, requires sufficiently long simulation trajectories. Very short trajectories will result in large statistical errors and unreliable results.
Fix: Run 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.
gotcha When 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.
Fix: Set `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.
breaking As 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.
Fix: Always 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.

Install

pip install pymatgen-analysis-diffusion Install stable version

Imports

MSDAnalyzer
wrong:
```
from pymatgen.analysis.diffusion.aimd.msd import MSDAnalyzer
```
correct:
```
from pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer
```
MSDAnalyzer is part of the 'pymatgen-analysis-diffusion' package, not directly under 'pymatgen.analysis'.

DiffusionAnalyzer

wrong:

from pymatgen.analysis.diffusion.aimd.diffusion_analyzer import DiffusionAnalyzer

correct:

from pymatgen_analysis_diffusion.aimd.diffusion_analyzer import DiffusionAnalyzer

DiffusionAnalyzer is part of the 'pymatgen-analysis-diffusion' package, not directly under 'pymatgen.analysis'.

Quickstart

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]}")

view raw JSON →