{"id":10111,"library":"pymatgen-analysis-diffusion","title":"Pymatgen Diffusion Analysis","description":"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.","status":"active","version":"2025.11.15","language":"en","source_language":"en","source_url":"https://github.com/materialsvirtuallab/pymatgen-analysis-diffusion","tags":["material-science","solid-state","diffusion","AIMD","pymatgen","computational-materials-science"],"install":[{"cmd":"pip install pymatgen-analysis-diffusion","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for material structures and analysis tools. Requires >=2023.8.15.","package":"pymatgen","optional":false},{"reason":"Numerical operations.","package":"numpy","optional":false},{"reason":"Scientific computing routines.","package":"scipy","optional":false},{"reason":"Utilities for materials science code.","package":"monty","optional":false},{"reason":"Machine learning utilities, possibly for clustering or data processing.","package":"scikit-learn","optional":false}],"imports":[{"note":"MSDAnalyzer is part of the 'pymatgen-analysis-diffusion' package, not directly under 'pymatgen.analysis'.","wrong":"from pymatgen.analysis.diffusion.aimd.msd import MSDAnalyzer","symbol":"MSDAnalyzer","correct":"from pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer"},{"note":"DiffusionAnalyzer is part of the 'pymatgen-analysis-diffusion' package, not directly under 'pymatgen.analysis'.","wrong":"from pymatgen.analysis.diffusion.aimd.diffusion_analyzer import DiffusionAnalyzer","symbol":"DiffusionAnalyzer","correct":"from pymatgen_analysis_diffusion.aimd.diffusion_analyzer import DiffusionAnalyzer"}],"quickstart":{"code":"from pymatgen.core import Structure, Species, Lattice\nfrom pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer\nimport numpy as np\n\n# 1. Create dummy structures to simulate a trajectory\nlattice = Lattice.cubic(10.0)\nspecies_list = [Species(\"Li\"), Species(\"O\")] * 4 # 8 atoms total\n\n# Generate a list of structures for the trajectory\nstructures = []\nfor i in range(5):\n    # Slightly perturb coordinates for each step\n    coords = np.random.rand(8, 3) + i * 0.05 # Simulate some movement\n    s = Structure(lattice, species_list, coords)\n    structures.append(s)\n\n# Define simulation parameters\ntime_step = 2.0  # Time step between structures in picoseconds (ps)\nstep_skip = 1    # Use every step\n\n# 2. Initialize MSDAnalyzer for a specific species (e.g., Li)\nli_species = [Species(\"Li\")]\n\nmsd_analyzer = MSDAnalyzer(\n    structures=structures,\n    species=li_species,\n    time_step=time_step,\n    step_skip=step_skip\n)\n\n# 3. Calculate diffusivity\ntemperature = 300 # Kelvin\ndiffusivity_data = msd_analyzer.get_diffusivity(temperature=temperature, initial_drift_correct=True)\n\nprint(f\"Calculated diffusivity for Li at {temperature}K:\")\nprint(f\"  Diffusivity: {diffusivity_data['diffusivity']:.2e} cm^2/s\")\nprint(f\"  Error: {diffusivity_data['error']:.2e} cm^2/s\")\n\n# Optional: Get MSD data for plotting\n# time_points, msd_values = msd_analyzer.get_msd_plot()\n# print(f\"First 5 MSD values: {msd_values[:5]}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your `time_step` is accurately converted to picoseconds from your simulation output (e.g., from femtoseconds for most AIMD codes).","message":"The `time_step` parameter in `MSDAnalyzer` (and related classes) expects units of picoseconds (ps). Incorrect units will lead to incorrect diffusion coefficients.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (especially across major `pymatgen` releases)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Use the full package name for imports: `from pymatgen_analysis_diffusion.aimd.msd import MSDAnalyzer`","cause":"Incorrect import path. Users often confuse add-on imports with core pymatgen imports.","error":"ImportError: cannot import name 'MSDAnalyzer' from 'pymatgen_analysis_diffusion.aimd.msd'"},{"fix":"Ensure the `structures` list passed to `MSDAnalyzer` contains at least two `pymatgen.core.Structure` objects to represent a trajectory over time.","cause":"The input list of structures provided to `MSDAnalyzer` contains fewer than two structures, which is insufficient to calculate mean squared displacement.","error":"ValueError: Need at least two structures!"},{"fix":"First, instantiate the analyzer class (e.g., `msd_analyzer = MSDAnalyzer(...)`), then call the method on that instance (e.g., `msd_analyzer.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`.","error":"TypeError: 'list' object has no attribute 'get_diffusivity'"}]}