Tasks.torsions_scan module

Description

This module defines the ParaMol.Tasks.torsions_scan.TorsionScan class, which is a ParaMol task that performs torsions scans.

class ParaMol.Tasks.torsions_scan.TorsionScan

Bases: ParaMol.Tasks.task.Task

ParaMol implementation of torsion scans.

Variables

  • qm_energies_list (list) – Array containing the QM energies of the scan.

  • mm_energies_list (list) – Array containing the MM energies of the scan.

  • qm_forces_list (list) – List containing the QM Forces of the scan.

  • conformations_list (list) – List containing the conformations of the scan.

  • scan_angles (list of float) – Array containing the dihedral angles scanned so far.

static freeze_atoms(system, atom_list)

Method that freezes atoms in atom_list of an OpenMM system.

Notes

This methods sets the mass of the atoms in atom_list to 0 by changing the OpenMM system.

Parameters

  • system (simtk.openmm.System) – Instance of a OpenMM System.

  • atom_list (list of int) – List containing indices of the atoms to bre frozen

Returns

system (ParaMol.System.system.ParaMolSystem) – Updated instance of OpenMM System.

static freeze_torsions(system, torsions_to_freeze, torsions_angles, k)

Method that freezes the torsion_to_freeze torsion of an OpenMM system by adding a restraint to it.

Parameters

  • system (simtk.openmm.System) – Instance of a OpenMM System.

  • torsions_to_freeze (list of lists of int) – List of lists containing indices of the atoms to be frozen

  • torsions_angles (list of float) – List of values of the desired torsion angle in degrees.

  • k (float) – Value of the force constant to be applied in kilojoules/mole.

Notes

This method should be called before creating a Context. If a Context was already created, it should be re-initialized. It works by creating a CustomTorsionForce that fixes the desired torsion. The energy expression of the CustomTorsionForce is:

\[F=-k*\cos( heta- heta_0)\]

where \(k\) is the force constant of the restraint and :math:` heta_0` is the chosen torsion angle value.

Returns

system (ParaMol.System.system.ParaMolSystem) – Updated instance of OpenMM System with an extra CustomTorsionForce that freezes the desired torsion.

static get_mm_relaxed_conformations(system, torsions_to_freeze, tolerance=0.01, max_iter=0, force_constant=9999999.0, threshold=0.01)
Parameters

  • system (ParaMol.System.system.ParaMolSystem) – ParaMol system instance.

  • torsions_to_freeze (list of list of int) – List of lists of wherein each inner list should contain 4 integers defining a torsion to be kept fixed.

  • tolerance (float) – Specifies how precisely the energy minimum must be located. Minimization will be halted once the root-mean-square value of all force components reaches this tolerance.

  • max_iter (int) – Maximum number of iterations to perform. If this is 0, minimation is continued until the results converge without regard to how many iterations it takes. The default value is 0.

  • force_constant (float) – Force constant for the dihedral restrain (kJ/mol).

  • threshold (float) – Conservation angle threshold.

Notes

This method overwrites the ref_coordinates attribute of the system object. Hence, use this with care.

Returns

mm_relaxed_conformations (np.array, shape=(n_conformations,n_atoms,3)) – MM-relaxed conformations.

static get_rdkit_mol_conf(system, pdb_file_name='temp_file.pdb')

Method that creates and returns a RDKit Conformer instance and a RDKit Molecule instance of the ParaMol system passed as an argument.

Parameters

  • system (ParaMol.System.system.ParaMolSystem) – ParaMol system instance.

  • pdb_file_name (str) – Name of the temporary .pdb file to be written (the default is “temp_file.pdb”)

Notes

This methods requires writing of a .pdb file from which the RDKit molecule will be constructed.

Returns

mol, conf (rdkit.Chem.rdchem.Mol, rdkit.Chem.rdchem.Conformer) – Tuple containing the RDKit Molecule and the RDKit conformer.

