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. Most sitator algorithms that modify/process SiteTrajectory``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 final `site_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 to site_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; if `False`, 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; if `False`, 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 to `site` 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]