mdgo.coordination module

This module implements functions for coordination analysis.

mdgo.coordination.neighbor_distance(nvt_run, center_atom, run_start, run_end, species, select_dict, distance)[source]

Calculates a dictionary of distances between the center_atom and neighbor atoms.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The center atom object.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • species (str) – The neighbor species in the select_dict.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • distance (float) – The neighbor cutoff distance.

Return type

Dict[str, ndarray]

Returns

A dictionary of distance of neighbor atoms to the center_atom. The keys are atom indexes in string type .

mdgo.coordination.find_nearest(trj, time_step, binding_cutoff, hopping_cutoff, smooth=51)[source]

Using the dictionary of neighbor distance trj, finds the nearest neighbor sites that the center atom binds to, and calculates the frequency of hopping between each neighbor, and steps when each binding site exhibits the closest distance to the center atom.

Parameters

  • trj (Dict[str, ndarray]) – A dictionary of distances between center atom and neighbor atoms.

  • time_step (float) – The time step of the simulation in ps.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Detaching cutoff distance.

  • smooth (int) – The length of the smooth filter window. Default to 51.

Return type

Tuple[List[int], Union[float, floating], List[int]]

Returns

Returns an array of nearest neighbor sites (unique on each frame), the frequency of hopping between sites, and steps when each binding site exhibits the closest distance to the center atom.

mdgo.coordination.find_nearest_free_only(trj, time_step, binding_cutoff, hopping_cutoff, smooth=51)[source]

Using the dictionary of neighbor distance trj, finds the nearest neighbor sites that the center_atom binds to, and calculates the frequency of hopping between each neighbor, and steps when each binding site exhibits the closest distance to the center atom. * Only hopping events with intermediate free state (no binded nearest neighbor) are counted.

Parameters

  • trj (Dict[str, ndarray]) – A dictionary of distances between center atom and neighbor atoms.

  • time_step (float) – The time step of the simulation in ps.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Detaching cutoff distance.

  • smooth (int) – The length of the smooth filter window. Default to 51.

Return type

Tuple[List[int], Union[float, floating], List[int]]

Returns

Returns an array of nearest neighbor sites (unique on each frame), the frequency of hopping between sites, and steps when each binding site exhibits the closest distance to the center atom.

mdgo.coordination.find_in_n_out(trj, binding_cutoff, hopping_cutoff, smooth=51, cool=20)[source]

Finds the frames when the center atom binds with the neighbor (binding) or hopping out (hopping) according to the dictionary of neighbor distance.

Parameters

  • trj (Dict[str, ndarray]) – A dictionary of distances between center atom and neighbor atoms.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Hopping out cutoff distance.

  • smooth (int) – The length of the smooth filter window. Default to 51.

  • cool (int) – The cool down frames between hopping in and hopping out. Default to 20.

Return type

Tuple[List[int], List[int]]

Returns

Two arrays of numberings of frames with hopping in and hopping out event, respectively.

mdgo.coordination.check_contiguous_steps(nvt_run, center_atom, distance_dict, select_dict, run_start, run_end, checkpoints, lag=20)[source]

Calculates the distance between the center atom and the neighbor atom in the checkpoint +/- lag time range.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The center atom object.

  • distance_dict (Dict[str, float]) – A dictionary of Cutoff distance of neighbor for each species.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • checkpoints (ndarray) – The frame numberings of interest to check for contiguous steps.

  • lag (int) – The range (+/- lag) of the contiguous steps. Default to 20.

Return type

Dict[str, ndarray]

Returns

An array of distance between the center atom and the neighbor atoms in the checkpoint +/- lag time range.

mdgo.coordination.heat_map(nvt_run, floating_atom, cluster_center_sites, cluster_terminal, cartesian_by_ref, run_start, run_end, dim='xyz')[source]

