kinisi.diffusion#

The modules is focused on tools for the evaluation of the mean squared displacement and resulting diffusion coefficient from a material.

class kinisi.diffusion.Bootstrap(delta_t, disp_3d, sub_sample_dt=1, progress=True)[source]#

Bases: object

The top-level class for bootstrapping.

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.

  • sub_sample_dt (int) – The frequency in observations to be sampled. Optional, default is 1 (every observation).

  • progress (bool) – Show tqdm progress for sampling. Optional, default is True.

to_dict()[source]#
Return type

dict

Returns

Dictionary description of the Bootstrap.

classmethod from_dict(my_dict)[source]#

Generate a Bootstrap object from a dictionary.

Parameters

my_dict (dict) – The input dictionary.

Return type

Bootstrap

Returns

New :py:class`Bootstrap` object.

property dt: numpy.ndarray#

Timestep values that were resampled.

Type

return

Return type

ndarray

property n: numpy.ndarray#

The mean MSD/TMSD/MSCD, as determined from the bootstrap resampling process, in units Å:sup:2.

Type

return

Return type

ndarray

property s: numpy.ndarray#

The MSD/TMSD/MSCD standard deviation, as determined from the bootstrap resampling process, in units Å:sup:2.

Type

return

Return type

ndarray

property v: numpy.ndarray#

The MSD/TMSD/MSCD variance as determined from the bootstrap resampling process, in units Å:sup:4.

Type

return

Return type

ndarray

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

Displacements between particles at each dt.

Type

return

Return type

List[Distribution]

property ngp: numpy.ndarray#

Non-Gaussian parameter as a function of dt.

Type

return

Return type

ndarray

property n_i: numpy.ndarray#

The number of independent trajectories as a function of dt.

Type

return

Return type

ndarray

property intercept: Optional[uravu.distribution.Distribution]#

The estimated intercept. Note that if fit_intercept is False is the relavent method call, then this is None

Type

return

Return type

Optional[Distribution]

property covariance_matrix: numpy.ndarray#

The covariance matrix for the trajectories.

Type

return

Return type

ndarray

static iterator(progress, loop)[source]#

Get the iteration object, using tqdm as appropriate.

Parameters
  • progress (bool) – Should tqdm be used to give a progress bar.

  • loop (Union[list, range]) – The object that should be looped over.

Return type

Union[tqdm, range]

Returns

Iterator object.

static sample_until_normal(array, n_samples, n_resamples, max_resamples, alpha=0.001, random_state=None)[source]#

Resample from the distribution until a normal distribution is obtained or a maximum is reached.

Args: :type array: ndarray :param array: The array to sample from. :type n_samples: int :param n_samples: Number of samples. :param r_resamples: Number of resamples to perform initially. :type max_resamples: int :param max_resamples: The maximum number of resamples to perform. :type alpha: float :param alpha: Level that p-value should be below in scipy.stats.normaltest() for the distribution

to be normal. Optional, default is 1e-3.

Parameters

random_state (Optional[RandomState]) – A RandomState object to be used to ensure reproducibility. Optional, default is None.

Return type

Distribution

Returns

The resampled distribution.

static n_samples(disp_shape, max_obs)[source]#

Calculate the maximum number of independent observations.

Parameters
  • disp_shape: – The shape of the displacements array.

  • max_obs (int) – The maximum number of observations for the trajectory.

Return type

int

Returns

Maximum number of independent observations.

static ngp_calculation(d_squared)[source]#

Determine the non-Gaussian parameter, from S. Song et al, “Transport dynamics of complex fluids” (2019): 10.1073/pnas.1900239116

Parameters

d_squared (ndarray) – Squared displacement values.

Return type

float

Returns

Value of non-Gaussian parameter.

bootstrap_GLS(use_ngp=False, dt_skip=0, fit_intercept=True, n_samples=1000, n_walkers=32, n_burn=500, progress=True, random_state=None)[source]#

Use the covariance matrix estimated from the resampled values to estimate the gradient and intercept using a generalised least squares approach.

Parameters
  • use_ngp (bool) – Should the ngp max be used as the starting point for the diffusion fitting. Optional, default is False.

  • dt_skip (float) – Values of dt that should be skipped, i.e. where the atoms are not diffusing. Note that if use_ngp is True this will be ignored. Optional, defaults to 0.

  • fit_intercept (bool) – Should the intercept of the diffusion relationship be fit. Optional, default is True.

  • n_samples (int) – Number of samples of the Gaussian process to perform. Optional, default is 1000.

  • n_walkers (int) – Number of MCMC walkers to use. Optional, default is 32.

  • n_burn (int) – Number of burn in samples (these allow the sampling to settle). Optional, default is 500.

  • rtol – The relative threshold term for the covariance matrix inversion. If you obtain a very unusual value for the diffusion coefficient, it is recommended to increase this value (ideally iteratively). Optional, default is N * eps, where eps is the machine precision value of the covariance matrix content.

  • progress (bool) – Show tqdm progress for sampling. Optional, default is True.

  • random_state (Optional[RandomState]) – A RandomState object to be used to ensure reproducibility. Optional, default is None.

