bjmorgan / kinisi

A Python package for estimating diffusion properties from molecular dynamics simulations.

Pronunciation: kee-nee-see

kinisi is an open-source package focussed on accurately quantifying the uncertainty in atomic and molecular displacements, and using this to more completely understand diffusion in materials.

Installation

kinisi is available from the PyPI repository so can be installed using pip or alternatively clone this repository and install the latest development build with the commands below.

pip install .

Contributing

If you would like to contribute to kinisi, have a look at the CONTRIBUTING.md that outlines the different ways to help out.

kinisi's Issues

Use the `uncertainties` package for some data storage

Given that there is a Gaussian assumption throughout, this is possibly a better solution than uravu.

Remove draft_pdf action

Now that the paper has been accepted, we should remove the draft pdf GitHub action.

Documentation rendering badly

I think there has been an update to the theme that we use cause the docs are looking bad now (see double figure on the homepage).

Make `random_state` object a class variable

This is particularly important in the diffusion module where it is being passed about a lot.

Subtract drift/center of mass during MSD calculation

Hello,

What do you think, is subtracting the drift of the entire system a necessary feature when calculating MSD? Seems to be an important step for the non-periodic systems, but not sure about 3D periodicity. It was somehow implemented in pymatgen's analyzer (using center of the geometry of a non-mobile framework ions) and maybe you can add similar feature in your package

Use `class_methods` to support different file types

Currently, there is a dtype keyword to identify which file type should be read in. This would be more clear on the code side if class_methods were used.

Error bars in the docs

It would be nice to update the pymatgen docs page so that the “error bars” plot notes the distinction between the expected variance in the observed MSD and the posterior predictive MSD distribution.

Remove memory limit limitation by refactoring

By calculating the mean-squared displacement and variance when the displacements are found instead of storing this data will remove the memory limitation. However, this requires careful thought such that the bootstrapping can still be performed if desired.

Diffusion coefficient Units

Hello,

Please let me confirm, that the units for diffusion coefficient are cm^2/s if we extract the data from XDATCAR from VASP MD simulations.
If I compare the diffusion coefficient with VASPKIT data (which generates in terms of cm^2/s), then it seems that kinsi produces D in units of m^2/s or vice versa. Below, I provide the value of D from VASPKIT and KINSI at similar temperature:
VASPKIT: 0.1012E-04
KINSI: 9.795032526434394e-09

Thankyou!

Support for ASE trajectory objects

Any plans to support ASE trajectory objects in the parsing functionality? https://wiki.fysik.dtu.dk/ase/ase/io/trajectory.html#trajectory

In principle, you can get at it from pymatgen.io.ase.AseAtomsAdaptor and then work with the pymatgen parser, but that can be quite a large computational overhead.

If it's not something you've considered, is it something you'd be interested in a contribution for?

Adding a diff.save() method to save the whole DiffusionAnalyzer object

This would be very useful to then post-process soundly.

Compatibility with Pymatgen in documentation

There is some compatility issue with pymatgen in documentation page:
https://kinisi.readthedocs.io/en/latest/pymatgen.html

I'm using pymatgen 2023.10.11

ModuleNotFoundError: No module named 'pymatgen.analysis.diffusion'

Put "Methodology" to the main page

There is a very good description of methodology "https://kinisi.readthedocs.io/en/latest/methodology.html", however it's hidden in the documentation. It would be nice if it can be easily accessible from the main page.

Move to using a pyproject.toml

The setup_requires in setup.py is deprecated and should be replaced with a pyproject.toml

Add support for `pint` for units

Add instruction for building the documentation

Please add instructions showing how to build the documentation. It looks like the Makefile under the doc is not working properly.

make html
Running Sphinx v7.2.6

Extension error:
Could not import extension sphinx_autodoc_typehints (exception: No module named 'sphinx_autodoc_typehints')
make: *** [Makefile:19: html] Error 2

Enable plotting of corner plots

It would be nice to return an object that can be passed to a corner plot for visualisation.

Reproducibility of jupyter notebook example

I just run the Notebook examples, and I found the number I got is slightly different compared to the number shown on documentation webpage. I assume this is normal right? If so, please indicate there will be some differences when rerun the notebook examples.

One of the example is on https://kinisi.readthedocs.io/en/latest/vasp_dj.html

diff.D_J.n, diff.D_J.con_int()

I got

(1.423210688465144e-05, array([1.60546798e-06, 2.96878163e-05]))

on the webpage the results are:

(1.4064382415055966e-05, array([1.54355335e-06, 2.96839782e-05]))

[Feature Request] MSD/Diffusion calculation in the x,y, and z direction

Hi Drew (@arm61),
We have a case where we would like to investigate the isotropic/anisotropic diffusion coefficient. I wonder if it is possible to implement such feature in the kinisi?
Cheers,
Pezhman

Use of max(NGP) in docs can encourage poor practice.

The docs talk about using the maximum in the non-Gaussian parameter as an indicator of "the start of the diffusive regime". e.g., https://kinisi.readthedocs.io/en/latest/vasp_dj.html.
This is not necessarily the case, and can encourage users to blindly use the max(NGP) as the start of their fitting regime, withouth looking at their data.
I suggest we revise the docs so that we do not imply that max(NGP) can always be used as a sensible fitting start-point.

Support a list of `Xdatcar` objects

Currently a list of strings pointing to files that can be read by pymatgen.Xdatcar can be parsed with the dtype='IdenticalXdatcar flag. However, it would be nicer to allow the user to pre-read the files.

No support for NPT simulations

Currently, kinisi only supports NVT simulations (because in the parser just the first lattice parameters are used). It should be a pretty straightforward fix.

Include the ability to calculate a centre of geometry mean-squared displacement

Currently, if you want to calculate the MSD for a molecule, there is a lot of gymnastics involving MDAnalysis to get here. This could be greatly simplified for the user by allowing a centre of geometry/mass calculation within kinisi (before the displacements are determined.

I think this would look best as something like

specie=[('C', 'O1', 'O2')]

For a CO₂ molecule, i.e., the tuple defines the molecule that the centre of geometry/mass should be found over.

This should probably wait for the conclusion of #30 as it should also work for indices.

Add the ability to define `indices` for the atoms to be analysed

Currently, the specie of an atom to be analysed can be defined (which is converted to an index internally). It would be useful to allow a user to define the indices themselves.

The potential pitfall is that the user maybe (accidentally) define a single index or only a handful of indices leading to extremely large error bars, therefore good documentation is a must.

misleading doc string

    def save(self, filename: str):
        """
        Save the Analyzer object as a HDF5 file.

        :param filename: Name for the file, no file extension is required and if one if given it is replaced with .hdf.
        """

This doc strings is explicit in saying no extension is required, but if .hdf is not given, it errors out. I considered pushing a fix but then was not sure what the intended behaviour is.

suggestion for CONTRIBUTING.md

Here:

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::

    $ mkvirtualenv kinisi
    $ cd kinisi/
    $ python setup.py develop

I couldn't find the setup.py (is it because I use conda instead of mkvirtualenv?), I guess it shall be installed in this way

pip install .[dev]

Implementation of ase's parser (instead of pymatgen's one)

Hello,

I highly recommend switching to ase.io.read method for reading trajectories instead of pymatgen's Xdatcar. It is an order of magnitude faster for relatively long trajectories (~100,000 ionic steps) in comparison to pymatgen.