kinisi.diffusion
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 is1
(every observation).progress (
bool
) – Show tqdm progress for sampling. Optional, default isTrue
.
- classmethod from_dict(my_dict)[source]#
Generate a
Bootstrap
object from a dictionary.- Parameters
my_dict (
dict
) – The input dictionary.- Return type
- 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
isFalse
is the relavent method call, then this isNone
- 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
) – Shouldtqdm
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 inscipy.stats.normaltest()
for the distributionto be normal. Optional, default is
1e-3
.- Parameters
random_state (
Optional
[RandomState
]) – ARandomState
object to be used to ensure reproducibility. Optional, default isNone
.- Return type
- 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 isFalse
.dt_skip (
float
) – Values ofdt
that should be skipped, i.e. where the atoms are not diffusing. Note that ifuse_ngp
isTrue
this will be ignored. Optional, defaults to0
.fit_intercept (
bool
) – Should the intercept of the diffusion relationship be fit. Optional, default isTrue
.n_samples (
int
) – Number of samples of the Gaussian process to perform. Optional, default is1000
.n_walkers (
int
) – Number of MCMC walkers to use. Optional, default is32
.n_burn (
int
) – Number of burn in samples (these allow the sampling to settle). Optional, default is500
.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
, whereeps
is the machine precision value of the covariance matrix content.progress (
bool
) – Show tqdm progress for sampling. Optional, default isTrue
.random_state (
Optional
[RandomState
]) – ARandomState
object to be used to ensure reproducibility. Optional, default isNone
.
- 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 timestepn_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 psdisp_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 is1
(every observation)n_resamples (
int
) – The initial number of resamples to be performed. Default is1000
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 is100000
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 is1e-3
- :param random_stateA
RandomState
object to be used to ensure reproducibility. Default is
None
- Parameters
progress (
bool
) – Show tqdm progress for sampling. Default isTrue
- 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 is1
(every observation)n_resamples (
int
) – The initial number of resamples to be performed. Optional, default is1000
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 is100000
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 is1e-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 isTrue
- 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 is1
(every observation).n_resamples (
int
) – The initial number of resamples to be performed. Optional, default is1000
.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 is100000
.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 is1e-3
.random_state (
Optional
[RandomState
]) – ARandomState
object to be used to ensure reproducibility. Optional, default isNone
.progress (
bool
) – Show tqdm progress for sampling. Optional, default isTrue
.