Hybrid Engine Options¶

Sub-engines and EngineIDs¶

Inside the Hybrid engine input block one or more sub-engine blocks can be defined. These have exactly the same format as regular engine blocks. There is, however, one extra feature: the EngineId. Optionally, a unique name can be added to the engine definition as an extra string, serving as an identifier. By default the identifier is simply the engine name. The extra string allows the user to select the same engine multiple times, each time with different settings.

This is an example, where we use the same engine (ADF) with two different spin polarizations, using results corresponding to the lowest energy.

Engine Hybrid
    Energy # we want results from the engine that yields the lowest energy to be this engine's result
       DynamicFactors UseLowestEnergy
       # The user-supplied factors are irrelevant here so we omit them
       Term EngineId=adf-singlet Region=*
       Term EngineId=adf-triplet Region=*
    End

    Engine ADF adf-singlet   # here adf-singlet is the EngineID
      SpinPolarization 0
      Unrestricted False
    EndEngine

    Engine ADF adf-triplet
      SpinPolarization 2
      Unrestricted True
    EndEngine

EndEngine

EngineIDs are for instance used in the technical example QUILD, which tests that EngineIDs are case-insensitive.

Engine header

Engine

Type: Block
Recurring: True
Description: The input for the computational (sub) engine. The header of the block determines the type of the engine. An optional second word in the header serves as the EngineID, if not present it defaults to the engine name. Currently it is not allowed to have a Hybrid engine as a sub engine.

Linear Combination of Energy Terms¶

The block Energy triggers a QUILD-like setup, allowing the energy to be defined as a linear combination of energy terms. Each energy term can be computed with a different engine.

See the basic QUILD example. As you can see capping can be enabled per energy term, and the user can set a charge per term (for the corresponding region).

Energy
   DynamicFactors [Default | UseLowestEnergy | UseHighestEnergy]
   Term
      Charge float
      EngineID string
      Factor float
      Region string
      UseCappingAtoms Yes/No
   End
End

Energy

Type: Block
Description: This block is there to construct the energy.

DynamicFactors

Type: Multiple Choice
Default value: Default
Options: [Default, UseLowestEnergy, UseHighestEnergy]
GUI name: Adjust factors
Description: Default - use factors as set in the corresponding Term blocks; UseLowestEnergy - set all factors to 0 except for that of the engine with the lowest energy, which is set to 1; UseHighestEnergy - set all factors to 0 except for that of the engine with the highest energy, which is set to 1. The last two options make sense only for non-QMMM hybrid calculation (that is, if the QMMM block is not present) and only when using engines whose energies can be compared directly.

Term

Type: Block
Recurring: True
Description: This block is there to construct the energy term. Can have multiple occurrences

Charge

Type: Float
Default value: 0.0
Description: Net charge to be used for this energy term.

EngineID

Type: String
Description: Identifier for the engine

Factor

Type: Float
Default value: 1.0
Description

Region

Type: String
Description: Identifier for the region

UseCappingAtoms

Type: Bool
Default value: Yes
Description: Whether to use capping for broken bonds

QM/MM¶

The alternative to the Energy block is the QMMM block, which triggers a two-layer computation. The embedding type can be selected with the Embedding key, for which mechanical or electrostatic can be selected. The former option triggers a specific linear combination of three energy terms, and can therefore also be set up using the Energy block (see basic QUILD example).

See the basic electrostatic embedding example. Capping can be disabled, and charges can be set for the QM and MM regions.

QMMM
   Embedding [Mechanical | Electrostatic]
   MMCharge float
   MMEngineID string
   QMCharge float
   QMEngineID string
   QMRegion string
   UseCappingAtoms Yes/No
End

QMMM

Type: Block
Description: This block is there to identify the QMMM engines.

Embedding

Type: Multiple Choice
Default value: Electrostatic
Options: [Mechanical, Electrostatic]
Description: Determines how the QM region is embedded into the MM region. Mechanical embedding embedding can also be achieved using the Energy%Terms keywords, but the common case of a two region mechanical QM/MM embedding is easier to set up using this keyword.

MMCharge

Type: Float
Default value: 0.0
Description: Net charge to be used for the MM region.

MMEngineID

Type: String
Description: Identifier for the MM engine

QMCharge

Type: Float
Default value: 0.0
Description: Net charge to be used for the QM region.

QMEngineID

Type: String
Description: Identifier for the QM engine

QMRegion

Type: String
Description: Identifier for the QM region. The rest of the system is considered the MM region.

UseCappingAtoms

Type: Bool
Default value: Yes
Description: Whether to use capping for broken bonds.

Committee¶

