Comparison with pymatgen#

The pymatgen project also has tools capable of calculating the mean-squared displacement and diffusion coefficient from a relevant input. So why should you use kinisi over pymatgen?

The simple answer is that the approach taken by kinisi, which is outlined in the methodology, uses a higher precision approach to estimate the diffusion coefficent and offers an accurate estimate in the variance of the mean-squared displacements and diffusion coefficient from a single simulation.

In this notebook, we will compare the results from pymatgen and kinisi. First we will import the kinisi and pymatgen DiffusionAnalyzer classes.

import numpy as np
from kinisi.analyze import DiffusionAnalyzer as KinisiDiffusionAnalyzer
from pymatgen.analysis.diffusion.analyzer import DiffusionAnalyzer as PymatgenDiffusionAnalyzer
from import Xdatcar

The kinisi.DiffusionAnalyzer API was based on the pymatgen equivalent, therefore, the two take the same inputs and can parse the Xdatcar.structures.

p_params = {'specie': 'Li',
            'time_step': 2.0,
            'step_skip': 50}
xd = Xdatcar('./example_XDATCAR.gz')

We can then run both the pymagten analysis and the kinisi analysis (the pymatgen requires and additional temperature keyword which is not used in this example).

pymatgen_diff = PymatgenDiffusionAnalyzer.from_structures(
    xd.structures, temperature=300, **p_params)
kinisi_diff = KinisiDiffusionAnalyzer.from_pymatgen(
    xd.structures, parser_params=p_params)
Reading Trajectory: 100%|██████████| 140/140 [00:00<00:00, 4585.48it/s]
Getting Displacements: 100%|██████████| 100/100 [00:00<00:00, 17313.95it/s]
Finding Means and Variances: 100%|██████████| 100/100 [00:00<00:00, 222.39it/s]

Now we can plot the mean-squared displacement from each to check agreement, the pymatgen time units are femtoseconds so these are adjusted.

import matplotlib.pyplot as plt
plt.plot(pymatgen_diff.dt / 1000,, label='pymatgen')
plt.plot(kinisi_diff.dt,, label='kinisi')
plt.xlabel('$\Delta t$/ps')

We can see that the results overlap almost entirely.

However, this doesn’t show the benefits for using kinisi over pymatgen. The first benefit is that kinisi will accurately estimate the variance in the observed mean-squared displacements, giving error bars for the above plot.

plt.errorbar(kinisi_diff.dt,, kinisi_diff.msd_std, c='#ff7f0e')
plt.xlabel('$\Delta t$/ps')

The second benefit is that kinisi will estimate the diffusion coefficient with an accurate uncertainty. pymatgen also estimates this uncertainty, however, pymatgen assumes that the data is independent and applies weighted least squares. However, mean-squared displacement observations are inherently dependent (as discussed in the thought experiment in the methodology), so kinisi accounts for this and applied a generalised least squares style approach. This means that the estimated variance in the diffusion coefficient from kinisi is accurate (while, pymatgen will heavily underestimate the value) and given the BLUE nature of the GLS approach, kinisi has a higher probability of determining a value for the diffusion coefficient closer to the true diffusion coefficient.

/home/docs/checkouts/ RuntimeWarning: invalid value encountered in subtract
  df = fun(x) - f0
Likelihood Sampling: 100%|██████████| 1500/1500 [00:01<00:00, 1157.47it/s]
from uncertainties import ufloat
print('D from pymatgen:',
      ufloat(pymatgen_diff.diffusivity, pymatgen_diff.diffusivity_std_dev))
D from pymatgen: (1.33307+/-0.00008)e-05
print('D from kinisi:',
      ufloat(kinisi_diff.D.n, kinisi_diff.D.s))
D from kinisi: (1.50+/-0.05)e-05

The comparison between weighted and generalised least squared estimators will be discussed in full in a future publication covering the methodology of kinisi.