sitator.landmark package

Submodules

sitator.landmark.errors module

exception sitator.landmark.errors.LandmarkAnalysisError

Bases: Exception

exception sitator.landmark.errors.StaticLatticeError(message, lattice_atoms=None, frame=None, try_recentering=False)

Bases: sitator.landmark.errors.LandmarkAnalysisError

Error raised when static lattice atoms break any limits on their movement/position.

lattice_atoms

The indexes of the atoms in the static lattice that caused the error.

Type:list, optional
frame

The frame in the trajectory at which the error occured.

Type:int, optional
TRY_RECENTERING_MSG = 'Try recentering the input trajectory (sitator.util.RecenterTrajectory)'
exception sitator.landmark.errors.ZeroLandmarkError(mobile_index, frame)

Bases: sitator.landmark.errors.LandmarkAnalysisError

Error raised when a landmark vector containing only zeros is encountered.

mobile_index

Which mobile atom had the all-zero vector.

Type:int
frame

At which frame it was encountered.

Type:int

sitator.landmark.helpers module

Module contents

class sitator.landmark.LandmarkAnalysis(clustering_algorithm='dotprod', clustering_params={}, cutoff_midpoint=1.5, cutoff_steepness=30, minimum_site_occupancy=0.01, site_centers_method='real-weighted', check_for_zero_landmarks=True, static_movement_threshold=1.0, dynamic_lattice_mapping=False, relaxed_lattice_checks=False, max_mobile_per_site=1, force_no_memmap=False, verbose=True)

Bases: object

Site analysis of mobile atoms in a static lattice with landmark analysis.

Parameters:
  • cutoff_center (double) – The midpoint for the logistic function used as the landmark cutoff function. (unitless)
  • cutoff_steepness (double) – Steepness of the logistic cutoff function.
  • minimum_site_occupancy = 0.1 (double) – Minimum occupancy (% of time occupied) for a site to qualify as such.
  • clustering_algorithm (str) –

    The landmark clustering algorithm. sitator supplies two:

    • "dotprod": The method described in our “Unsupervised landmark
      analysis for jump detection in molecular dynamics simulations” paper.
    • "mcl": A newer method we are developing.
  • clustering_params (dict) – Parameters for the chosen clustering_algorithm.
  • site_centers_method (str) –

    The method to use for computing the real space positions of the sites. Options:

    • SITE_CENTERS_REAL_UNWEIGHTED: A spatial average of all real-space
      mobile atom positions assigned to the site is taken.
    • SITE_CENTERS_REAL_WEIGHTED: A spatial average of all real-space
      mobile atom positions assigned to the site is taken, weighted by the confidences with which they assigned to the site.
    • SITE_CENTERS_REPRESENTATIVE_LANDMARK: A spatial average over
      all landmarks’ centers is taken, weighted by the representative or “typical” landmark vector at the site.

    The “real” methods will generally be more faithful to the simulation, but the representative landmark method can work better in cases with short trajectories, producing a more “ideal” site location.

  • check_for_zero_landmarks (bool) – Whether to check for and raise exceptions when all-zero landmark vectors are computed.
  • static_movement_threshold (float) – (Angstrom) the maximum allowed distance between an instantanous static atom position and it’s ideal position.
  • dynamic_lattice_mapping (bool) –

    Whether to dynamically decide each frame which static atom represents each average lattice position; this allows the LandmarkAnalysis to deal with, say, a rare exchage of two static atoms that does not change the structure of the lattice.

    It does NOT allow LandmarkAnalysis to deal with lattices whose structures actually change over the course of the trajectory.

    In certain cases this is better delt with by MergeSitesByDynamics.

  • max_mobile_per_site (int) –

    The maximum number of mobile atoms that can be assigned to a single site without throwing an error. Regardless of the value, assignments of more than one mobile atom to a single site will be recorded and reported.

    Setting this to 2 can be necessary for very diffusive, liquid-like materials at high temperatures.

    Statistics related to this are reported in self.avg_mobile_per_site and self.n_multiple_assignments.

  • force_no_memmap (bool) – if True, landmark vectors will be stored only in memory. Only useful if access to landmark vectors after the analysis has run is desired.
  • verbose (bool) – Verbosity for the clustering_algorithm. Other output controlled through logging.
CLUSTERING_CLUSTER_SIZE = 'cluster-size'
CLUSTERING_CONFIDENCES = 'cluster-confs'
CLUSTERING_LABELS = 'cluster-labels'
CLUSTERING_LANDMARK_GROUPINGS = 'cluster-landmark-groupings'
CLUSTERING_REPRESENTATIVE_LANDMARKS = 'cluster-representative-lvecs'
SITE_CENTERS_REAL_UNWEIGHTED = 'real-unweighted'
SITE_CENTERS_REAL_WEIGHTED = 'real-weighted'
SITE_CENTERS_REPRESENTATIVE_LANDMARK = 'representative-landmark'
cutoff
landmark_dimension

Number of components in a single landmark vector.

landmark_vectors

Landmark vectors from the last invocation of run()

run(sn, frames)

Run the landmark analysis.

The input SiteNetwork is a network of predicted sites; it’s sites will be used as the “basis” for the landmark vectors.

Wraps a copy of frames into the unit cell.

Parameters:
  • sn (SiteNetwork) – The landmark basis. Each site is a landmark defined by its vertex static atoms, as indicated by sn.vertices. (Typically from VoronoiSiteGenerator.)
  • frames (ndarray n_frames x n_atoms x 3) – A trajectory. Can be unwrapped; a copy will be wrapped before the analysis.