It is also possible to run the hybrid engine in Committee mode. When using the hybrid engine as a committee, the average is taken of each engine, meaning that all the regions and factors must be the same. Additionally, the spread of results of the different engines is understood as an uncertainty. The standard deviation of the different engine energies and forces are computed and reported as the uncertainty.

Committee
   Enabled Yes/No
End

Committee

Type: Block
Description: Settings for using the hybrid engine as a committee. The factors and region for each engine must be the same. When committee is enabled the standard deviation is also reported as the uncertainty.

Enabled

Type: Bool
Default value: No
Description: Enable committee

Capping¶

Whether of not capping is enabled is set inside the Energy and QMMM blocks. If enabled then the user can influence the position and type of the capping atom with the Capping sub-block.

Capping
   AllowHighBondOrders Yes/No
   AtomicInfoForCappingAtom string
   CappingElement string
   CheckCapping Yes/No
   Distance float
   Option [Fractional | Fixed]
End

Capping

Type: Block
Description: This block is about capping details. Capping occurs with hydrogen atoms when a bond is broken between an atom inside the region and one outside.

AllowHighBondOrders

Type: Bool
Default value: No
Description: Allows capping of interregional aromatic, double and triple bonds. This is normally not a good idea, since the capping is done with hydrogen atoms.

AtomicInfoForCappingAtom

Type: String
Default value: ForceField.Type=H_ ForceField.Charge=0.0
Description: The AtomicInfo for the capping atoms. Typically a string like ForceField.Type=X much like forcefield info is entered in the System block for normal atoms.

CappingElement

Type: String
Default value: H
Description: The element to be used for capping. The hydrogen atom has the advantage that it is very small.

CheckCapping

Type: Bool
Default value: Yes
Description: The same outside atom can be involved in multiple capping coordinate definitions. This is not a good idea, and this will not be accepted by using this check.

Distance

Type: Float
Default value: -1.0
Description: A negative value means automatic. In that case the sum of covalent radii is used

Option

Type: Multiple Choice
Default value: Fixed
Options: [Fractional, Fixed]
GUI name: Capping option
Description: The capping atom is always along the broken bond vector. The bond distance between the capping atom and the two atoms are obtained from covalent radii, let us call them D1H and D2H. With option=Fractional the capping is on the bond vector with the fraction D1H/(D1H+D2H). With the Fixed option it at the distance D1H from atom 1. A distance of zero always means the coordinate of the inside atom.

For a specific application of QM/MM with capping atoms see this example.

Restarts¶

In a molecular dynamics run or geometry optimization, the geometries at subsequent steps are often very similar. Generally, efficiency can be gained by providing the engines with information from the previous step (“restart”), as this might speed up the SCF or charge equilibration procedure, if applicable. To the forcefield engine, this might avoid re-loading of the database, guessing bonds, etc. at every step. By default all sub-engines are provided with restart information. It can be switched off with the RestartSubEngines key.

RestartSubEngines Yes/No

RestartSubEngines

Type: Bool
Default value: Yes
Description: Save all the results of the subengines and pass those in a next geometry step or MD step.

Charges per region¶

The user can specify charges per region associated with each energy term.

Depending on the setup the charges can be set with the Energy%Term%Charge or the QMMM%mmCharge and QMMM%mmCharge keys.

For a QM engine the charge for a region determines the number of electrons in the region defined in the energy term. For the ForceField engine, charges are specified per atom, and they should add up to the charge specified for the region.

Linear Combination of Energy Terms¶

When the Linear Combination of Energy Terms feature is selected, but using the Energy block, the energy is a linear combination of independent calculations. It is in this spirit that the total charge is considered to be

\[Q = \sum_i^N w_i \; Q^\text{engine(i)}\big(region(i)\big)\]

In the QMMM setup the total charge is the sum of the charge of the mm region and the qm region.

When Energy%DynamicFactors is set to anything other than Default the factors specified in the Term blocks are not used.

Electrostatic Embedding¶

In general, the charges for sub-regions should be consistent with the charge specified for the total system. However, in the case of an electrostatic embedding computation with capping atoms, the sum of charges of the subsystems used in the computation of the five energy terms is allowed to deviate from the total system charge.

\[E = E^{MM}(E) + E^{QM}\big(\text{A}_C(V^\text{E})\big) + E^\text{MM}_\text{nonelstat}(\text{A+E}) - E^\text{MM}_\text{nonelstat}(\text{A}_C) - E^\text{MM}_\text{nonelstat}(\text{E})\]

The MM region that will be passed to the MM engine (term 1) will often have a fractional charge, due to un-capped dangling bonds. The fractional charge of the QM-region however (term 2), should be corrected by the capping atom charges, to yield a chemical system that optimally resembles the full system. As a result, the sub-region charges do not need to add up to the total charge of the system.