schrodinger.structutils.minimize module

A module for force field energy evaluation and minimization.

API examples

A non-conformer serial minimization should use the minimize function:

for st in structure.StructureReader('various_ligands.mae'):
    minimize.minimize_structure(st)
    st.append('various_ligands-mini-out.mae')

A conformer serial minimization can reduce atom-typing overhead by using the Minimizer class:

for index, st in enumerate(structure.StructureReader('conformers.mae')):
    if index == 0:
        min = minimize.Minimizer(struct=st)
    else:
        min.updateCoordinates(st)
    min.minimize()
    st = min.getStructure()
    st.append('conformers-out.mae')
class schrodinger.structutils.minimize.Minimizer(ffld_version=None, struct=None, cleanup=True, honor_pbc=True, **kwargs)

Bases: object

A class to provide force field energy and minimization.

For simple cases the minimize_structure function can be used. Direct use of this class is mostly useful for cases where multiple conformers are to be minimized, as the updateCoordinates() method allows one to avoid running atom-typing for every conformer.

addAngleRestraint(i, j, k, force_constant, target, flat_bottom=0.0)

Define an angle restraint.

Parameters:
  • j, k (i,) – atoms defining the restraint
  • force_constant (float) – force constant
  • target (float) – target value
  • flat_bottom (float) – flat-bottom half width (default 0.0)
addDistanceRestraint(i, j, force_constant, target, flat_bottom=0.0)

Define a distance restraint.

Parameters:
  • j (i,) – atoms defining the restraint
  • force_constant (float) – force constant
  • target (float) – target value
  • flat_bottom (float) – flat-bottom half width (default 0.0)
addPosFrozen(i)

Define a frozen atom.

Parameters:i (int) – atom to be frozen
addPosRestraint(i, force_constant, flat_bottom=0.0)

Define a positional restraint.

Parameters:
  • i (int) – atom defining the restraint
  • force_constant (float) – force constant
  • flat_bottom (float) – flat-bottom half width (default 0.0)
addTorsionRestraint(i, j, k, l, force_constant, target, flat_bottom=0.0)

Define a torsional restraint.

Parameters:
  • j, k, l (i,) – atoms defining the restraint
  • force_constant (float) – force constant
  • target (float) – target value
  • flat_bottom (float) – flat-bottom half width (default 0.0)
charges_from_ct

See the constructor method for documentation.

deleteAllRestraints(rest_type=0)

Delete all the restraints for a given type (default all types).

Parameters:rest_type (mm Constant) – One of: - mm.MMFfldTorsionRest - mm.MMFfldPosRest - mm.MMFfldPosFrozen - mm.MMFfldAllRestType
dielectric_constant

See the constructor method for documentation.

energy_criterion

See the constructor method for documentation.

energy_lj_repulsive_only

See the constructor method for documentation.

energy_no_electrostatics

See the constructor method for documentation.

get14EleEnergy()

get the 1,4-electrostatic energy of the system

get14LJEnergy()

get the 1,4-Lennard Jones energy of the system

getBending(ibnd)

get the bending type information and parameters

getBendingEnergy()

get the beinding energy of the system

getBondedEnergies(atom_subset)

Return bonded energies for bonded interactions within the given atom subset.

Parameters:atom_subset (List of atom indices.) – Atoms to calculate bonded energies for.
Returns:(stretch-energy, bend-energy, torsion-energy, imp-tor-energy)
Return type:tuple
getBondedEnergyComponents(stretch_item_list, bending_item_list, torsion_item_list, imp_torsion_item_list)

Get energy components for bonded terms given in an list of stretches/bend/torsions/improper torsions (given as integer numbers) in *_item_list. The *_energy_list arguments are ignored.

Returns the corresponding energies as a tuple of double lists: (stretch_energy_list, bending_energy_list, torsion_energy_list, imp_torsion_energy_list).

Atoms are counted starting at zero.

NOTE: The API of this function may change in the next release.

getBondedInteractionEnergy(atomset1, atomset2=None, verbose=False)

Return the bonded component of the interaction energy between the two given atom sets. If the second subset is not specified, instead use all other atoms from the CT.

Parameters:
  • atomset1 (List of atom indices.) – Atoms from the first subset.
  • atomset2 (List of atom indices.) – Atoms from the second subset.
Returns:

