molsysmt.molecular_mechanics.potential_energy_minimization#

molsysmt.molecular_mechanics.potential_energy_minimization(molecular_system, method='L-BFGS', platform='CPU', engine='OpenMM', to_form=None, in_place=False, verbose=False)[source]#

Relax a molecular system to a local minimum of the potential energy.

Performs energy minimization using the chosen backend optimizer. The minimized coordinates are applied either in-place to the original molecular system or to a new copy depending on the in_place flag.

Parameters:

  • molecular_system (molecular system) – Molecular system in any supported MolSysMT format.

  • method (str, default='L-BFGS') – Local minimization algorithm. OpenMM’s LocalEnergyMinimizer implements L-BFGS, so ‘L-BFGS’ is the only accepted value; any other name is refused.

  • platform (str, default='CPU') – OpenMM platform name. Accepted values are ‘CPU’ and ‘CUDA’.

  • engine (str, default='OpenMM') – Engine performing the minimization. Only ‘OpenMM’ is implemented.

  • to_form (str, default=None) – Form of the returned molecular system when in_place=False. With None the input form is preserved.

  • in_place (bool, default=False) – Whether the minimized coordinates are written into molecular_system instead of being returned in a new molecular system.

  • verbose (bool, default=False) – Whether the potential energy before and after the minimization is printed.

Returns:

When in_place=False, returns a molecular system with the minimized coordinates in the form specified by to_form (or the original form). When in_place=True, returns None and updates molecular_system in place (only applicable for non-Context/Simulation forms).

Return type:

molecular system or None

Raises:

NotImplementedError – Raised if the requested engine is not supported.

Notes

If the input is not already an openmm.Context or openmm.Simulation, the molecular system is converted to an openmm.Context using the MolSysMT default attributes for any missing molecular-mechanics parameters (forcefield, integrator, temperature, etc.).

The minimization is performed by OpenMM’s LocalEnergyMinimizer.minimize, which converges to the nearest local minimum of the force-field potential energy surface.

Added in version 1.0.0.