Registry / data / pymatgen-analysis-diffusion

pymatgen-analysis-diffusion

JSON →
library2025.11.15pypypiunverified

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.

pip install pymatgen-analysis-diffusion
INSTALL
IMPORT
SIG · PYMATGEN-ANALYSIS-
P
pymatgen-analysis-diffusion
datapythonv2025.11.15
Install
29.8s avg
Import
Disk
633MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
build_error
glibc
py 3.103.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.
fix
Ensure 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.
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.
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.
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.
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.
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.
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.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
pymatgen-analysis-diffusion — pip install pymatgen-analysis-diffusion · libregistry