narupa.imd.imd_force module

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

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
narupa.imd.imd_force.apply_single_interaction_force(positions: numpy.ndarray, masses: numpy.ndarray, interaction, forces: numpy.ndarray, periodic_box_lengths: Optional[numpy.array] = 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.
narupa.imd.imd_force.calculate_gaussian_force(particle_position: numpy.ndarray, interaction_position: numpy.ndarray, sigma=1, periodic_box_lengths: Optional[numpy.ndarray] = None) → Tuple[float, numpy.ndarray]

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,
  • sigma – The width of the Gaussian. Increasing this results in a more diffuse, but longer reaching interaction.
Returns:

The energy of the interaction, and the force to be applied to the particle.
narupa.imd.imd_force.calculate_imd_force(positions: numpy.ndarray, masses: numpy.ndarray, interactions: Iterable[narupa.imd.particle_interaction.ParticleInteraction], periodic_box_lengths: Optional[numpy.ndarray] = None) → Tuple[float, numpy.array]

Reference implementation of the Narupa 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.
narupa.imd.imd_force.calculate_spring_force(particle_position: numpy.array, interaction_position: numpy.array, k=1, periodic_box_lengths: Optional[numpy.ndarray] = None) → Tuple[float, numpy.array]

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.
narupa.imd.imd_force.get_center_of_mass_subset(positions: numpy.ndarray, masses: numpy.ndarray, subset: Iterable[int], periodic_box_lengths: Optional[numpy.ndarray] = None) → numpy.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.
narupa.imd.imd_force.wrap_pbc(positions: numpy.ndarray, periodic_box_lengths: numpy.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.