run_task(settings, systems, torsions_to_scan, scan_settings, interface=None, torsions_to_freeze=None, ase_constraints=None, optimize_qm=True, optimize_qm_before_scan=False, optimize_mm=False, optimize_mm_before_scan=False, optimize_mm_type='freeze_atoms', sampling=False, rotate_from_initial=False, n_structures_to_sample=1, dihedral_conservation_threshold=0.01, mm_opt_force_constant=99999.0, mm_opt_tolerance=1.0, mm_opt_max_iter=0, rdkit_conf=None, restart=False)

Method that performs 1D or 2D torsional scans. Only a scan at a time.

Notes

Only one ParaMol system is supported at once. Initially a QM engine is initiated for every system in systems. Then for every system in systems a RDKit molecule is created. The 1D or 2D torsional scan is performed for the torsion(s) in torsions_to_scan with the correspondent settings defined in scan_settings. The torsions defined in torsions_to_freeze are frozen.

Parameters

  • settings (dict) – Dictionary containing global ParaMol settings.

  • systems (list of ParaMol.System.system.ParaMolSystem) – List containing instances of ParaMol systems.

  • torsions_to_scan (list of list of int) – List of lists wherein the most inner list should contain 4 integers defining the torsions to be scanned in a 1D or 2D torsion scan Example: 1D-Scan [ [1,2,3,4] ]; 2D-Scan [ [1,2,3,4],[5,6,7,8] ]

  • scan_settings (list of list of float) – List of lists wherein each the most inner list should contain 3 floats defining the settings of the scan in the to be performed and in the following order: lower torsion angle, upper torsion angle, angle step (in degrees). Example: 1D-Scan [ [180.0,-180.0,-10.0] ]; 2D-Scan [ [180.0,-180.0,-10.0],[60.0,-180.0,-10.0] ]

  • interface (ParaMol.Utils.interface.ParaMolInterface) – ParaMol system instance.

  • torsions_to_freeze (list of list of int) – List of lists of wherein each inner list should contain 4 integers defining a torsion to be kept fixed (default is None)

  • ase_constraints (list of ASE constraints.) – List of ASE constraints to be applied during the scans (default is None)

  • optimize_qm (bool) – Flag that controls whether a QM geometry optimization is performed (default is True).

  • optimize_qm_before_scan (bool) – Flag that controls whether a QM geometry optimization is performed before the scan (default is False).

  • optimize_mm (bool) – Flag that controls whether a MM geometry optimization is performed (before every QM optimization, default is False).

  • optimize_mm_before_scan (bool) – Flag that controls whether a MM geometry optimization is performed before the scan (default is False).

  • optimize_mm_type (str) – Constraint to be used when performing MM optimization. Available options are ‘freeze_atoms’ or ‘freeze_dihedral’. ‘freeze_atoms’ is recommended.

  • sampling (bool) – Indicates whether to perform sampling at each dihedral angle value using an ASE integrator (default is False).

  • rotate_from_initial (bool) – Flag whether to perform rotation using initial structure or the last structure.

  • n_structures_to_sample (int) – If sampling is True, sets the number of structures to sample for each dihedral angle value (default is 1).

  • dihedral_conservation_threshold (float) – Threshold that control how much the dihedrals are allow to vary when applying constraints.

  • mm_opt_force_constant (float) – Only used if optimize_mm is True and optimize_mm_type is ‘freeze_dihedral’. Force constant for the dihedral harmonic restrain (kJ/mol).

  • mm_opt_tolerance (float) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. This specifies how precisely the energy minimum must be located. Minimization will be halted once the root-mean-square value of all force components reaches this tolerance.

  • mm_opt_max_iter (int) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. The maximum number of iterations to perform. If this is 0, minimation is continued until the results converge without regard to how many iterations it takes.

  • rdkit_conf (list of rdkit.Chem.rdchem.Conformer) – List of RDKit conformer for each system. It should be provided with the desired starting conformation.

  • restart (bool) – Flag that controls whether or not to perform a restart.

