molecular_dynamics

Full Documentation for hippynn.molecular_dynamics package. Click here for a summary page.

A range of tools for working with MD data and running MD using hippynn. Includes tools for processing MD data to use for training hippynn models and analyzing MD trajectories, a custom molecular dynamics driver that allows for the design of user-created algorithms, and a suite of functions for applying coarse-graining mappings to all-atom data.

class SpeciesLookup(species_numbers, species_names)[source]

Bases: object

name_to_number(name)[source]

number_to_name(num)[source]

calculate_adf(positions, cutoffs, cells=None, species=None)[source]

Computes ADFs for given cutoffs. If species is not provided, also computes species triple specific ADFs.

This code will be quite slow if numba is not available.

Parameters:

positions (np.ndarray) – Shape (n_frames, n_particles, 3).
cutoff (list[float]) – Maximum arm lengths on angles to consider.
cells (np.ndarray or None, optional) – Shape (n_frames, 3, 3) or (3, 3), no PBC if None, defaults to None.
species (np.ndarray or None, optional) – Shape (n_frames, n_particles) or (n_particles,), defaults to None.

Returns:

A dictionary with keys - f”adf_values_all-all-all_cutoff_{cutoff}” (np.ndarray): y-values for plotting ADF of all positions for each value cutoff in cutoffs, shape (180,). - f”adf_values_{center}-{end1}-{end2}_cutoff_{cutoff}” (np.ndarray): Available only if species was provided. y-values for plotting ADF of all angles

with center of type center and ends of species end1 and end2 for all possible combinations triples of species species, and for each value cutoff in cutoffs, shape (180,).

Return type:

dict

calculate_rdf(positions: ndarray, cutoff: float, cells: ndarray = None, species: ndarray = None, n_bins: int = 300, lower_cutoff: float = 0)[source]

Computes the RDF. If species is not provided, also computes species pair specific RDFS.

Parameters:

positions (np.ndarray) – Shape (n_frames, n_particles, 3).
cutoff (float) – Largest pair distance considered.
cells (np.ndarray or None, optional) – Shape (n_frames, 3, 3) or None to if no PBC, defaults to None.
species (np.ndarray or None, optional) – Shape (n_frames, n_particles) or (n_particles,), defaults to None.
n_bins (int, optional) – Number of bins for RDF(s), defaults to 300.
lower_cutoff (float, optional) – Smallest pair distance considered, defaults to 0.

Returns:

A tuple containng - bin_centers (np.ndarray): x-values for plotting RDF, shape (n_bins,). - rdf (np.ndarray): y-values for plotting RDF, shape (n_bins,). - species_rdfs (dict(str, np.ndarray)): Only included if species is provided. Dictionary where the keys are pairs “rdf_values_i-j” for each

pair of species i and j, and the values are the RDF y-values for that species pair. The same x-values are used for all RDFs.

Return type:

tuple

cg_one_average(bead_values)[source]: Unweighted average

cg_one_center_of_geometry_pbc(bead_values, frame_cell, wrap_into_cell=True)[source]: Position center of geometry using PBC

cg_one_center_of_mass_pbc(bead_values, bead_masses, frame_cell, wrap_into_cell=True)[source]: Position center of mass using PBC

cg_one_mass_weighted_average(bead_values, bead_masses)[source]: General mass-weighted average (eg. for velocities when using COM position mapping)

cg_one_sum(bead_values)[source]: Sum of values

coarse_grain_all(values, atom_to_bead, coarse_grain_one, masses=None, cells=None, atom_species=None, bead_species=None, single_frame=False)[source]

Apply a user-defined coarse_grain_one function to all beads across all frames.

The user-supplied function, coarse_grain_one, should take bead_values as an argument, which will correspond the the values of values for one bead in one frame. It can optionally take bead_masses, frame_cell, bead_atom_species, and bead_type as additional arguments. It should return the coarse_grained version of values for the bead given the data provided.

This function loops over each frame (if single_frame=False) and over each bead (as defined by atom_to_bead) and applies coarse_grain_one to each bead. Returns the resulting values in an array of shape (n_frames, n_beads, …) or (n_beads, …) where the trailing dimensions match the output of coarse_grain_one.

See examples of pre-defined coarse_grain_one options in hippynn.molecular_dynamics.coarse_grain.

Parameters:

values – Array of data to coarse-grain. Shape (n_frames, n_atoms, d) if single_frame=False or (n_atoms, d) if single_frame=True.
atom_to_bead – Integer array of shape (n_frames, n_atoms,) or (n_atoms,) mapping each atom to a bead.
coarse_grain_one – Function to coarse-grain one bead’s data.
masses – (Optional) Array of shape (n_frames, n_atoms,) or (n_atoms,) of masses. Values for the current frame/bead passed to coarse_grain_one if provided.
cells – (Optional) Array of shape (n_frames, 3, 3) or (3, 3) of cell matrices. The cell for the current frame is passed to coarse_grain_one if provided.
atom_species – (Optional) Array of shape (n_frames, n_atoms,) or (n_atoms,) of atom species, defined in any manner you choose. Values for the current frame passed to coarse_grain_one if provided.
bead_species – (Optional) Array of shape (n_frames, max_bead_idx+1,) or (max_bead_idx+1,) where max_bead_idx is the maximum value in atom_to_bead. Values for the current frame/bead passed to coarse_grain_one if provided.
single_frame – (Optional) Use to specify if data arrays contain a frame axis. Defaults to False.

Returns:

Array of coarse-grained values. Shape (n_frames, n_beads, …) if single_frame=False or (n_beads, …) if single_frame=True.

write_extxyz(filename, positions, species=None, cells=None, velocities=None, forces=None)[source]

Write a extended XYZ (.extxyz) file.

Parameters:: filename (str): Output .extxyz file path. positions (np.ndarray): Shape (n_frames, n_particles, 3). species (np.ndarray, optional): Shape (n_frames, n_particles,). cells (np.ndarray, optional): Shape (n_frames, 3, 3). velocities (np.ndarray, optional): Shape (n_frames, n_particles, 3). forces (np.ndarray, optional): Shape (n_frames, n_particles, 3).

Submodules