nanover.imd.imd_force module

Provides a reference implementation of the IMD forces used by NanoVer.

For details, and if you find these functions helpful, please cite [1].

[1]

M. O’Connor et al, “An open-source multi-person virtual reality framework for interactive molecular dynamics: from quantum chemistry to drug binding”, arXiv:1902.01827, 2019

class nanover.imd.imd_force.ForceCalculator(*args, **kwargs)

Bases: Protocol

nanover.imd.imd_force.apply_single_interaction_force(positions: ndarray[Any, dtype[_ScalarType_co]], masses: ndarray[Any, dtype[_ScalarType_co]], interaction, forces: ndarray[Any, dtype[_ScalarType_co]], periodic_box_lengths: ndarray[Any, dtype[_ScalarType_co]] | None = None) → float

Calculates the energy and adds the forces to the particles of a single application of an interaction potential.

Parameters:

• positions – Collection of N particle position vectors, in nm.

• masses – Collection on N particle masses, in a.m.u.

• interaction – An interaction to be applied.

• forces – Array of N force vectors to accumulate computed forces into (in kJ/(mol*nm)).

• periodic_box_lengths – Orthorhombic periodic box lengths to use to apply minimum image convention.

Returns:

energy in kJ/mol.

nanover.imd.imd_force.calculate_constant_force(particle_position: ndarray[Any, dtype[_ScalarType_co]], interaction_position: ndarray[Any, dtype[_ScalarType_co]], periodic_box_lengths: ndarray[Any, dtype[_ScalarType_co]] | None = None) → Tuple[float, ndarray[Any, dtype[_ScalarType_co]]]

Applies a constant force that is independent of the distance between the particle and the interaction site. Applies no force when the two overlap.

Parameters:

• particle_position – The position of the particle.

• interaction_position – The position of the interaction.

• periodic_box_lengths – Vector of periodic boundary lengths.

Returns:

The energy of the interaction, and the force to be applied to the particle.

nanover.imd.imd_force.calculate_contribution_to_work(forces: ndarray[Any, dtype[_ScalarType_co]], positions: ndarray[Any, dtype[_ScalarType_co]])

The expression for the work done on the system by the user is

\[W = \sum_{t = 1}^{n_{steps}} \sum_{i = 1}^{N} \mathbf{F}_{i}(t - 1) \cdot (\mathbf{r}_{i}(t) - \mathbf{r}_{i}(t - 1)))\]

which can be rewritten as

\[W = \sum_{t = 1}^{n_{steps}} \bigg( \sum_{i = 1}^{N} \mathbf{F}_{i}(t - 1) \cdot \mathbf{r}_{i}(t) \bigg) - \bigg( \sum_{i = 1}^{N} \mathbf{F}_{i}(t - 1) \cdot \mathbf{r}_{i}(t - 1) \bigg)\]

where the contribution at each value of t is separated into an previous-step contribution (t-1) and an on-step contribution (t). Doing so enables calculation of the work done on-the-fly without having to save the positions of the atoms at each time step that the user applies an iMD force.

This function calculates the contribution to the work done on the system by the user for a set of forces and positions, and add it to the work done on the system. Only involves the atoms affected by the user interaction.

Parameters:

• forces – Array of user forces acting on the system (in NanoVer units of force, i.e. kJ mol-1 nm-1)

• positions – Array of atomic positions of the atoms on which the user forces act (in NanoVer units, i.e. nm)

Return work_done_contribution:

the contribution to the work done on the system (in NanoVer units of energy, i.e. kJ mol-1)

nanover.imd.imd_force.calculate_gaussian_force(particle_position: ndarray[Any, dtype[_ScalarType_co]], interaction_position: ndarray[Any, dtype[_ScalarType_co]], periodic_box_lengths: ndarray[Any, dtype[_ScalarType_co]] | None = None) → Tuple[float, ndarray[Any, dtype[_ScalarType_co]]]

Computes the interactive Gaussian force.

The force applied to the given particle position is determined by the position of a Gaussian centered on the interaction position.

Parameters:

• particle_position – The position of the particle.

• interaction_position – The position of the interaction.

• periodic_box_lengths – The periodic box vectors. If passed,

Returns:

The energy of the interaction, and the force to be applied to the particle.

nanover.imd.imd_force.calculate_imd_force(positions: ndarray[Any, dtype[_ScalarType_co]], masses: ndarray[Any, dtype[_ScalarType_co]], interactions: Iterable[ParticleInteraction], periodic_box_lengths: ndarray[Any, dtype[_ScalarType_co]] | None = None) → Tuple[float, ndarray[Any, dtype[_ScalarType_co]]]

Reference implementation of the NanoVer IMD force.

Given a collection of interactions, particle positions and masses, computes the force to be applied to each particle for each interaction and accumulates them into an array.

Parameters:

• positions – Array of N particle positions, in nm, with shape (N,3).

• masses – Array of N particle masses, in a.m.u, with shape (N,).

• interactions – Collection of interactions to be applied.

• periodic_box_lengths – Orthorhombic periodic box lengths. If given, the minimum image convention is applied to the calculation.

Returns:

energy in kJ/mol, accumulated forces (in kJ/(mol*nm)) to be applied.

nanover.imd.imd_force.calculate_spring_force(particle_position: ndarray[Any, dtype[_ScalarType_co]], interaction_position: ndarray[Any, dtype[_ScalarType_co]], periodic_box_lengths: ndarray[Any, dtype[_ScalarType_co]] | None = None) → Tuple[float, ndarray[Any, dtype[_ScalarType_co]]]

Computes the interactive harmonic potential (or spring) force.

The force applied to the given particle position is determined by placing a spring between the particle position and the interaction, and pulling the particle towards the interaction site.

Parameters:

• particle_position – The position of the particle.

• interaction_position – The position of the interaction.

• k – The spring constant. A higher value results in a stronger force.

• periodic_box_lengths – Vector of periodic boundary lengths.

Returns:

The energy of the interaction, and the force to be applied to the particle.

nanover.imd.imd_force.get_center_of_mass_subset(positions: ndarray, masses: ndarray, subset: Iterable[int], periodic_box_lengths: ndarray | None = None) → ndarray

Gets the center of mass of [a subset of] positions. If orthorhombic periodic box lengths are given, the minimal image convention is applied, wrapping the subset into the periodic boundary before calculating the center of mass.

Parameters:

• positions – List of N vectors representing positions.

• masses – List of N vectors representing masses.

• subset – Indices [0,N) of positions to include. If None, all positions included.

• periodic_box_lengths – Orthorhombic periodic box lengths to wrap positions into before calculating centre of mass.

Returns:

The center of mass of the subset of positions.

nanover.imd.imd_force.get_sparse_forces(user_forces: ndarray[Any, dtype[_ScalarType_co]]) → Tuple[ndarray[Any, dtype[_ScalarType_co]], ndarray[Any, dtype[_ScalarType_co]]]

Takes in an array of user forces acting on the system containing N particles and outputs two arrays that describe these user forces in a sparse form:

• The first contains the indices of the particles for which the user forces are non-zero

• The second contains the non-zero user forces associated with each index

Parameters:

user_forces – Array of user forces with dimensions (N, 3)

Returns:

Array of particle indices, Array of corresponding user forces

nanover.imd.imd_force.wrap_pbc(positions: ndarray, periodic_box_lengths: ndarray)

Wraps a list of positions into the given orthorhombic periodic box.

Parameters:

• positions – List of N vectors with shape (N,3).

• periodic_box_lengths – Box lengths of a periodic box positioned at the origin.

Returns:

Positions wrapped into the minimum image of the orthorhombic periodic box.