Returns

systems (list) – List with the updated instances of ParaMol System.

scan_1d(interface, restart_settings, system, rdkit_conf, torsion_to_scan, torsions_to_freeze, scan_settings, optimize_qm, optimize_qm_before_scan, optimize_mm, optimize_mm_before_scan, optimize_mm_type, ase_constraints, sampling, rotate_from_initial, n_structures_to_sample, threshold, mm_opt_force_constant, mm_opt_tolerance, mm_opt_max_iter, restart)

Method that performs 1-dimensional torsional scans.

Parameters

  • interface (ParaMol.Utils.interface.ParaMolInterface) – ParaMol system instance.

  • restart_settings (dict) – Dictionary containing restart ParaMol settings.

  • system (ParaMol.System.system.ParaMolSystem) – Instance of a ParaMol System.

  • rdkit_conf (rdkit.Chem.rdchem.Conformer) – RDKit conformer.

  • torsion_to_scan (list of int) – List containing the indices of the quartet of atoms that define the torsion to be scanned.

  • torsions_to_freeze (list of list of int) – List containing lists of the indices of the quartets of atoms to be frozen.

  • scan_settings (list) – List containing the settings of the scan in the following order: lower torsion angle, upper torsion angle, angle step (in degrees).

  • optimize_qm (bool) – Flag that controls whether a QM geometry optimization is performed (default is True). Note that the QM optimization is done after the MM optimization and therefore it inherits any structure obtained in the MM optimization.

  • optimize_qm_before_scan (bool) – Flag that controls whether a QM geometry optimization is performed before the scan.

  • optimize_mm (bool) – Flag that controls whether a MM geometry optimization is performed before every QM optimization.

  • optimize_mm_before_scan (bool) – Flag that controls whether a MM geometry optimization is performed before the scan.

  • optimize_mm_type (str) – Constraint to be used when performing MM optimization. Available options are ‘freeze_atoms’ or ‘freeze_dihedral’.

  • ase_constraints (list of ASE constraints.) – List of ASE constraints to be applied during the scans.

  • rotate_from_initial (bool) – Flag whether to perform rotation using initial structure or the last structure.

  • sampling (bool) – Indicates whether to perform sampling at each dihedral angle value using an ASE integrator.

  • n_structures_to_sample (int) – If sampling is True, sets the number of structures to sample for each dihedral angle value.

  • threshold (float) – Conservation angle threshold.

  • mm_opt_force_constant (float) – Only used if optimize_mm is True and optimize_mm_type is ‘freeze_dihedral’. Force constant for the dihedral restrain (kJ/mol).

  • mm_opt_tolerance (float) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. This specifies how precisely the energy minimum must be located. Minimization will be halted once the root-mean-square value of all force components reaches this tolerance.

  • mm_opt_max_iter (int) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. The maximum number of iterations to perform. If this is 0, minimation is continued until the results converge without regard to how many iterations it takes.

  • restart (bool) – Flag that controls whether or not to perform a restart.

Returns

qm_energies_list, qm_forces_list, mm_energies_list, conformations_list, scan_angles

scan_2d(interface, restart_settings, system, rdkit_conf, torsion_to_scan_1, torsion_to_scan_2, torsions_to_freeze, scan_settings_1, scan_settings_2, optimize_qm, optimize_qm_before_scan, optimize_mm, optimize_mm_before_scan, optimize_mm_type, ase_constraints, rotate_from_initial, threshold, mm_opt_force_constant, mm_opt_tolerance, mm_opt_max_iter, restart)

Method that performs 2-dimensional torsional scans.

