mdgo.core module

This module implements two core class MdRun and MdJob for molecular dynamics simulation analysis and job setup.

class mdgo.core.MdRun(wrapped_run, unwrapped_run, nvt_start, time_step, name, select_dict=None, res_dict=None, cation_name='cation', anion_name='anion', cation_charge=1, anion_charge=- 1, temperature=298.15, cond=True, units='real')[source]

Bases: object

A core class for MD results analysis. TODO: add support for 2d and dimension selection.

Parameters

  • wrapped_run (Universe) – The Universe object of wrapped trajectory.

  • unwrapped_run (Universe) – The Universe object of unwrapped trajectory.

  • nvt_start (int) – NVT start time step.

  • time_step (float) – Timestep between each frame, in ps.

  • name (str) – Name of the MD run.

  • select_dict (Optional[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. This dict is intended for analyzing interested atoms.

  • res_dict (Optional[Dict[str, str]]) – A dictionary of resnames, where each resname is a key and the corresponding values are the selection language. This dict is intended for analyzing interested residues (ions/molecules).

  • cation_name (str) – Name of cation. Default to “cation”.

  • anion_name (str) – Name of anion. Default to “anion”.

  • cation_charge (float) – Charge of cation. Default to 1.

  • anion_charge (float) – Charge of anion. Default to 1.

  • temperature (float) – Temperature of the MD run. Default to 298.15.

  • cond (bool) – Whether to calculate conductivity MSD. Default to True.

  • units – unit system (currently ‘real’ and ‘lj’ are supported)

classmethod from_lammps(data_dir, wrapped_dir, unwrapped_dir, nvt_start, time_step, name, select_dict=None, res_dict=None, cation_name='cation', anion_name='anion', cation_charge=1, anion_charge=- 1, temperature=298.15, cond=True, units='real')[source]

Constructor from lammps data file and wrapped and unwrapped trajectory dcd file.

Parameters

  • data_dir (str) – Path to the data file.

  • wrapped_dir (str) – Path to the wrapped dcd file.

  • unwrapped_dir (str) – Path to the unwrapped dcd file.

  • nvt_start (int) – NVT start time step.

  • time_step (float) – LAMMPS timestep in ps.

  • name (str) – Name of the MD run.

  • select_dict (Optional[Dict[str, str]]) – A dictionary of species selection.

  • res_dict (Optional[Dict[str, str]]) – A dictionary of resnames.

  • cation_name (str) – Name of cation. Default to “cation”.

  • anion_name (str) – Name of anion. Default to “anion”.

  • cation_charge (float) – Charge of cation. Default to 1.

  • anion_charge (float) – Charge of anion. Default to 1.

  • temperature (float) – Temperature of the MD run. Default to 298.15.

  • cond (bool) – Whether to calculate conductivity MSD. Default to True.

  • units (str) – unit system (currently ‘real’ and ‘lj’ are supported)

get_init_dimension()[source]

Returns the initial box dimension.

Return type

ndarray

get_equilibrium_dimension(npt_range, period=200)[source]

Returns the equilibrium box dimension.

Parameters

  • npt_range (int) – The maximum time step of the npt run.

  • period (int) – The interval of checking points for volume convergence.

Return type

ndarray

get_nvt_dimension()[source]

Returns the box dimension at the last frame.

Return type

ndarray

get_cond_array()[source]

Calculates the conductivity “mean square displacement”.

Return type

ndarray

Returns

An array of MSD values for each time in the trajectory.

choose_cond_fit_region()[source]

Computes the optimal fitting region (linear regime) of conductivity MSD.

Parameters

msd (numpy.array) – mean squared displacement

Return type

tuple

Returns at tuple with the start of the fitting regime (int), end of the fitting regime (int), and the beta value of the fitting regime (float).

Return type

tuple

plot_cond_array(start=- 1, end=- 1, *runs, reference=True)[source]

Plots the conductivity MSD as a function of time. If no fitting region (start, end) is provided, computes the optimal fitting region based on the portion of the MSD with greatest linearity.

Parameters

  • start (int) – Start time step for fitting.

  • end (int) – End time step for fitting.

  • runs (MdRun) – Other runs to be compared in the same plot.

  • reference (bool) – Whether to plot reference line. Default to True.

  • units (str) – unit system (currently ‘real’ and ‘lj’ are supported)

get_conductivity(start=- 1, end=- 1)[source]

Calculates the Green-Kubo (GK) conductivity given fitting region. If no fitting region (start, end) is provided, computes the optimal fitting region based on the portion of the MSD with greatest linearity.

Parameters

  • start (int) – Start time step for fitting MSD.

  • end (int) – End time step for fitting MSD.

Return type

float

Print and return conductivity.

Return type

float

Parameters

  • start (int) –

  • end (int) –

coord_num_array_single_species(species, distance, run_start, run_end, center_atom='cation')[source]

Calculates the coordination number array of one species around the interested center_atom.

Parameters

  • species (str) – The neighbor species.

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

Return type

ndarray

Returns

An array of coordination number in the frame range.

coord_num_array_multi_species(distance_dict, run_start, run_end, center_atom='cation')[source]

Calculates the coordination number array of multiple species around the interested center_atom.

Parameters

  • 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.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

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.

coord_num_array_specific(distance_dict, run_start, run_end, center_atom='cation', counter_atom='anion')[source]

Calculates the coordination number array of multiple species of specific coordination types (SSIP, CIP, AGG).

Parameters

  • 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.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

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

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.

write_solvation_structure(distance_dict, run_start, run_end, structure_code, write_freq, write_path, center_atom='cation')[source]

Writes out a series of desired solvation structures as *.xyz files

Parameters

  • 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.

  • structure_code (int) – An integer code representing the solvation structure, for example, 221 is two species A, two species B and one species C with the same order as in the distance_dict.

  • write_freq (float) – Probability to write out files.

  • write_path (str) – Path to write out files.

  • center_atom (str) – The solvation shell atom. Default to “cation”.

coord_type_array(distance, run_start, run_end, center_atom='cation', counter_atom='anion')[source]

Calculates the solvation structure type (1 for SSIP, 2 for CIP, 3 for AGG) array of the solvation structure center_atom (typically the cation).

Parameters

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

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

Return type

ndarray

Returns

An array of the solvation structure type in the specified frame range.

angle_array(distance_dict, run_start, run_end, center_atom='cation', cip=True)[source]

Calculates the angle of a-c-b in the specified frame range.

Parameters

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

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The center atom species.

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

Returns

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

coordination(species, distance, run_start, run_end, center_atom='cation')[source]

Tabulates the coordination number distribution of one species around the solvation structure center_atom.

Parameters

  • species (str) – The neighbor species.

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

Return type

DataFrame

Returns

A dataframe of the species coordination number and corresponding percentage.

rdf_integral(distance_dict, run_start, run_end, center_atom='cation')[source]

Calculates the integral of the radial distribution function of selected species around the center_atom.

Parameters

  • 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.

  • center_atom (str) – The solvation shell center atom to calculate the radial distribution for. Default to “cation”.

Return type

DataFrame

Returns

A dataframe of the species and the coordination number.

coordination_type(distance, run_start, run_end, center_atom='cation', counter_atom='anion')[source]

Tabulates the percentage of each solvation structures (CIP/SSIP/AGG)

Parameters

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

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

Return type

DataFrame

Returns

A dataframe of the solvation structure and percentage.

coordination_specific(distance_dict, run_start, run_end, center_atom='cation', counter_atom='anion')[source]

Calculates the integral of the coordiantion number of selected species in each type of solvation structures (CIP/SSIP/AGG)

Parameters

  • 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.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

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

Return type

DataFrame

Returns

A dataframe of the solvation structure and percentage.

get_msd_all(start=0, stop=- 1, fft=True, species='cation')[source]

Calculates the mean square displacement (MSD) of the interested atom species.

Parameters

  • start (int) – Start time step.

  • stop (int) – End time step.

  • fft (bool) – Whether to use fft to calculate msd. Default to True.

  • species (str) – The species for analysis. Default to “cation”.

Return type

ndarray

Returns

An array of MSD values in the trajectory

get_msd_partial(distance, run_start, run_end, largest=1000, center_atom='cation', binding_site='anion')[source]

Calculates the mean square displacement (MSD) of the center_atom according to coordination states. The returned free_array include the MSD when center_atom is not coordinated to binding_site. The attach_array includes the MSD when center_atom is coordinated to binding_site.

Parameters

  • distance (float) – The coordination cutoff distance.

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • largest (int) – The largest time sequence to trace.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

  • binding_site (str) – The species the center_atom coordinates to. Default to “anion”.

Return type

Tuple[Optional[List[ndarray]], Optional[List[ndarray]]]

Returns

Two arrays of MSD in the trajectory

get_d(msd_array, start, stop, percentage=1, species='cation')[source]

Prints the self-diffusion coefficient (in m^2/s) of the species. Prints the Nernst-Einstein conductivity (in mS/cm) if it’s the cation.

Parameters

  • msd_array (ndarray) – msd array.

  • start (int) – Start time step.

  • stop (int) – End time step.

  • percentage (float) – The percentage of the cation. Default to 1.

  • species (str) – The species for analysis. Default to “cation”.

get_neighbor_corr(distance_dict, run_start, run_end, center_atom='cation')[source]

Calculates the neighbor auto-correlation function (ACF) of selected species around center_atom.

Parameters

  • 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.

  • center_atom (str) – The solvation shell center atom to calculate the ACF for. Default to “cation”.

Return type

Tuple[ndarray, Dict[str, ndarray]]

Returns

An array of the time series and a dict of ACFs of each species.

get_residence_time(times, acf_avg_dict, cutoff_time)[source]

Calculates the residence time of selected species around cation

Parameters

  • times (ndarray) – The time series.

  • acf_avg_dict (Dict[str, ndarray]) – A dict of ACFs of each species.

  • cutoff_time (int) – Cutoff time for fitting the exponential decay.

Return type

Dict[str, floating]

Returns

The residence time of each species in a dict.

get_neighbor_trj(run_start, run_end, species, neighbor_cutoff, center_atom='cation', index=0)[source]

Returns the distance between one center atom and neighbors as a function of time

Parameters

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

  • species (str) – The neighbor species.

  • neighbor_cutoff (float) – The neighbor cutoff distance.

  • index (int) – The index of the atom in the interested atom group.

Return type

Dict[str, ndarray]

Returns

A dict of distance arrays of the center atom-neighbor as a function of time with neighbor id as keys.

get_hopping_freq_dist(run_start, run_end, binding_site, binding_cutoff, hopping_cutoff, floating_atom='cation', smooth=51, mode='full')[source]

Calculates the cation hopping rate and hopping distance.

Parameters

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • binding_site (str) – Floating ion binding site species.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Hopping out cutoff distance.

  • floating_atom (str) – Floating atom species.

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

  • mode (str) – The mode of treating hopping event. Default to “full”.

Return type

Tuple[floating, floating]

Returns

The floating_atom average hopping rate and average hopping distance.

shell_evolution(distance_dict, run_start, run_end, lag_step, binding_cutoff, hopping_cutoff, smooth=51, cool=0, binding_site='anion', center_atom='cation', duplicate_run=None)[source]

Calculates the coordination number evolution of species around center_atom as a function of time, the coordination numbers are averaged over all time steps around events when the center_atom hopping to and hopping out from the binding_site. If duplicate_run is given, it is also averaged over all duplicate runs.

Parameters

  • 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_step (int) – time steps to track before and after the hopping event

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Detaching 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.

  • center_atom (str) – The solvation shell center atom. Default to “cation”.

  • binding_site (str) – The select_dict key of the binding site. Default to “anion”.

  • duplicate_run (Optional[List[MdRun]]) – Default to None.

Return type

Dict[str, Dict[str, Union[int, ndarray]]]

Returns

A dictionary containing the number of trj logged, the averaged coordination number and standard deviation for each species, and the corresponding time sequence.

get_heat_map(run_start, run_end, cluster_center, cluster_terminal, binding_cutoff, hopping_cutoff, floating_atom='cation', cartesian_by_ref=None, sym_dict=None, sample=None, smooth=51, dim='xyz')[source]

Calculates the heatmap matrix of floating ion around a cluster

Parameters

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • cluster_center (str) – The center atom species of the cluster.

  • 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.

  • binding_cutoff (float) – Binding cutoff distance.

  • hopping_cutoff (float) – Detaching cutoff distance.

  • floating_atom (str) – The floating atom species.

  • cartesian_by_ref (Optional[ndarray]) – Transformation matrix between cartesian and reference coordinate systems. Default to None.

  • sym_dict (Optional[Dict[str, List[ndarray]]]) – Dictionary of symmetry operation dictionary. Default to None.

  • sample (Optional[int]) – Number of samples desired. Default to None, which is no sampling.

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

  • dim (str) – Desired dimensions to calculate heat map

Return type

ndarray

Returns

An array of coordinates.

get_cluster_distance(run_start, run_end, neighbor_cutoff, cluster_center='center')[source]

Calculates the average distance of the center of clusters/molecules

Parameters

  • run_start (int) – Start frame of analysis.

  • run_end (int) – End frame of analysis.

  • neighbor_cutoff (float) – Upper limit of first nearest neighbor.

  • cluster_center (str) – species name of cluster center. Default to “center”.

Return type

floating

Returns

The averaged distance.

class mdgo.core.MdJob(name)[source]

Bases: object

A core class for MD results analysis.

classmethod from_dict()[source]

Constructor.

Returns:

classmethod from_recipe()[source]

Constructor.

Returns: