# 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
End

Basis Type=TZP
End

Basis Type=DZ
End

EndEngine

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

Engine
Type: Block True 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 This block is there to construct the energy.
Term
Type: Block True This block is there to construct the energy term. Can have multiple occurrences
Charge
Type: Float 0.0 Net charge to be used for this energy term.
EngineID
Type: String Identifier for the engine
Factor
Type: Float 1.0
Region
Type: String Identifier for the region
UseCappingAtoms
Type: Bool Yes 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 This block is there to identify the QMMM engines.
Embedding
Type: Multiple Choice Electrostatic [Mechanical, Electrostatic] 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 0.0 Net charge to be used for the MM region.
MMEngineID
Type: String Identifier for the MM engine
QMCharge
Type: Float 0.0 Net charge to be used for the QM region.
QMEngineID
Type: String Identifier for the QM engine
QMRegion
Type: String Identifier for the QM region. The rest of the system is considered the MM region.
UseCappingAtoms
Type: Bool Yes 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 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 No 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 ForceField.Type=H_ ForceField.Charge=0.0 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 H The element to be used for capping. The hydrogen atom has the advantage that it is very small.
CheckCapping
Type: Bool Yes 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 -1.0 A negative value means automatic. In that case the sum of covalent radii is used
Option
Type: Multiple Choice Fixed [Fractional, Fixed] Capping option 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 Yes 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.