Parameters

  • interface (ParaMol.Utils.interface.ParaMolInterface) – ParaMol system instance.

  • restart_settings (dict) – Dictionary containing restart ParaMol settings.

  • system (ParaMol.System.system.ParaMolSystem) – Instance of a ParaMol System.

  • rdkit_conf (rdkit.Chem.rdchem.Conformer) – RDKit conformer

  • torsion_to_scan_1 (list of int) – List containing the indices of the quartet of atoms that define the torsion 2 to be scanned.

  • torsion_to_scan_2 (list of int) – List containing the indices of the quartet of atoms that define the torsion 1 to be scanned.

  • torsions_to_freeze (list of list of int) – List containing lists of the indices of the quartets of atoms to be frozen.

  • scan_settings_1 (list of float) – List containing the settings of the scan of torsion 1 in the following order: lower torsion angle, upper torsion angle, angle step (in degrees).

  • scan_settings_2 (list of float) – List containing the settings of the scan of torsion 1 in the following order: lower torsion angle, upper torsion angle, angle step (in degrees).

  • optimize_qm (bool) – Flag that controls whether a QM geometry optimization is performed (default is True). Note that the QM optimization is done after the MM optimization and therefore it inherits any structure obtained in the MM optimization.

  • optimize_qm_before_scan (bool) – Flag that controls whether a QM geometry optimization is performed before the scan.

  • optimize_mm (bool) – Flag that controls whether a MM geometry optimization is performed before the scan. In case this is argument is set to True and optimize_qm_before_scan is also set to True, the MM optimization precedes the QM optimization.

  • optimize_mm_before_scan (bool) – Flag that controls whether a QM geometry optimization is performed before the scan.

  • optimize_mm_type (str) – Constraint to be used when performing MM optimization. Available options are ‘freeze_atoms’ or ‘freeze_dihedral’.

  • ase_constraints (list of ASE constraints.) – List of ASE constraints to be applied during the scans.

  • rotate_from_initial (bool) – Flag whether to perform rotation using initial structure or the last structure.

  • threshold (float) – Conservation angle threshold.

  • mm_opt_force_constant (float) – Only used if optimize_mm is True and optimize_mm_type is ‘freeze_dihedral’. Force constant for the dihedral restrain (kJ/mol).

  • mm_opt_tolerance (float) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. This specifies how precisely the energy minimum must be located. Minimization will be halted once the root-mean-square value of all force components reaches this tolerance.

  • mm_opt_max_iter (int) – Only used if optimize_mm is True. Argument for LocalEnergyMinimizer. The maximum number of iterations to perform. If this is 0, minimation is continued until the results converge without regard to how many iterations it takes.

  • restart (bool) – Flag that controls whether or not to perform a restart.

Returns

qm_energies_list, qm_forces_list, mm_energies_list, conformations_list, scan_angles

static set_positions_rdkit_conf(rdkit_conf, positions)

Method that sets the given positions in the given RDKit conformer.

Parameters

  • rdkit_conf (rdkit.Chem.rdchem.Conformer) – RDKit conformer.

  • positions (list or np.array) – Position array.

Returns

rdkit_conf (rdkit.Chem.rdchem.Conformer) – RDKit conformer.

static set_zero(system, rotatable_bonds)

Method that modifies the ForceField of a ParaMol System so that the values of the force constants of torsions for which the inner atoms form rotatable (soft) bonds are set to 0.0

Parameters

  • system (ParaMol.System.system.ParaMolSystem) – Instance of ParaMol System.

  • rotatable_bonds (list of lists of ints) – Lists that contains lists with pairs of atoms’s indices.

Returns

system (ParaMol.System.system.ParaMolSystem) – Instance of ParaMol System with updated ForceField.

static write_scan_data(scan_angles, qm_energies, file_name, scan_dim)

Method that writes human-readable scan data to .dat file.

Parameters

  • scan_angles (list) – List containing the set of angles for which the scan was performed.

  • qm_energies (list) – List containing the QM energy value for a given angle.

  • file_name (str) – Name of the file to be written.

  • scan_dim (int) – Dimension of the torsional scan.

Returns

None