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

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