emle.calculator

The calculator module contains a calculator for computing energies and gradients. This is used by the emle-engine script to compute energies and gradients when interfacing with sander. The calculator can also be used by Sire to interface with OpenMM.

class emle.calculator.EMLECalculator(model=None, method='electrostatic', alpha_mode='species', atomic_numbers=None, qm_charge=0, backend='torchani', external_backend=None, plugin_path='.', mm_charges=None, deepmd_model=None, deepmd_deviation=None, deepmd_deviation_threshold=None, qm_xyz_file='qm.xyz', pc_xyz_file='pc.xyz', qm_xyz_frequency=0, ani2x_model_index=None, mace_model=None, ace_model=None, rascal_model=None, parm7=None, qm_indices=None, orca_path=None, sqm_theory='DFTB3', lambda_interpolate=None, interpolate_steps=None, restart=False, device=None, orca_template=None, energy_frequency=0, energy_file='emle_energy.txt', log_level='ERROR', log_file=None, save_settings=False)[source]

Predicts EMLE energies and gradients allowing QM/MM with ML electrostatic embedding. Requires the use of a QM (or ML) engine to compute in vacuo energies and gradients, to which those from the EMLE model are added. Supported backends are listed in the _supported_backends attribute below.

Constructor

Parameters:

  • model (str) – Path to the EMLE embedding model parameter file. If None, then a default model will be used.

  • method (str) –

    The desired embedding method. Options are:
    ”electrostatic”:

    Full ML electrostatic embedding.

    ”mechanical”:

    ML predicted charges for the core, but zero valence charge.

    ”nonpol”:

    Non-polarisable ML embedding. Here the induced component of the potential is zeroed.

    ”mm”:

    MM charges are used for the core charge and valence charges are set to zero. If this option is specified then the user should also specify the MM charges for atoms in the QM region.

  • backend (str, Tuple[str]) – The backend to use to compute in vacuo energies and gradients. If None, then no backend will be used, allowing you to obtain the electrostatic embedding energy and gradients only. If two backends are specified, then the second can be used to apply delta-learning corrections to the energies and gradients.

  • alpha_mode (str) –

    How atomic polarizabilities are calculated.
    ”species”:

    one volume scaling factor is used for each species

    ”reference”:

    scaling factors are obtained with GPR using the values learned for each reference environment

  • atomic_numbers (List[int], Tuple[int], numpy.ndarray) – Atomic numbers for the QM region. This allows use of optimised AEV symmetry functions from the NNPOps package. Only use this option if you are using a fixed QM region, i.e. the same QM region for each call to the calculator.

  • qm_charge (int) – The charge on the QM region. This is required when using an EMLECalculator instance with the OpenMM interface. When using the sander interface, the QM charge will be taken from the ORCA input file.

  • external_backend (str) – The name of an external backend to use to compute in vacuo energies. This should be a callback function formatted as ‘module.function’. The function should take a single argument, which is an ASE Atoms object for the QM region, and return the energy in Hartree along with the gradients in Hartree/Bohr as a numpy.ndarray.

  • plugin_path (str) – The direcory containing any scripts used for external backends.

  • mm_charges (List, Tuple, numpy.ndarray, str) – An array of MM charges for atoms in the QM region. This is required when the embedding method is “mm”. Alternatively, pass the path to a file containing the charges. The file should contain a single column. Units are electron charge.

  • deepmd_model (str) – Path to the DeePMD model file to use for in vacuo calculations. This must be specified if “deepmd” is the selected backend.

  • deepmd_deviation (str) – Path to a file to write the max deviation between forces predicted with the DeePMD models.

  • deepmd_deviation_threshold (float) – The threshold for the maximum deviation between forces predicted with the DeePMD models. If the deviation exceeds this value, a ValueError will be raised and the calculation will be terminated.

  • qm_xyz_file (str) – Path to an output file for writing the xyz trajectory of the QM region.

  • pc_xyz_file (str) – Path to an output file for writing the charges and positions of the MM point charges.

  • qm_xyz_frequency (int) – How often to write the xyz trajectory of the QM and MM regions. Zero turns off writing.

  • ani2x_model_index (int) – The index of the ANI model to use when using the TorchANI backend. If None, then the full 8 model ensemble is used.

  • mmace_model (str) – Name of the MACE-OFF23 models to use. Available models are ‘mace-off23-small’, ‘mace-off23-medium’, ‘mace-off23-large’. To use a locally trained MACE model, provide the path to the model file. If None, the MACE-OFF23(S) model will be used by default.

  • ace_model (str) – Path to the ACE model file to use for in vacuo calculations. This must be specified if ‘ace’ is the selected backend.

  • rascal_model (str) – Path to the Rascal model file to use for in vacuo calculations. This must be specified if “rascal” is the selected backend.

  • lambda_interpolate (float, [float, float]) – The value of lambda to use for end-state correction calculations. This must be between 0 and 1, which is used to interpolate between a full MM and EMLE potential. If two lambda values are specified, the calculator will gradually interpolate between them when called multiple times. This must be used in conjunction with the ‘interpolate_steps’ argument.

  • interpolate_steps (int) – The number of steps over which lambda is linearly interpolated.

  • parm7 (str) – The path to an AMBER parm7 file for the QM region. This is needed to compute in vacuo MM energies for the QM region when using the Rascal backend, or when interpolating.

  • qm_indices (list, str) – A list of atom indices for the QM region. This must be specified when interpolating. Alternatively, a path to a file containing the indices can be specified. The file should contain a single column with the indices being zero-based.

  • orca_path (str) – The path to the ORCA executable. This is required when using the ORCA backend.

  • sqm_theory (str) – The QM theory to use when using the SQM backend. See the AmberTools manual for the supported theory levels for your version of AmberTools.

  • restart (bool) – Whether this is a restart simulation with sander. If True, then energies are logged immediately.

  • device (str) – The name of the device to be used by PyTorch. Options are “cpu” or “cuda”.

  • orca_template (str) –

    The path to a template ORCA input file. This is required when using the ORCA backend when using emle-engine with Sire. This should be a full template, including the charge and multiplicity of the QM region, along with a placeholder name for the xyz file that will be replaced with the file generated at runtime, e.g.:

    %pal nprocs 4 end !BLYP 6-31G* verytightscf %method grid 4 finalgrid 6 end %scf maxiter 100 end %MaxCore 1024 ! ENGRAD ! Angs NoUseSym *xyzfile 0 1 inpfile.xyz

  • energy_frequency (int) – The frequency of logging energies to file. If 0, then no energies are logged.

  • energy_file (str) – The name of the file to which energies are logged.

  • log_level (str) – The logging level to use. Options are “TRACE”, “DEBUG”, “INFO”, “WARNING”, “ERROR”, and “CRITICAL”.

  • log_file (str) – The name of the file to which log messages are written.

  • save_settings (bool) – Whether to write a YAML file containing the settings used to initialise the calculator.

run(path=None)[source]

Calculate the energy and gradients.

Parameters:

path (str) – Path to the working directory of the sander process.

set_lambda_interpolate(lambda_interpolate)[source]

Set the value of the lambda interpolation parameter. Note the server must already be in ‘interpolation’ mode, i.e. the user must have specified an initial value for ‘lambda_interpolate’ in the constructor.

Parameters:

lambda_interpolate (float, [float, float]) – The value of lambda to use for interpolating between pure MM (lambda=0) and ML/MM (lambda=1) potentials.and. If two lambda values are specified, the calculator will gradually interpolate between them when called multiple times.