Calculates the heat map of the floating atom around the cluster. The coordinates are normalized to a cartesian coordinate system where the cluster_center_sites atom is the origin.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • floating_atom (Atom) – Floating atom species.

  • cluster_center_sites (List[int]) – A list of nearest cluster center sites (atom index).

  • cluster_terminal (Union[str, List[str]]) – The selection string for terminal atom species of the cluster (typically the binding site for the floating ion). The argument can be a str if all the terminal atoms have the same selection string and are equivalent, or a list if the terminal atoms are distinct and have different selection strings.

  • cartesian_by_ref (ndarray) – Transformation matrix between cartesian and reference coordinate systems.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • dim (str) – Desired dimensions to calculate heat map. TODO: 2d support or dimension selection.

Return type

ndarray

Returns

The coordinates of the floating ion around clusters normalized to the desired cartesian coordinate system.

mdgo.coordination.process_evol(nvt_run, select_dict, in_list, out_list, distance_dict, run_start, run_end, lag, binding_cutoff, hopping_cutoff, smooth, cool, binding_site, center_atom)[source]

Calculates the coordination number evolution of species around center_atom as a function of time, the coordination numbers are averaged over all frames around events when the center_atom hopping to and hopping out from the binding_site.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • in_list (Dict[str, List[ndarray]]) – A list to store the distances for hopping in events.

  • out_list (Dict[str, List[ndarray]]) – A list to store the distances for hopping out events.

  • distance_dict (Dict[str, float]) – A dict of coordination cutoff distance of the neighbor species.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • lag (int) – The frame range (+/- lag) for check evolution.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Hopping out cutoff distance.

  • smooth (int) – The length of the smooth filter window. Default to 51.

  • cool (int) – The cool down frames between binding and hopping out.

  • binding_site (str) – The binding site of binding and hopping out events.

  • center_atom (str) – The solvation shell center atom.

mdgo.coordination.get_full_coords(coords, reflection=None, rotation=None, inversion=None, sample=None, dim='xyz')[source]

A helper function for calculating the heatmap. It applies the reflection, rotation and inversion symmetry operations to coords and take sample number of samples.

Parameters

  • coords (ndarray) – An array of coordinates.

  • reflection (Optional[List[ndarray]]) – A list of reflection symmetry operation matrix.

  • rotation (Optional[List[ndarray]]) – A list of rotation symmetry operation matrix.

  • inversion (Optional[List[ndarray]]) – A list of inversion symmetry operation matrix.

  • sample (Optional[int]) – Number of samples to take from coords.

  • dim (str) – The dimensions of the coordinates. Default to “xyz”.

Return type

ndarray

Returns

An array with sample number of coordinates.

mdgo.coordination.cluster_coordinates(nvt_run, select_dict, run_start, run_end, species, distance, basis_vectors=None, cluster_center='center')[source]

Calculates the average position of a cluster.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • species (List[str]) – A list of species in the cluster.

  • distance (float) – The coordination cutoff distance.

  • basis_vectors (Union[List[ndarray], ndarray, None]) – The basis vector for normalizing the coordinates of the cluster atoms.

  • cluster_center (str) – Cluster center atom species.

Return type

ndarray

Returns

An array of coordinates of the cluster atoms.

mdgo.coordination.num_of_neighbor(nvt_run, center_atom, distance_dict, select_dict, run_start, run_end, write=False, structure_code=None, write_freq=0, write_path=None)[source]

Calculates the coordination number of each specified neighbor species and the total coordination number in the specified frame range.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The solvation shell center atom.

  • distance_dict (Dict[str, float]) – A dict of coordination cutoff distance of the neighbor species.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start – Start frame of analysis.

  • run_end – End frame of analysis.

  • write – Whether to writes out a series of desired solvation structures as *.xyz files.

  • structure_code – An integer code representing the solvation structure to write out. For example, 221 is two species A, two species B and one species C.

  • write_freq – Probability to write out files.

  • write_path – Path to write out files.

Return type

Dict[str, ndarray]

Returns

A diction containing the coordination number sequence of each specified neighbor species and the total coordination number sequence in the specified frame range .

mdgo.coordination.num_of_neighbor_simple(nvt_run, center_atom, distance_dict, select_dict, run_start, run_end)[source]

Calculates solvation structure type (1 for SSIP, 2 for CIP and 3 for AGG) with respect to the enter_atom in the specified frame range.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The solvation shell center atom.

  • distance_dict (Dict[str, float]) – A dict of coordination cutoff distance of the neighbor species.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

