sitator.dynamics package

Module contents

class sitator.dynamics.AverageVibrationalFrequency(min_frequency=0, max_frequency=inf)

Bases: object

Compute the average vibrational frequency of indicated atoms in a trajectory.

Uses the method described in section 2.2 of this paper:

Klerk, Niek J.J. de, Eveline van der Maas, and Marnix Wagemaker.

Analysis of Diffusion in Solid-State Electrolytes through MD Simulations, Improvement of the Li-Ion Conductivity in β-Li3PS4 as an Example.

ACS Applied Energy Materials 1, no. 7 (July 23, 2018): 3230–42. https://doi.org/10.1021/acsaem.8b00457.

Parameters:
  • (float, units (max_frequency) – timestep^-1): Compute mean frequency of power spectrum above this frequency.
  • (float, units – timestep^-1): Compute mean frequency of power spectrum below this frequency.
compute_avg_vibrational_freq(traj, mask, return_stdev=False)

Compute the average vibrational frequency.

Parameters:
  • traj (ndarray n_frames x n_atoms x 3) – An MD trajectory.
  • mask (ndarray n_atoms bool) – Which atoms to average over.
Returns:

A frequency in units of (timestep)^-1
class sitator.dynamics.JumpAnalysis

Bases: object

Given a SiteTrajectory, compute various statistics about the jumps it contains.

Adds these edge attributes to the SiteTrajectory’s SiteNetwork:
  • n_ij: total number of jumps from i to j.
  • p_ij: being at i, the probability of jumping to j.
  • jump_lag: The average number of frames a particle spends at i before jumping
    to j. Can be +inf if no such jumps every occur.
And these site attributes:
  • residence_times: Avg. number of frames a particle spends at a site before jumping.
  • total_corrected_residences: Total number of frames when a particle was at the site,
    including frames when an unassigned particle’s last known site was this site.
jump_lag_by_type(sn, return_counts=False)

Given a SiteNetwork with jump_lag info, compute avg. residence times by type.

Computes the average number of frames a mobile particle spends at each type of site before jumping to each other type of site.

Parameters:
  • sn (SiteNetwork) –
  • return_counts (bool) – Whether to also return a matrix giving the
  • of each type of jump that occured. (number) –
Returns:

An (n_types, n_types) matrix. If no jumps of a given type occured,

the corresponding entry is +inf.

If return_counts, two such matrixes.
plot_jump_lag(sn, mode='site', min_n_events=1, ax=None, fig=None, **kwargs)

Plot the jump lag of a site network.

Parameters:
  • sn (SiteNetwork) –
  • mode (str) – If 'site', show jump lag between individual sites. If 'type', show jump lag between types of sites (see :func:jump_lag_by_type)
  • min_n_events (int) – Minimum number of jump events of a given type (i -> j or type -> type) to show a jump lag. If a given jump has occured less than min_n_events times, no jump lag will be shown.
run(st)

Run the analysis.

Adds edge attributes to st’s SiteNetwork.

Parameters:st (SiteTrajectory) –
Returns:st
class sitator.dynamics.MergeSitesByDynamics(connectivity_matrix_generator=None, distance_threshold=1.0, post_check_thresh_factor=1.5, check_types=True, markov_parameters={})

Bases: sitator.network.merging.MergeSites

Merges sites using dynamical data.

Given a SiteTrajectory, merges sites using Markov Clustering.

Parameters:
  • distance_threshold (float) – Don’t merge sites further than this in real space. Zeros out the connectivity_matrix at distances greater than this; a hard, step function style cutoff. For a more gentle cutoff, try changing connectivity_matrix_generator to incorporate distance.
  • post_check_thresh_factor (float) – Throw an error if proposed merge sites are further than this * distance_threshold away. Only a sanity check; not a hard guerantee. Can be None; defaults to 1.5. Can be loosely thought of as how “normally distributed” the merge sites need to be, with larger values allowing more and more oblong point clouds.
  • check_types (bool) – If True, only sites of the same type are candidates to be merged; if false, type information is ignored. Merged sites will only be assigned types if this is True.
  • iterlimit (int) – Maximum number of Markov Clustering iterations to run before throwing an error.
  • markov_parameters (dict) – Parameters for underlying Markov Clustering. Valid keys are 'inflation', 'expansion', and 'pruning_threshold'.
static connectivity_jump_lag_biased(jump_lag_coeff=1.0, jump_lag_sigma=20.0, jump_lag_cutoff=inf, distance_coeff=0.5, distance_sigma=1.0)

Bias the typical connectivity matrix p_ij with jump lag and distance contributions.

The jump lag and distance are processed through Gaussian functions with the given sigmas (i.e. higher jump lag/larger distance => lower connectivity value). These matrixes are then added to p_ij, with a prefactor of jump_lag_coeff and distance_coeff.

Site pairs with jump lags greater than jump_lag_cutoff have their bias set to zero regardless of jump_lag_sigma. Defaults to inf.

static connectivity_n_ij(sn)

Basic default connectivity scheme: uses n_ij directly as connectivity matrix.

Works well for systems with sufficient statistics.

class sitator.dynamics.MergeSitesByThreshold(attrname, relation=<built-in function ge>, directed=True, connection='strong', distance_threshold=inf, forbid_multiple_occupancy=False, **kwargs)

Bases: sitator.network.merging.MergeSites

Merge sites using a strict threshold on any edge property.

Takes the edge property matrix given by attrname, applys relation to it with threshold, and merges all connected components in the graph represented by the resulting boolean adjacency matrix.

Threshold is given by a keyword argument to run().

Parameters:
  • attrname (str) – Name of the edge attribute to merge on.
  • (func, default (relation) – operator.ge): The relation to use for the thresholding.
  • connection (directed,) – Parameters for scipy.sparse.csgraph’s connected_components.
  • **kwargs – Passed to MergeSites.
class sitator.dynamics.RemoveUnoccupiedSites

Bases: object

Remove unoccupied sites.

run(st, return_kept_sites=False)
Parameters:return_kept_sites (bool) – If True, a list of the sites from st that were kept will be returned.
Returns:A SiteTrajectory, or st itself if it has no unoccupied sites.