static populate_covariance_matrix(variances, n_samples)[source]#

Populate the covariance matrix for the generalised least squares methodology.

Parameters
  • variances (ndarray) – The variances for each timestep

  • n_samples (ndarray) – Number of independent trajectories for each timestep

Return type

ndarray

Returns

An estimated covariance matrix for the system

diffusion(**kwargs)[source]#

Use the bootstrap-GLS method to determine the diffusivity for the system. Keyword arguments will be passed of the bootstrap_GLS() method.

property D: Optional[uravu.distribution.Distribution]#

An alias for the diffusion coefficient Distribution.

Return type

Optional[Distribution]

Returns

Diffusion coefficient, with units of cm:sup:2`s:sup:-1`.

jump_diffusion(**kwargs)[source]#

Use the bootstrap-GLS method to determine the jump diffusivity for the system. Keyword arguments will be passed of the bootstrap_GLS() method.

property D_J: Optional[uravu.distribution.Distribution]#

Alias for the jump diffusion coefficient Distribution.

Return type

Optional[Distribution]

Returns

Jump diffusion coefficient, with units of cm:sup:2`s:sup:-1`.

conductivity(temperature, volume, **kwargs)[source]#

Use the bootstrap-GLS method to determine the ionic conductivity for the system, in units of mScm:sup:-1. Keyword arguments will be passed of the bootstrap_GLS() method.

Parameters
  • temperature (float) – System temperature, in Kelvin.

  • volume (float) – System volume, in Å^{3}.

property sigma: Optional[uravu.distribution.Distribution]#

The estimated conductivity, based on the generalised least squares approach, with units mScm:sup:-1.

Type

return

Return type

Optional[Distribution]

class kinisi.diffusion.MSDBootstrap(delta_t, disp_3d, sub_sample_dt=1, n_resamples=1000, max_resamples=10000, dimension='xyz', alpha=0.001, random_state=None, progress=True)[source]#

Bases: kinisi.diffusion.Bootstrap

Perform a bootstrap resampling to obtain accurate estimates for the mean and uncertainty for the mean squared displacements.

Parameters
  • delta_t (ndarray) – An array of the timestep values, units of ps

  • 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.

  • sub_sample_dt (int) – The frequency in observations to be sampled. Default is 1 (every observation)

  • n_resamples (int) – The initial number of resamples to be performed. Default is 1000

  • max_resamples (int) – The max number of resamples to be performed by the distribution is assumed to be normal. This is present to allow user control over the time taken for the resampling to occur. Default is 100000

  • dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

  • alpha (float) – Value that p-value for the normal test must be greater than to accept. Default is 1e-3

:param random_stateA RandomState object to be used to ensure reproducibility. Default

is None

Parameters

progress (bool) – Show tqdm progress for sampling. Default is True

class kinisi.diffusion.TMSDBootstrap(delta_t, disp_3d, sub_sample_dt=1, n_resamples=1000, max_resamples=10000, dimension='xyz', alpha=0.001, random_state=None, progress=True)[source]#

Bases: kinisi.diffusion.Bootstrap

Perform a bootstrap resampling to obtain accurate estimates for the mean and uncertainty for the total mean squared displacements.

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.

  • sub_sample_dt (int) – The frequency in observations to be sampled. Optional, default is 1 (every observation)

  • n_resamples (int) – The initial number of resamples to be performed. Optional, default is 1000

  • max_resamples (int) – The max number of resamples to be performed by the distribution is assumed to be normal. This is present to allow user control over the time taken for the resampling to occur. Optional, default is 100000

  • dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

  • alpha (float) – Value that p-value for the normal test must be greater than to accept. Optional, default is 1e-3

:param random_stateA RandomState object to be used to ensure reproducibility. Optional,

default is None

Parameters

progress (bool) – Show tqdm progress for sampling. Optional, default is True

class kinisi.diffusion.MSCDBootstrap(delta_t, disp_3d, ionic_charge, sub_sample_dt=1, n_resamples=1000, max_resamples=10000, dimension='xyz', alpha=0.001, random_state=None, progress=True)[source]#

Bases: kinisi.diffusion.Bootstrap

Perform a bootstrap resampling to obtain accurate estimates for the mean and uncertainty for the mean squared charge displacements.

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.

  • 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.

  • sub_sample_dt (int) – The frequency in observations to be sampled. Optional, default is 1 (every observation).

  • n_resamples (int) – The initial number of resamples to be performed. Optional, default is 1000.

  • max_resamples (int) – The max number of resamples to be performed by the distribution is assumed to be normal. This is present to allow user control over the time taken for the resampling to occur. Optional, default is 100000.

  • dimension (str) – Dimension/s to find the displacement along, this should be some subset of ‘xyz’ indicating the axes of interest. Optional, defaults to ‘xyz’.

  • alpha (float) – Value that p-value for the normal test must be greater than to accept. Optional, default is 1e-3.

  • random_state (Optional[RandomState]) – A RandomState object to be used to ensure reproducibility. Optional, default is None.

  • progress (bool) – Show tqdm progress for sampling. Optional, default is True.