kinisi.analyze#

This module contains the API classes for kinisi. It is anticipated that this is where the majority of interaction with the package will occur. This module includes:

  • the kinisi.analyze.DiffusionAnalyzer class for MSD and diffusion analysis;

  • the kinisi.analyze.JumpDiffusionAnalyzer class for TMSD and collective diffusion analysis; and

  • the kinisi.analyze.ConductivityAnalyzer class for MSCD and conductivity analysis.

These are all compatible with VASP Xdatcar output files, pymatgen structures and any MD trajectory that the MDAnalysis package can handle.

The kinisi.analyze.DiffusionAnalyzer class enables the analysis of mean-squared displacement and the self-diffusion coefficient.

class kinisi.diffusion_analyzer.DiffusionAnalyzer(delta_t, disp_3d, volume)[source]#

Bases: kinisi.analyzer.Analyzer

The kinisi.analyze.DiffusionAnalyzer class performs analysis of diffusion relationships in materials. This is achieved through the application of a bootstrapping methodology to obtain the most statistically accurate values for mean squared displacement uncertainty and estimating the covariance. The time-dependence of the MSD is then modelled in a generalised least squares fashion to obtain the diffusion coefficient and offset using Markov chain Monte Carlo maximum likelihood sampling.

Parameters
  • delta_t (ndarray) – An array of the timestep values.

  • disp_3d (List[ndarray]) – A list of arrays, where each array has the axes [atom, displacement observation, dimension]. There is one array in the list for each delta_t value. Note: it is necessary to use a list of arrays as the number of observations is not necessary the same at each data point.

  • volume (float) – The volume of the simulation cell.

  • bootstrap_params – The parameters for the kinisi.diffusion.DiffBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

to_dict()[source]#
Return type

dict

Returns

Dictionary description of DiffusionAnalyzer.

classmethod from_dict(my_dict)[source]#

Generate a DiffusionAnalyzer object from a dictionary.

Parameters

my_dict (dict) – The input dictionary.

Return type

DiffusionAnalyzer

Returns

New DiffusionAnalyzer object.