The bonded interaction energy.
Return type:

float
getEleEnergy()

get the electrostatic energy of the system

getEnergy(recalc=None)

Run a zero-step minimization to calculate the energy, and return it. Also stores the energy in the structure properties. Units are kcal/mol.

Parameters:recalc (bool) – Deprecated, and will propably go away. If previously calculated energy is needed, use the Minimizer.min_energy property.
getExcludedAtomList(iatom, excluded_atoms)

get the excluded atoms

getImpTorsion(imp_tor)

get the improper torsion type information and parameters

getImpTorsionEnergy()

get the imporoper torsion energy of the system

getInteractionEnergy(subset_atoms, consider_atoms=None, include_bonded=False, verbose=False)

Calculate the energy of interaction between the <subset_atoms> and the <consider_atoms>. If <consider_atoms> is not specified, then returns a sum of all interactions between the <subset_atoms> and the rest of the atoms.

Note that in the default case where <consider_atoms> is None, atoms outside of the cutoff are not considered.

Parameters:
  • subset_atoms (List of atom indices.) – First atom set.
  • consider_atoms (List of atom indices.) – Second atom set (optional)
  • include_bonded (Boolean.) – Whether to also include bonded terms. By default, only non-bonded interactions are included, even if the atom sets are covalently bonded, and any bonded interactions are excluded.
Returns:

Interaction energy betwen the given atom sets (or between the given atom sets and the rest of the structure).
Return type:

float
getLJEnergy()

get the Lennard Jones energy of the system

getNB14Pairs(i14pair)

get the 1,4-pair information

getNBEnergyComponents(atom_list_i, atom_list_j, nb_energy_component_list)

TODO: this API should be eliminated. This is currently called by test programs in /mmshare/mmlibs/mmffld/test/ and one could replace the use of this API by calling getInteractionEnergyComponents() see Ev:133233.

Get the non-bonded energy components for two cases:

  1. For one list of atoms given in atom_list_i and their neighbors obtained from the pairlist. In this case the atom_list_j is empty on input and on output contains all the pairs of atoms used in the calculation.
  2. For two lists of atoms ( if atom_list_j is not zero ).

Note that atom_list_j is a list (of len(atom_list_i)) of lists.

The energy components are returned in a vector of length atom_list_i of a vector (of length atom_list_j) of a vector of double which includes the following energy components:

  1. A_ij * R^-12
  2. -B_ij * R^-6
  3. Coulomb energy
  4. interatomic distance r_ij

Note that this method will require a valid product license. Currently, MacroModel, GLIDE, Impact, or PLOP will suffice.

Atoms are counted starting at zero.

getNBEnergyForTwoAtomLists(atom_list_i, atom_list_j)

Get the non-bonded energy components for two arbitrary list of atoms. The total Coulomb and LJ interaction energies are returned.

getNonBondedEnergies(atom_subset, verbose=False)

Given a list of atoms representing a substructure (e.g. a residue), return a tuple of:

  1. the sum of non-bonded energies WITHIN the set.
  2. the sum of non-bonded energies between the set atoms and everything else.
Parameters:atom_subset (list(int)) – Atoms indicies to calculate non-bonded energies for
Returns:(internal non-bonded energy in kcal/mol, non-bonded interaction energy in kcal/mol)
Return type:tuple
getOptions()

Return the values for all properties that control Minimizer behavior.

getSelfEnergy(atom_subset, include_intra_nb=True)

Return the internal energy of the the given atoms. This is the sum of all bonded interactions between the given atoms.

Parameters:
  • atom_subset (List of atom indices.) – Atoms to calculate self-energy for.
  • include_intra_nb (bool) – If True, include non-bonded interaction energy within the given subset. If False, include only bonded interactions.
Returns:

Total self-energy
Return type:

float
getStretch(istr)

get the stretch type information and parameters

getStretchEnergy()

get the stretch energy of the system

getStructure()

Return the current structure.

getSubsetEnergy(atom_subset, include_intra_nb=True, verbose=False)

Return the potential energy of the the given atoms.

It is a sum of bonded interactions within the atom set and the non-bonded interactions between the atom set and the rest of the structure (honoring the NB-cutoff). By default, the internal interaction energy is also included.

Parameters:
  • atom_subset (List of atom indices.) – Atoms to calculate energy for.
  • include_intra_nb (bool) – If True, also include non-bonded interaction energy within the given subset.
