pydft_qmmm.common.utils package

Submodules

pydft_qmmm.common.utils.lattice_utils module

A module containing helper functions accessed by multiple classes.

pydft_qmmm.common.utils.lattice_utils.compute_lattice_constants(box)

Calculate the length and angle constants from lattice vectors.

Returns the lattice constants a, b, c, alpha, beta, and gamma using a set of box vectors for a periodic triclinic system.

Parameters:

box (NDArray[np.float64]) – The lattice vectors (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

Returns:

The characteristic lengths (\(\mathrm{\mathring{A}}\)) and angles (\(\mathrm{\degree}\)) of an arbitrary triclinic box.

Return type:

tuple[float, …]

pydft_qmmm.common.utils.lattice_utils.compute_lattice_vectors(a, b, c, alpha, beta, gamma)

Calculate the lattice vectors from length and angle constants.

Parameters:

• a (float) – The first characteristic length (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

• b (float) – The second characteristic length (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

• b – The third characteristic length (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

• alpha (float) – The first characteristic angle (\(\mathrm{\degree}\)) of an arbitrary triclinic box.

• beta (float) – The second characteristic angle (\(\mathrm{\degree}\)) of an arbitrary triclinic box.

• gamma (float) – The third characteristic angle (\(\mathrm{\degree}\)) of an arbitrary triclinic box.

• c (float)

Returns:

The lattice vectors (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

Return type:

NDArray[np.float]

pydft_qmmm.common.utils.lattice_utils.compute_least_mirror(i_vector, j_vector, box)

Calculate the least mirror vector.

Parameters:

• i_vector (NDArray[np.float64]) – The position vector (\(\mathrm{\mathring{A}}\)).

• j_vector (NDArray[np.float64]) – The reference vector (\(\mathrm{\mathring{A}}\)).

• box (NDArray[np.float64]) – The lattice vectors (\(\mathrm{\mathring{A}}\)) of an arbitrary triclinic box.

Returns:

Returns the least mirror coordinates of i_vector with respect to j_vector given a set of lattice vectors from a periodic triclinic system.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils module

A module containing helper functions accessed by multiple classes.

pydft_qmmm.common.utils.misc_utils.Components

The type corresponding to the energy components determined by calculators.

pydft_qmmm.common.utils.misc_utils.SELECTORS

Pairs of VMD selection keywords and the corresponding attribute and type to check in a system.

class pydft_qmmm.common.utils.misc_utils.Results(energy=0, forces=<factory>, components=<factory>)

Bases: object

Store the results of a calculation.

Parameters:

• energy (float) – The energy (\(\mathrm{kJ\;mol^{-1}}\)) of a system determined by a calculator.

• forces (NDArray[np.float64]) – The forces (\(\mathrm{kJ\;mol^{-1}\;\mathring{A}^{-1}}\)) on a system determined by a calculator.

• componentes – The energy components (\(\mathrm{kJ\;mol^{-1}}\)) of a system determined by a calculator.

• components (Components)

components: Components

energy: float = 0

forces: NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.align_dict(dictionary)

Create a ‘flat’ version of an energy components dictionary.

Parameters:

dictionary (dict[str, Any]) – The components dictionary to flatten.

Returns:

A flattened version of the components dictionary.

Return type:

dict[str, float]

pydft_qmmm.common.utils.misc_utils.center_positions(positions, box, atoms)

Center positions about the centroid of a set of atoms.

Parameters:

• positions (NDArray[np.ndarray]) – The positions (\(\mathrm{\mathring{A}}\)) which will be centered.

• box (NDArray[np.float64]) – The lattice vectors (\(\mathrm{\mathring{A}}\)) of the box containing the system.

• atoms (frozenset[int]) – The set of atom indices whose centroid will become the center of the box.

Returns:

The new centered positions of the system.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.empty_array()

Factory method for empty arrays.

Returns:

An empty array.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.generate_velocities(masses, temperature, seed=None)

Generate velocities with the Maxwell-Boltzmann distribution.

Parameters:

• masses (NDArray[np.float64]) – The masses (\(\mathrm{AMU}\)) of particles.

• temperature (float | int) – The temperature (\(\mathrm{K}\)) of the system.

• seed (int | None) – A seed for the random number generator.

Returns:

A set of velocities (\(\mathrm{\mathring{A}\;fs^{-1}}\)) equal in number to the set of masses provided.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.lazy_load(name)

Load a module lazily, not performing execution until necessary.

Parameters:

name (str) – The name of the module to load.

Returns:

The module that has been lazily loaded.

Return type:

ModuleType

pydft_qmmm.common.utils.misc_utils.numerical_gradient(calculator, atoms, dist=0.0025, component=None)

Calculate the numerical energy gradients for a set of atoms.

Parameters:

• simulation – A simulation object used for the energy evaluations.

• atoms (frozenset[int]) – The atoms to perform numerical gradients on.

• dist (int | float) – The displacement for central differencing (\(\mathrm{\mathring{A}}\)).

• component (str | None) – The component of the energy dictionary to use in central differencing calculations.

• calculator (Calculator)

Returns:

The numerical gradients of the energy (\(\mathrm{kJ\;mol^{-1}\;\mathring{A}^{-1}}\))

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.residue_partition(atoms, positions, residue_map, atoms_metric, other_metric, cutoff)

Perform the residue-wise system partitioning.

Parameters:

• positions (NDArray[np.float64]) – The positions (\(\mathrm{\mathring{A}}\)) which will be centered.

• box – The lattice vectors (\(\mathrm{\mathring{A}}\)) of the box containing the system.

• atoms (frozenset[int]) – The set of atom indices whose centroid will become the center of the box.

• residue_map (dict[int, frozenset[int]])

• atoms_metric (Callable[[NDArray], float])

• other_metric (Callable[[NDArray], float])

• cutoff (float | int)

Return type:

list[int]

pydft_qmmm.common.utils.misc_utils.wrap_positions(positions, box, residue_map)

Wrap atom positions in accord with PBC.

Atoms are wrapped to stay inside of the periodic box. This function ensures molecules are not broken up by a periodic boundary, since OpenMM electrostatics will be incorrect if atoms in a molecule are not on the same side of the periodic box. This method currently assumes an isotropic box.

Parameters:

• positions (NDArray[np.float64]) – The positions (\(\mathrm{\mathring{A}}\)) which will be wrapped.

• box (NDArray[np.float64]) – The lattice vectors (\(\mathrm{\mathring{A}}\)) of the box containing the system.

• residue_map (dict[int, frozenset[int]]) – Sets of atom indices mapped by residue index.

Returns:

The new wrapped positions of the system.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.misc_utils.zero_vector()

Create a zero vector with three dimensions.

Returns:

An array with three dimensions of zero magnitude.

Return type:

NDArray[np.float64]

pydft_qmmm.common.utils.selection_utils module

A module containing helper functions accessed by multiple classes.

pydft_qmmm.common.utils.selection_utils.SELECTORS

Pairs of VMD selection keywords and the corresponding attribute and type to check in a system.

pydft_qmmm.common.utils.selection_utils.and_slice(line, start)

Find the slice of a query modified by the ‘and’ keyword.

Parameters:

• line (list[str]) – The atom selection query, broken into meaningful components.

• start (int) – The index of the line where the statement modified by the ‘and’ keyword begins.

Returns:

The slice whose start and stop corresponds to the phrase modified by the ‘and’ keyword.

Return type:

slice

pydft_qmmm.common.utils.selection_utils.decompose(text)

Decompose an atom selection query into meaningful components.

Parameters:

text (str) – The atom selection query.

Returns:

The atom selection query broken into meaningful parts, demarcated by keywords.

Return type:

list[str]

pydft_qmmm.common.utils.selection_utils.evaluate(text, system)

Evaluate a part of an atom selection query.

Parameters:

• text (str) – A single contained statement from an atom selection query.

• system (System) – The system whose atoms will be selected by evaluating a single query statement.

Returns:

The set of atom indices selected by the query statement.

Return type:

frozenset[int]

pydft_qmmm.common.utils.selection_utils.interpret(line, system)

Interpret a line of atom selection query language.

Parameters:

• line (list[str]) – The atom selection query, broken into meaningful components.

• system (System) – The system whose atoms will be selected by interpreting the selection query.

Returns:

The set of atom indices selected by the query.

Return type:

frozenset[int]

Note

Based on the VMD atom selection rules.

pydft_qmmm.common.utils.selection_utils.not_slice(line, start)

Find the slice of a query modified by the ‘not’ keyword.

Parameters:

• line (list[str]) – The atom selection query, broken into meaningful components.

• start (int) – The index of the line where the statement modified by the ‘not’ keyword begins.

Returns:

The slice whose start and stop corresponds to the phrase modified by the ‘not’ keyword.

Return type:

slice

pydft_qmmm.common.utils.selection_utils.or_slice(line, start)

Find the slice of a query modified by the ‘or’ keyword.

Parameters:

• line (list[str]) – The atom selection query, broken into meaningful components.

• start (int) – The index of the line where the statement modified by the ‘or’ keyword begins.

Returns:

The slice whose start and stop corresponds to the phrase modified by the ‘or’ keyword.

Return type:

slice

pydft_qmmm.common.utils.selection_utils.parens_slice(line, start)

Find the slice of a query within parentheses.

Parameters:

• line (list[str]) – The atom selection query, broken into meaningful components.

• start (int) – The index of the line where the statement within parentheses begins.

Returns:

The slice whose start and stop corresponds to the phrase contained by parentheses.

Return type:

slice

Module contents

A sub-package containing common classes, utilities, and constants.