sitator.landmark package¶
Subpackages¶
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
andself.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 throughlogging
.
-
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.
- sn (SiteNetwork) – The landmark basis. Each site is a landmark defined
by its vertex static atoms, as indicated by sn.vertices.
(Typically from