Returns:

Total energy of the subset
Return type:

float
getTorsion(itor)

get the torsion type information and parameters

getTorsionEnergy()

get the torsion energy of the system

getTotal14Pair()

get the total number of 1,4-pairs

getTotalAtom()

get the total number of atoms

getTotalBending()

get the total number of bending

getTotalEnergy()

get the total energy of the system

getTotalImpTorsion()

get the total number of improper torsion

getTotalStretch()

get the total number of stretch

getTotalTorsion()

get the total number of torsion

gradient_criterion

See the constructor method for documentation.

static initialize(error_handler=None)

Initialize needed mmlibs.

This method is called by the Minimizer constructor, so if Minimizer objects are used there is no need to explicitly call it.

maintain_planarity

See the constructor method for documentation.

max_steps

See the constructor method for documentation.

min_converged

Return 1 if last minimization converged, 0 if it didn’t.

min_energy

Return the energy calculated in the last minimization.

min_method

See the constructor method for documentation.

min_rms_gradient

Return the RMS gradient of the last minimization.

minimize()

Minimize the provided Structure. Store results as properties in the Structure.

Note that this method will require a valid product license. Currently, MacroModel, GLIDE, Impact, or PLOP will suffice.

no_zob_restrain

See the constructor method for documentation.

nonbonded_cutoff

See the constructor method for documentation.

printParameters()

Print all parameters for the entered molecules.

setLigandCleanupOptions()

Obsolete.

setOptions(**kwargs)

Set Minimizer options by keyword. To be used only internally by the constructor.

setStructure(struct)

Change the structure to be minimized.

This method generally won’t need to be called by the end user. To minimize different molecules, it is preferable to create separate Minimizer instances.

If only the coordinates of the structure changed, it is much faster to call updateCoordinates() instead of setStructure().

static terminate()

Terminate the mmlibs initialized in the initialize method.

It’s only necessary to call this method if you want to free resources used by the underlying lib.

Note that this terminate method isn’t automatically called in the __del__ method of Minimizer. This is because there is significant overhead to reading the force field data and it won’t be re-read as long as the library reference count is greater than zero.

updateCoordinates(struct)

Update the coordinates of the current structure with the values from the provided struct.

This allows an additional conformer to be minimized without re-running atomtyping. It is the caller’s responsibility to make sure the molecules are equivalent and have the same atomtypes (i.e. same charges, connectivity).

verbose

See the constructor method for documentation.

schrodinger.structutils.minimize.get_converged(struct, ffld_version)

Return the converged status for a Structure.

Parameters:ffld_version – One of the valid force fields from mmcommon_get_valid_forcefields()
schrodinger.structutils.minimize.get_energy(struct, ffld_version)

Return the force field energy for a Structure. Units are kcal/mol.

Parameters:ffld_version – One of the valid force fields from mmcommon_get_valid_forcefields()
schrodinger.structutils.minimize.get_rms_gradient(struct, ffld_version)

Return the RMS of derivatives from force field minimization for a Structure.

Parameters:ffld_version – One of the valid force fields from mmcommon_get_valid_forcefields()
schrodinger.structutils.minimize.initialize(error_handler=None)

Initialize needed mmlibs.

This method is called by the Minimizer constructor, so if Minimizer objects are used there is no need to explicitly call it.

schrodinger.structutils.minimize.minimize_structure(struct, ffld_version=None, cleanup=True, **kwargs)

Minimize the provided structure.

Additional keyword arguments will be used to set properties of the Minimizer instance. See the Minimizer.__init__() method for supported property names.

Parameters:
  • ffld_version (integer module constant) – The force field to use. Default is to use the force field that is selected in Maestro preferences.
  • cleanup (bool) – If True, attempts to automatically clean up the structure will be made. (This uses the C function mmlewis_apply().) Note that this can modify the atom types of the passed in structure.
  • kwargs – Additional keyword arguments.
schrodinger.structutils.minimize.terminate()

Terminate the mmlibs initialized in the initialize method.

It’s only necessary to call this method if you want to free resources used by the underlying lib.

Note that this terminate method isn’t automatically called in the __del__ method of Minimizer. This is because there is significant overhead to reading the force field data and it won’t be re-read as long as the library reference count is greater than zero.