sitator package¶
Subpackages¶
Submodules¶
Module contents¶
-
class
sitator.
SiteNetwork
(structure, static_mask, mobile_mask)¶ Bases:
object
A network of mobile particle sites in a static lattice.
Stores the locations of sites (
centers
) for some indicated mobile atoms (mobile_mask
) in a structure (structure
). Optionally includes their defining static atoms (vertices
) and “types” (site_types
).Arbitrary data can also be associated with each site and with each edge between sites. Site data can be any array of length n_sites; edge data can be any matrix of shape (n_sites, n_sites) where entry i, j is the value for the edge from site i to site j (edge attributes can be asymmetric).
Attributes can be marked as “computed”; this is a hint that the attribute was computed based on a
SiteTrajectory
. Mostsitator
algorithms that modify/processSiteTrajectory``s will clear "computed" attrbutes, assuming that they are invalidated by the changes to the ``SiteTrajectory
.-
centers
¶ (n_sites, 3) coordinates of each site.
Type: ndarray
-
vertices
¶ list of lists of indexes of static atoms defining each site.
Type: list, optional
-
site_types
¶ (n_sites,) values grouping sites into types.
Type: ndarray, optional
Parameters: - structure (ase.Atoms) – an ASE
Atoms
containging whatever atoms exist in the MD trajectory. - static_mask (ndarray) – Boolean mask indicating which atoms make up the host lattice.
- mobile_mask (ndarray) – Boolean mask indicating which atoms’ movement we are interested in.
-
ATTR_NAME_REGEX
= re.compile('^[a-zA-Z][a-zA-Z0-9_]*$')¶
-
add_edge_attribute
(name, attr, computed=True)¶ Add an edge attribute.
Parameters: - name (str) –
- attr (ndarray) – Must be of shape
(n_sites, n_sites)
. - computed (bool) – Whether to mark this attribute as “computed”.
-
add_site_attribute
(name, attr, computed=True)¶ Add a site attribute.
Parameters: - name (str) –
- attr (ndarray) – Must be of length
n_sites
. - computed (bool) – Whether to mark this attribute as “computed”.
-
centers
The positions of the sites.
-
clear_attributes
()¶ Remove all site and edge attributes.
-
clear_computed_attributes
()¶ Remove all attributes marked “computed”.
-
copy
(with_computed=True)¶ Returns a (shallowish) copy of self.
Parameters: with_computed (bool) – If False
, attributes marked “computed” will not be included in the copy.Returns: A SiteNetwork
.
-
edge_attributes
¶ The names of the
SiteNetwork
’s edge attributes.
-
get_edge
(edge)¶ Get all info for the edge identified by (i, j)
Parameters: edge (tuple) – which edge to get data on. Returns dict:
-
get_site
(site)¶ Get all info about a site.
Parameters: site (int) – Returns dict:
-
get_structure_with_sites
(site_atomic_number=None)¶ Get an
ase.Atoms
with the sites included.Sites are appended to the static structure; the first
np.sum(static_mask)
atoms in the returned object are the static structure.Parameters: site_atomic_number – If None
, the species of the first mobile atom will be used.Returns: ase.Atoms
and finalsite_atomic_number
-
has_attribute
(attr)¶ Whether the
SiteNetwork
has a given site or edge attrbute.Parameters: attr (str) – Returns: bool
-
n_sites
¶ The number of sites.
-
n_total
¶ The total number of atoms in the system.
-
n_types
¶ The number of site types in the
SiteNetwork
.
-
number_of_vertices
¶ The number of vertices of each site.
-
of_type
(stype)¶ Returns a subset of this
SiteNetwork
with only sites of a certain type.Parameters: stype (int) – Returns: A SiteNetwork
.
-
plot
(*args, **kwargs)¶ Convenience method – constructs a defualt
SiteNetworkPlotter
and calls it.
-
remove_attribute
(attr)¶ Remove a site or edge attribute.
Parameters: attr (str) –
-
site_attributes
¶ The names of the
SiteNetwork
’s site attributes.
-
site_ids
¶ Convenience property giving the index of each site.
-
site_types
The type IDs of each site.
-
types
¶ The unique site type IDs in the
SiteNetwork
.
-
update_centers
(newcenters)¶ Update the
SiteNetwork
’s centers without reseting all other information.Parameters: newcenters (ndarray) – Must have same length as current number of sites.
-
vertices
The static atoms defining each site.
-
-
class
sitator.
SiteTrajectory
(site_network, particle_assignments, confidences=None)¶ Bases:
object
A trajectory capturing the dynamics of particles through a SiteNetwork.
-
SITE_UNKNOWN
= -1¶
-
assign_to_last_known_site
(frame_threshold=1)¶ Assign unassigned mobile particles to their last known site.
Parameters: frame_threshold (int) – The maximum number of frames between the last known site and the present frame up to which the last known site can be used. Returns: information dictionary of debugging/diagnostic information.
-
check_multiple_occupancy
(max_mobile_per_site=1)¶ Count cases of “multiple occupancy” where more than one mobile share the same site at the same time.
These cases usually indicate bad site analysis.
Returns: the total number of multiple assignment incidents; and float: the average number of mobile atoms at any site at any one time. Return type: int
-
compute_site_occupancies
()¶ Computes site occupancies.
Adds site attribute
occupancies
tosite_network
.In cases of multiple occupancy, this will be higher than the number of frames in which the site is occupied and could be over 1.0.
Returns: ndarray of occupancies (length n_sites
)
-
confidences
¶
-
copy
(with_computed=True)¶ Return a copy.
Parameters: with_computed (bool) – See SiteNetwork.copy()
.
-
jumps
(**kwargs)¶ Iterate over all jumps in the trajectory, jump by jump.
A jump is considered to occur “at the frame” when it first acheives its new site. For example,
- Frame 0: Atom 1 at site 4
- Frame 1: Atom 1 at site 5
will yield a jump
(1, 1, 4, 5)
.Parameters: unknown_as_jump (bool) – If True
, moving from a site to unknown (or vice versa) is considered a jump; ifFalse
, unassigned mobile atoms are considered to be at their last known sites.Yields: tuple – (frame_number, mobile_atom_number, from_site, to_site)
-
jumps_by_frame
(**kwargs)¶ Iterate over all jumps in the trajectory, frame by frame.
A jump is considered to occur “at the frame” when it first acheives its new site. For example,
- Frame 0: Atom 1 at site 4
- Frame 1: Atom 1 at site 5
will yield a jump
(1, 1, 4, 5)
.Parameters: unknown_as_jump (bool) – If True
, moving from a site to unknown (or vice versa) is considered a jump; ifFalse
, unassigned mobile atoms are considered to be at their last known sites.Yields: tuple – (frame_number, mob_that_jumped, from_sites, to_sites)
-
n_assigned
¶ The total number of times a mobile particle was assigned to a site.
-
n_frames
¶ The number of frames in the trajectory.
-
n_unassigned
¶ The total number of times a mobile particle is unassigned.
-
percent_unassigned
¶ Proportion of particle positions that are unassigned over all time.
-
plot_frame
(*args, **kwargs)¶
-
plot_particle_trajectory
(*args, **kwargs)¶
-
plot_site
(*args, **kwargs)¶
-
real_positions_for_site
(site, return_confidences=False)¶ Get all real-space positions assocated with a site.
Parameters: - site (int) –
- return_confidences (bool) – If
True
, the confidences with which each real-space position was assigned tosite
are also returned.
Returns: ndarray (N, 3)[, ndarray (N)]
-
real_trajectory
¶ The real-space trajectory this
SiteTrajectory
is based on.
-
remove_real_traj
()¶ Forget associated real trajectory.
-
set_real_traj
(real_traj)¶ Assocaite this SiteTrajectory with a trajectory of points in real space.
The trajectory is not copied.
Parameters: real_traj (ndarray of shape (n_frames, n_total)) –
-
site_network
¶
-
traj
¶ The site assignments over time.
-
trajectory_for_particle
(i, return_confidences=False)¶ Returns the array of sites particle i is assigned to over time.
Parameters: - i (int) –
- return_confidences (bool) – If
True
, also return the confidences with which those assignments were made.
Returns: ndarray (int) of length
n_frames``[, ndarray (float) length ``n_frames
]
-