ParaMol.System.system module¶

Description¶

This module defines the ParaMol.System.system.ParaMolSystem class, which is a ParaMol representation of a chemical system. This object is used to store reference data such as:

coordinates,

reference energies,

reference forces,

number of atoms,

MM and QM engines,

the ParaMol.Force_field.force_field.ForceField associated with this system,

etc …

It also contains methods that aid the calculation of ensemble properties.

class ParaMol.System.system.ParaMolSystem(name, engine, n_atoms, resp_engine=None, ref_coordinates=None, ref_energies=None, ref_forces=None, ref_esp=None, ref_esp_grid=None, n_cpus=1)¶

Bases: object

ParaMol representation of a chemical system.

Parameters

name (str) – Name of the system.
n_atoms (int) – Number of atoms of the system.
engine (ParaMol.MM_engines.openmm.OpenMMEngine) – Instance of the MM engine object to be used. Currently only OpenMM is supported.
ref_coordinates (list or np.array) – (n_structures,n_atoms,3) 3D list or numpy array containing the reference coordinates.
ref_energies (list or np.array) – (n_structures) 1D list or numpy array containing the reference energies.
ref_forces (list or np.array) – (n_structures,n_atoms,3) 3D list or numpy array containing the reference forces.

Variables

name (str) – Name of the system.
n_atoms (int) – Number of atoms of the system.
weights (int or np.array) – Weight of each configuration.
wham_weights (int or np.array) – WHAM weight of each configuration. It is equal to 1 unless adaptive parametrization is being performed with WHAM reweighting.
n_structures (int) – Number of configurations.
ref_coordinates (list or np.array) – (n_structures,n_atoms,3) 3D list or numpy array containing the reference coordinates.
ref_energies (list or np.array) – (n_structures) 1D list or numpy array containing the reference energies.
ref_forces (list or np.array) – (n_structures,n_atoms,3) 3D list or numpy array containing the reference forces.
ref_esp (list or np.array) – (n_esp) 1D list or numpy array containing values of the electrostatic potential.
ref_esp_grid (list or np.array) – (n_esp,3) 2D list or numpy array containing the coordinates of the electrostatic potential grid.
engine (ParaMol.MM_engines.openmm.OpenMMEngine) – Instance of the MM engine object to be used. Currently only OpenMM is supported.
resp_engine (ParaMol.MM_engines.resp.RESP) – Instance of the RESP engine object to be used.
qm_engine (any instance of the classes defined in the modules of the subpackage ParaMol.QM_engines) – Instance of the QM engine object to be used.
interface (ParaMol.Utils.interface.ParaMolInterface) – ParaMol interface object instance.
n_cpus (int) – Number of cpus that this system uses.

append_data_to_system(conformations_list, qm_energies_list, qm_forces_list)¶

Method that appends data to the ParaMol System instance (self).

Notes

Appends conformations and/or QM energies and/or QM forces to the instance variables ref_coordinates, ref_energies and ref_forces, respectively.

Parameters

conformations_list (list or np.array) – (N,n_atoms,3) 3D list or numpy array containing the reference coordinates.
qm_energies_list (list or np.array) –
1. 1D list or numpy array containing the reference energies.
qm_forces_list (list or np.array) – (N,n_atoms,3) 3D list or numpy array containing the reference forces.

Returns

ref_coordinates, ref_energies, ref_forces (np.array, np.array, np.array)

compute_conformations_weights(temperature=None, emm=None, weighting_method='UNIFORM', manual_weights_array=None)¶

Method that calculates the weights of every configuration of the ensemble or sets them in case manual weighting is used.

Notes

For more info about the non-Boltzmann weighting see: “Communication: Hybrid ensembles for improved force matching” Lee-Ping Wang and Troy Van Voorhis J. Chem. Phys. 133, 231101 (2010) https://doi.org/10.1063/1.3519043

Parameters

temperature (simtk.unit.Quantity) – Temperature of the ensemble in Kelvin.
weighting_method (str) – Available weighting methods are “UNIFORM”, “BOLTZMANN”, “NON-BOLTZMANN”, and “MANUAL”
emm (list or np.array) – (n_structures) 1D list or numpy array containing the MM energies.
manual_weights_array (list or np.array) – (n_structures) 1D list or numpy array containing weights of the conformers.

