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 basis sets, computing the average result.

Engine Hybrid
    Energy # we want the average energy obtained with the DZ and TZP basis sets
       Term EngineId=adf-tzp factor=0.5
       Term EngineId=adf-dz factor=0.5
    End

    Engine ADF adf-tzp   # here afd-tzp is the EngineID
      Basis Type=TZP
    End

    Engine ADF adf-dz
      Basis Type=DZ
    End

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
   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.

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.

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.

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.