classmethod from_pymatgen(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a DiffusionAnalyzer object from a list or nested list of pymatgen.core.structure.Structure objects.

Parameters
  • trajectory (List[Union[pymatgen.core.structure.Structure, List[pymatgen.core.structure.Structure]]]) – The list or nested list of structures to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a list of pymatgen.core.structure.Structure objects, this should be None. However, if a list of lists is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Dtype trajectory

List[Union[‘pymatgen.core.structure.Structure’, List[‘pymatgen.core.structure.Structure’]]]

Returns

Relevant DiffusionAnalyzer object.

classmethod from_Xdatcar(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a DiffusionAnalyzer object from a single or a list of pymatgen.io.vasp.outputs.Xdatcar objects.

Parameters
  • trajectory (Union[pymatgen.io.vasp.outputs.Xdatcar, List[pymatgen.io.vasp.outputs.Xdatcar]]) – The Xdatcar or list of Xdatcar objects to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a pymatgen.io.vasp.outputs.Xdatcar object, this should be None. However, if a list of pymatgen.io.vasp.outputs.Xdatcar objects is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant DiffusionAnalyzer object.

classmethod from_file(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a DiffusionAnalyzer object from a single or a list of Xdatcar file(s).

Parameters
  • trajectory (Union[str, List[str]]) – The file or list of Xdatcar files to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (Optional[str]) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (Optional[dict]) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant DiffusionAnalyzer object.

classmethod from_universe(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create an DiffusionAnalyzer object from an MDAnalysis.core.universe.Universe object.

Parameters
  • trajectory (MDAnalysis.core.universe.Universe) – The universe to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.MDAnalysisParser object. See the appropriate documention for more guidance on this dictionary.

  • dtype (str) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify that these constitute a series of identical starting points with different random seeds, in which case the dtype should be identical. For a series of consecutive trajectories, please construct the relevant object using MDAnalysis.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant DiffusionAnalyzer object.

diffusion(diffusion_params=None)[source]#

Calculate the diffusion coefficicent using the bootstrap-GLS methodology.

Parameters

diffusion_params (Optional[dict]) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

property msd: numpy.ndarray#

MSD for the input trajectories. Note that this is the bootstrap sampled MSD, not the numerical average from the data.

Type

return

Return type

ndarray

property msd_std: numpy.ndarray#

MSD standard deviations values for the input trajectories.

Type

return

Return type

ndarray

property D: uravu.distribution.Distribution#

Diffusion coefficient distribution.

Type

return

Return type

uravu.distribution.Distribution

property flatchain: numpy.ndarray#

sampling flatchain

Type

return

Return type

ndarray

The kinisi.analyze.JumpDiffusionAnalyzer class allows the study of jump diffusion and the collective motion of particles.

class kinisi.jump_diffusion_analyzer.JumpDiffusionAnalyzer(delta_t, disp_3d, volume)[source]#

Bases: kinisi.analyzer.Analyzer

The kinisi.analyze.JumpDiffusionAnalyzer class performs analysis of collective diffusion relationships in materials. This is achieved through the application of a bootstrapping methodology to obtain the most statistically accurate values for total mean squared displacement uncertainty and covariance. The time-dependence of the TMSD is then modelled in a generalised least squares fashion to obtain the jump diffusion coefficient and offset using Markov chain Monte Carlo maximum likelihood sampling.

Parameters
  • delta_t (ndarray) – An array of the timestep values.

  • disp_3d (List[ndarray]) – A list of arrays, where each array has the axes [atom, displacement observation, dimension]. There is one array in the list for each delta_t value. Note: it is necessary to use a list of arrays as the number of observations is not necessary the same at each data point.

  • volume (float) – The volume of the simulation cell.

  • bootstrap_params – The parameters for the kinisi.diffusion.DiffBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

to_dict()[source]#
Return type

dict

Returns

Dictionary description of JumpDiffusionAnalyzer.

classmethod from_dict(my_dict)[source]#

Generate a DiffusionAnalyzer object from a dictionary.

Parameters

my_dict – The input dictionary.

Return type

JumpDiffusionAnalyzer

Returns

New DiffusionAnalyzer object.

classmethod from_pymatgen(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a JumpDiffusionAnalyzer object from a list or nested list of pymatgen.core.structure.Structure objects.

Parameters
  • trajectory (List[Union[pymatgen.core.structure.Structure, List[pymatgen.core.structure.Structure]]]) – The list or nested list of structures to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a list of pymatgen.core.structure.Structure objects, this should be None. However, if a list of lists is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant JumpDiffusionAnalyzer object.

classmethod from_Xdatcar(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a JumpDiffusionAnalyzer object from a single or a list of pymatgen.io.vasp.outputs.Xdatcar objects.

Parameters
  • trajectory (Union[pymatgen.io.vasp.outputs.Xdatcar, List[pymatgen.io.vasp.outputs.Xdatcar]]) – The Xdatcar or list of Xdatcar objects to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a pymatgen.io.vasp.outputs.Xdatcar object, this should be None. However, if a list of pymatgen.io.vasp.outputs.Xdatcar objects is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant JumpDiffusionAnalyzer object.

classmethod from_file(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create a JumpDiffusionAnalyzer object from a single or a list of Xdatcar file(s).

Parameters
  • trajectory (Union[str, List[str]]) – The file or list of Xdatcar files to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (Optional[str]) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (Optional[dict]) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant JumpDiffusionAnalyzer object.

classmethod from_universe(trajectory, parser_params, dtype=None, bootstrap_params=None)[source]#

Create an JumpDiffusionAnalyzer object from an MDAnalysis.core.universe.Universe object.

Parameters
  • trajectory (MDAnalysis.core.universe.Universe) – The universe to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.MDAnalysisParser object. See the appropriate documention for more guidance on this dictionary.

  • dtype (str) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify that these constitute a series of identical starting points with different random seeds, in which case the dtype should be identical. For a series of consecutive trajectories, please construct the relevant object using MDAnalysis.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

Returns

Relevant JumpDiffusionAnalyzer object.

jump_diffusion(jump_diffusion_params=None)[source]#

Calculate the jump diffusion coefficicent using the bootstrap-GLS methodology.

Parameters

ump_diffusion_params – The parameters for the kinisi.diffusion.TMSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

property tmsd: numpy.ndarray#

TMSD for the input trajectories. Note that this is the bootstrap sampled MSD, not the numerical average from the data.

Type

return

Return type

ndarray

property tmsd_std: numpy.ndarray#

MSD standard deviations values for the input trajectories.

Type

return

Return type

ndarray

property D_J: uravu.distribution.Distribution#

Jump diffusion coefficient

Type

return

Return type

uravu.distribution.Distribution

property flatchain: numpy.ndarray#

sampling flatchain

Type

return

Return type

ndarray

The kinisi.analyze.ConductivityAnalyzer class will allow the conductivity of a material in a simulation to be found, without assuming a Haven ration of 1.

class kinisi.conductivity_analyzer.ConductivityAnalyzer(delta_t, disp_3d, volume)[source]#

Bases: kinisi.analyzer.Analyzer

The kinisi.analyze.ConductivityAnalyzer class performs analysis of conductive relationships in materials. This is achieved through the application of a bootstrapping methodology to obtain the most statistically accurate values for mean squared charge displacement uncertainty and covariance. The time-dependence of the MSCD is then modelled in a generalised least squares fashion to obtain the jump diffusion coefficient and offset using Markov chain Monte Carlo maximum likelihood sampling.

Parameters
  • delta_t (ndarray) – An array of the timestep values.

  • disp_3d (List[ndarray]) – A list of arrays, where each array has the axes [atom, displacement observation, dimension]. There is one array in the list for each delta_t value. Note: it is necessary to use a list of arrays as the number of observations is not necessary the same at each data point.

  • volume (float) – The volume of the simulation cell.

  • bootstrap_params – The parameters for the kinisi.diffusion.DiffBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

  • ionic_charge – The charge on the mobile ions, either an array with a value for each ion or a scalar if all values are the same. Optional, default is 1.

to_dict()[source]#
Return type

dict

Returns

Dictionary description of ConductivityAnalyzer.

classmethod from_dict(my_dict)[source]#

Generate a ConductivityAnalyzer object from a dictionary.

Parameters

my_dict (dict) – The input dictionary.

Return type

ConductivityAnalyzer

Returns

New :py:class`ConductivityAnalyzer` object.

classmethod from_pymatgen(trajectory, parser_params, dtype=None, bootstrap_params=None, ionic_charge=1)[source]#

Create a ConductivityAnalyzer object from a list or nested list of pymatgen.core.structure.Structure objects.

Parameters
  • trajectory (List[Union[pymatgen.core.structure.Structure, List[pymatgen.core.structure.Structure]]]) – The list or nested list of structures to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a list of pymatgen.core.structure.Structure objects, this should be None. However, if a list of lists is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

  • ionic_charge (Union[ndarray, int]) – The charge on the mobile ions, either an array with a value for each ion or a scalar if all values are the same. Optional, default is 1.

Returns

Relevant ConductivityAnalyzer object.

classmethod from_Xdatcar(trajectory, parser_params, dtype=None, bootstrap_params=None, ionic_charge=1)[source]#

Create a ConductivityAnalyzer object from a single or a list of pymatgen.io.vasp.outputs.Xdatcar objects.

Parameters
  • trajectory (Union[pymatgen.io.vasp.outputs.Xdatcar, List[pymatgen.io.vasp.outputs.Xdatcar]]) – The Xdatcar or list of Xdatcar objects to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (str) – If trajectory is a pymatgen.io.vasp.outputs.Xdatcar object, this should be None. However, if a list of pymatgen.io.vasp.outputs.Xdatcar objects is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

  • ionic_charge (Union[ndarray, int]) – The charge on the mobile ions, either an array with a value for each ion or a scalar if all values are the same. Optional, default is 1.

Returns

Relevant ConductivityAnalyzer object.

classmethod from_file(trajectory, parser_params, dtype=None, bootstrap_params=None, ionic_charge=1)[source]#

Create a ConductivityAnalyzer object from a single or a list of Xdatcar file(s).

Parameters
  • trajectory (Union[str, List[str]]) – The file or list of Xdatcar files to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.PymatgenParser object. See the appropriate documentation for more guidance on this dictionary.

  • dtype (Optional[str]) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify if these constitute a series of consecutive trajectories or a series of identical starting points with different random seeds, in which case the dtype should be either consecutive or identical.

  • bootstrap_params (Optional[dict]) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

  • ionic_charge (Union[ndarray, int]) – The charge on the mobile ions, either an array with a value for each ion or a scalar if all values are the same. Optional, default is 1.

Returns

Relevant ConductivityAnalyzer object.

classmethod from_universe(trajectory, parser_params, dtype=None, bootstrap_params=None, ionic_charge=1)[source]#

Create an ConductivityAnalyzer object from an MDAnalysis.core.universe.Universe object.

Parameters
  • trajectory (MDAnalysis.core.universe.Universe) – The universe to be analysed.

  • parser_params (dict) – The parameters for the kinisi.parser.MDAnalysisParser object. See the appropriate documention for more guidance on this dictionary.

  • dtype (str) – If trajectory is a single file, this should be None. However, if a list of files is passed, then it is necessary to identify that these constitute a series of identical starting points with different random seeds, in which case the dtype should be identical. For a series of consecutive trajectories, please construct the relevant object using MDAnalysis.

  • bootstrap_params (dict) – The parameters for the kinisi.diffusion.MSDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters.

  • ionic_charge (Union[ndarray, int]) – The charge on the mobile ions, either an array with a value for each ion or a scalar if all values are the same. Optional, default is 1.

Returns

Relevant ConductivityAnalyzer object.

conductivity(temperature, conductivity_params=None)[source]#

Calculate the jump diffusion coefficicent using the bootstrap-GLS methodology.

Parameters
  • temperature (float) – Simulation temperature in Kelvin

  • conductivity_params (Optional[dict]) – The parameters for the kinisi.diffusion.MSCDBootstrap object. See the appropriate documentation for more guidance on this. Optional, default is the default bootstrap parameters

property mscd: numpy.ndarray#

MSCD for the input trajectories. Note that this is the bootstrap sampled value, not the numerical average from the data.

Type

return

Return type

ndarray

property mscd_std: numpy.ndarray#

MSCD standard deviations values for the input trajectories.

Type

return

Return type

ndarray

property sigma: uravu.distribution.Distribution#

Conductivity, in mS^{1}cm^{-1}.

Type

returns

Return type

uravu.distribution.Distribution

property flatchain: numpy.ndarray#

sampling flatchain

Type

return

Return type

ndarray

This module contains the base class for the different Analyzer objects used by kinisi.

class kinisi.analyzer.Analyzer(delta_t, disp_3d, volume)[source]#

Bases: object

This class is the superclass for the kinisi.analyze.DiffusionAnalyzer, kinisi.analyze.JumpDiffusionAnalyzer and kinisi.analyze.ConductivityAnalyzer classes. Therefore all of the properties here are available to these other classes.

Parameters
  • delta_t (ndarray) – An array of the timestep values.

  • disp_3d (List[ndarray]) – A list of arrays, where each array has the axes [atom, displacement observation, dimension]. There is one array in the list for each delta_t value. Note: it is necessary to use a list of arrays as the number of observations is not necessary the same at each data point.

  • volume (float) – The volume of the simulation cell.

save(filename)[source]#

Save the Analyzer object as a HDF5 file.

Parameters

filename (str) – Name for the file, no file extension is required and if one if given it is replaced with .hdf.

classmethod load(filename)[source]#

Load the Analyzer object from an HDF5 file.

Parameters

filename (str) – Name for the file, any file extension will be replaced with .hdf.

Return type

Analyzer

Returns

An Analyzer object from the file.

to_dict()[source]#
Return type

dict

Returns

Dictionary description of Analyzer.

classmethod from_dict(my_dict)[source]#

Generate an Analyzer object from a dictionary.

Parameters

my_dict (dict) – The input dictionary.

Return type

Analyzer

Returns

New Analyzer object.

property distribution: numpy.ndarray#

A distribution of samples for the linear relationship that can be used for easy plotting of credible intervals.

Type

return

Return type

ndarray

property dt: numpy.ndarray#

Timestep values that have been sampled.

Type

return

Return type

ndarray

property dr: List[uravu.distribution.Distribution]#

A list of uravu.distribution.Distribution objects that describe the euclidian displacement at each dt.

Type

return

Return type

List[uravu.distribution.Distribution]

property ngp_max: float#

Position in dt where the non-Gaussian parameter is maximised.

Type

return

Return type

float

property intercept: uravu.distribution.Distribution#

The distribution describing the intercept.

Type

return

Return type

uravu.distribution.Distribution

property volume: float#

Volume of system, in cubic angstrom.

Type

return

Return type

float