Returns

weights (np.array) – (n_structures) 1D array containing the weight of each configuration.

convert_system_ref_arrays_to_list()¶

Method that checks the data type of the forces, energies and coordinates data structures and converts them to lists.

Parameters: system (ParaMol.System.system.ParaMolSystem) – ParaMol System instance.
Returns: ref_forces, ref_energies, ref_coordinates (list, list, list) – Forces, energies and coordinates as lists.

create_qm_engines(qm_engine_name, qm_engine_settings, interface=None, overwrite_qm_engine=False)¶

Method (top-level) that creates a QM engine for the system.

Parameters

qm_engine_name (str) – Name of the QM engine. Available QM engines are “amber”, “dftb+” and “ase”.
qm_engine_settings (dict) – Keyword arguments passed to the QM engine wrapper.
interface (ParaMol.Utils.interface.ParaMolInterface, default=None) – ParaMol interface.
overwrite_qm_engine (bool) – Flag to overwrite current QM engine, if it exists.

Returns

qm_engine (any instance of the classes defined in the modules of the subpackage ParaMol.QM_engines) – Instance of the QM engine object to be used.

energy_statistics(emm)¶

Method that calculates statistics of energies.

Parameters: emm (list) – (n_structures) 1D list containing the MM energies.
Returns: diff, rms, ratio

filter_conformations(energy_threshold)¶

Method that removes configurations for which the energy reference (QM energy) is greater than a given threshold with respect to the lowest energy of the ensemble. That is, all configurations for which the \(E-E_{min} > \delta\) are removed, where \(E_{min}\) is the lowest energy of the ensemble and \(\delta\) is the energy threshold.

Parameters: energy_threshold (float) – Energy threshold in kJ/mol.
Returns: ref_coordinates, ref_energies, ref_forces – Updated reference arrays.

force_statistics(fmm)¶

Method that calculates statistics of forces.

Parameters: fmm (list) – (n_structures,n_atoms,3) 3D list containing the MM forces.
Returns: num, denom, ratio

get_energies_ensemble()¶

Method that calculates the MM energies of the ensemble of configurations contained in the ref_coordinates attribute.

Returns: emm (list) – (n_structures) 1D list containing the MM energies.

get_esp_ensemble()¶

Method that calculates MM electrostatic potential of the ensemble of configurations contained in the ref_coordinates attribute.

Notes

This method requires that the attribute resp_engine is not None.

Returns: mm_esp (list) – (n_structures, n_esp) 2D list containing the calculated ESP values for every configuration.

get_forces_ensemble()¶

Method that calculates the MM forces of the ensemble of configurations contained in the ref_coordinates attribute.

Returns: fmm (list) – (n_structures,n_atoms,3) 3D list containing the MM forces.

read_data(input_file_name=None, append=False)¶

Method that reads coordinates, reference energies and reference forces from a NetCDF 4 (.nc) file.

Parameters

input_file_name (str) – Name of the .nc file to be read.
append – Whether to append or overwrite new data to current data.

Returns

True if file was closed successfully. False otherwise.

wham_reweighing(parameters_generation)¶

Method that performs WHAM reweighting.

Notes

For more info see the source: “Systematic Parametrization of Polarizable Force Fields from Quantum Chemistry Data” Lee-Ping Wang, Jiahao Chen, and Troy Van Voorhis J. Chem. Theory Comput. 2013, 9, 1, 452–460

Parameters: parameters_generation (list of lists) – Each inner list contains the parameters for a given generation.
Returns: wham_weights (np.array of floats) – Array with new weights.

write_coordinates_xyz(output_file_name=None, xyz_comment='comment')¶

Method that writes all stored conformations to a .xyz file.

Parameters

output_file_name (str) – Name of the .xyz file to be written.
xyz_comment (str) – Comment to be written on the header of each xyz block.

Returns

True if file was closed successfully. False otherwise.

write_data(output_file_name=None)¶

Method that writes coordinates, reference energies and reference forces to a NetCDF 4 (.nc) file.

Parameters: output_file_name (str) – Name of the .nc file to be written.
Returns: True if file was closed successfully. False otherwise.