ONIOM
This guide is aimed to give a general overview of the ONIOM implementation within the xtb
program package.
Note
This feature is only present in version 6.6 and newer or in the current bleeding-edge version.
General description
The ONIOM scheme is a multiscale calculation approach used to treat large molecular systems efficiently. A detailed review of the ONIOM scheme and its possible applications can be found at: Chung2015.
The total two-layer ONIOM energy is defined as
where \(E_{whole, low}\) and \(E_{model, low}\) terms are the single-point energies calculated at a low-level of theory of the whole system and a specific system cutoff (called henceforward ‘inner region’). \(E_{model, high}\) denotes the single-point energy of the inner region at a higher level of theory. The idea is to combine the different theory levels in a subtractive manner to compromise accuracy and speed.
Input
To perform an ONIOM calculation with xtb
the --oniom
option is used. The inner region has to be defined by providing the atom numbers contained in it and two calculation methods (high:low
) can be chosen. The ONIOM calculation is then invoked by callinig:
> xtb <geometry_file> --oniom [high]:[low] [inner_region]
Note
If high:low
are not provided, the gfn2:gfnff
combination is used.
Methods
gfnff, gfn1, gfn2
These methods are available in the xtb
and can be utilized both as high and low-level approaches in the ONIOM framework.
Important
The ONIOM routine includes but is not limited to the xtb
functionality. To expand the range of the available methods, the external ORCA
and TURBOMOLE
software packages can be employed. This is done by the addition of the corresponding binary path in the environment variable $PATH
.
The best way to configure the external settings for the xtb run is to use xcontrol instructions.
orca
If ORCA
should be employed, an orca input has to be provided to run calculations. An additional instruction file like xcontrol
allows to specify the user-supplied orca input by adding the follwing lines:
$external
orca input file=<filename>
or to provide only calculation method:
$external
orca input string=<method>
If no input is specified, xtb
writes an orca input with the default settings (B97-3c).
turbomole
Turbomole
also uses its format to perform calculations, defined by the control
file.
Initially, the xtb
searches for the control
file in the user’s calculation directory, and if no file is present, writes it with some default settings (B97-3c).
Note
Currently, it is possible to use ORCA
/TURBOMOLE
only as the high level embedding.
Inner region
To perform the ONIOM calculations with xtb
one has to specify the inner_region_cutoff
which is provided either directly as comma-separated indices (“1,3-5,9,10”), or via a file with the same content (or each index on a separate line).
If covalent bonds are cut between the inner region and the rest of the system, ONIOM handles the resulting boundary through Hydrogen Linked Atoms (LAs):
The positions for LAs are determined by the positions of the cleaved atoms:
where \([xyz]_{con}\) and \([xyz]_{host}\) are coordinates of connector atom (stays in the inner region) and host atom (replaced by LA), \(k\) is a fixed scaling factor.

To distinguish between different bonds the topology information from the low
level method is used.
Warning
It is strongly recommended to cut only single bonds. When using the GFN-FF as a low-level method, one has to be very careful with the inner region specification. The topology data of the GFN-FF does not allow for an accurate distinction between single and higher-order bonds.
Functionality
flags
- --chrg ‘int:int’:
extension of the classical
--chrg
flag, allows to specify charges for inner region and whole molecule as inner_region_charge:system_charge. If only one value is given, it is used as system_charge, and thextb
will determine the inner_region_charge automatically.
Note
If inner_region_charge is specified in the external input format file(*.inp
or control
), one has to provide the same charge to the xtb
as:
> xtb <geometry_file> --oniom <orca/turbomole>:<xtb> <inner_region> --chrg <inner_region_charge>:<system_charge>
- --cut:
write the geometry of the specified inner region without performing any calculations. Note that hydrogen-linked atoms are not present, due to the absence of the Wiberg bond orders. In addition, this procedure can be used to test the abovementioned automatic inner region charge determination.
- --ceasefiles:
extension of the original flag, with instructions for the
xtb
to delete all external files fromORCA
/TURBOMOLE
(except for*.inp
andcontrol
files)
xcontrol
In addition to the above-mentioned xcontrol
instructions deeper control over the ONIOM routine is available via the $oniom
group block.
- inner logs=[bool]
print high- and low-level optimization trajectory for the model system (
high.inner_region.log
andlow.inner_region.log
).- derived k=[bool]
k is a scaling factor for the LAs coordinates, which by default is constant. This instruction allows it to be dynamically assigned in dependence on the distance between the connector and host atoms.
- outer=[bool]
perform outer region saturation
- ignore topo=[bool]
bypass topology check when cutting bonds
- silent=[bool]
redirecting the output of the external programs into files.
Example: S30L-23
As a showcase host-guest complex number 23 from S30L benchmark is chosen.

This system consists of 2 NCI-bound fragments: 1-62 and 63-98, the latter having +1 charge. To test the automatic charge identification routine:
To start single-point calculation with the user-defined orca input file:
specify orca input and add its name in the xcontrol file:
Please use the engrad
keyword to allow xtb
to read the ORCA
output. The inner region is automatically written in the some.xyz
file.
start
xtb
run:
> xtb input.xyz --oniom orca:gfn2 1-62 --chrg +1 --input xcontrol
The final xtb
output for the given example is divided into 3 parts with the ONIOM results printed in the property printout section:
------------------------------------------------------------------------
Singlepoint calculation of whole system with low-level method
------------------------------------------------------------------------
... skip ...
------------------------------------------------------------------------
Singlepoint calculation of inner region with low-level method
------------------------------------------------------------------------
... skip ...
------------------------------------------------------------------------
Singlepoint calculation of inner region with high-level method
------------------------------------------------------------------------
... skip ...
-------------------------------------------------
| Property Printout |
-------------------------------------------------
-------------------------------------------------
| TOTAL ENERGY -1438.298999659396 Eh |
| GRADIENT NORM 0.045824034529 Eh/α |
-------------------------------------------------