Return type

Dict[str, ndarray]

Returns

A dict with “total” as the key and an array of the solvation structure type in the specified frame range as the value.

mdgo.coordination.angular_dist_of_neighbor(nvt_run, center_atom, distance_dict, select_dict, run_start, run_end, cip=True)[source]

Calculates the angle of a-c-b of center atom c in the specified frames.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The center atom object.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • distance_dict (Dict[str, float]) – A dict of coordination cutoff distance of the neighbor species. The key must be in the order of a, b, c, where a is the neighbor species used for determining coordination type, b is the other neighbor species, and c is the center species.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • cip (bool) – Only includes contact ion pair structures with only one a and one c atoms. Default to True.

Return type

Dict[str, ndarray]

Returns

An array of angles of a-c-b occurrence in the specified frames.

mdgo.coordination.num_of_neighbor_specific(nvt_run, center_atom, distance_dict, select_dict, run_start, run_end, counter_atom='anion')[source]

Calculates the coordination number of each specific solvation structure type (SSIP, CIP, AGG).

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The center atom object.

  • distance_dict (Dict[str, float]) – A dict of coordination cutoff distance of the neighbor species.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • counter_atom (str) – The neighbor counter ion species. Default to “anion”.

Return type

Dict[str, ndarray]

Returns

A tuple containing three dictionary of the coordination number of each neighbor species and total coordination number for the three solvation structure type, respectively.

mdgo.coordination.full_solvation_structure(nvt_run, center_atom, center_species, counter_species, select_dict, distance, run_start, run_end, depth=4)[source]

Obtain the solvation structure of a full connected ion network with depth-first traversal.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • center_atom (Atom) – The center atom object.

  • center_species (str) – The center ion species. It should be the atom directly connect to the counter ion.

  • counter_species (str) – The neighbor counter ion species. It should be the atom directly connect to the center ion.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • depth (int) – The depth of the traversal. Default to 4

Return type

ndarray

Returns

Return an array of full solvation structure of the specified frames. Each solvation structure is represented by an array of the number of ions from the first to the n-th solvation shell with n=``depth``.

mdgo.coordination.concat_coord_array(nvt_run, func, center_atoms, distance_dict, select_dict, run_start, run_end, **kwargs)[source]

A helper function to analyze the coordination number/structure of every atoms in an AtomGroup using the specified function.

Parameters

  • nvt_run (Universe) – An MDAnalysis Universe containing wrapped trajectory.

  • func (Callable) – One of the neighbor statistical method (num_of_neighbor, num_of_neighbor_simple)

  • center_atoms (AtomGroup) – Atom group of the center atoms.

  • distance_dict (Dict[str, float]) – A dictionary of coordination cutoff distance of the neighbor species.

  • select_dict (Dict[str, str]) – A dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection language.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • kwargs (Union[bool, str]) –

Return type

Dict[str, ndarray]

Returns

A diction containing the coordination number sequence of each specified neighbor species and the total coordination number sequence in the specified frame range.

mdgo.coordination.write_out(center_pos, center_name, neighbors, path)[source]

Helper function for solvation structure coordinates write out.

Parameters

  • center_pos (ndarray) – The coordinates of the center atom in the frame.

  • center_name (str) – The element name of the center atom in the frame.

  • neighbors (AtomGroup) – The neighbor AtomGroup.

  • path (str) – The path to write out *.xyz file.

mdgo.coordination.select_shell(select, distance, center_atom, kw)[source]

Select a group of atoms that is within a distance of an center_atom.

Parameters

  • select (Union[Dict[str, str], str]) – A selection string of neighbors or a dictionary of atom species selection, where each atom species name is a key and the corresponding values are the selection string.

  • distance (Union[Dict[str, float], str]) – A neighbor cutoff distance or a dict of cutoff distances of neighbor species.

  • center_atom (Atom) – The solvation shell center Atom object

  • kw (str) – The key for the select and/or distance dictionary if applicable.

Return type

str

Returns

A selection string specifying the neighbor species within a distance of the center_atom.