User Guide#

The MBE step estimates high-level energies, forces and stress for a periodic cell or a large cluster that the high-level method can’t treat directly. It corrects a cheap calculation of the whole system with many-body increments, each the difference [high − low] computed on a small isolated fragment:

E(system) ≈ E_low(system) + Σ_F dE_F

where dE_F is the F-body part of [high − low] for each selected fragment F: monomers, pairs and triples. Forces and the virial are assembled the same way. The bookkeeping is done by the seamm_mbe library.

The levels of theory#

The step uses up to four Model Chemistries:

High level: The level the labels approximate, run on every fragment. By default it is the one chosen by the Model Chemistry step before this step.
Molecular low level: The cheap level run on the fragments referenced to a molecular code. It is required.
Periodic low level: Optional. A periodic code for the compact fragments: monomers, and pairs closer than a distance r1. It should be the code of the cell’s low level, since that cancels the cell’s own low-level error best. Extended fragments use the molecular low level, because they pick up interactions with their periodic images in affordable boxes. This is the “mixed” scheme.
Whole-system low level: The cheap level run on the whole cell or cluster. automatic uses the periodic low level for a cell and the molecular low level for a cluster. For a cell with a periodic low level it must be that same level, so that the compact fragments and the cell are the same calculation.

Each field accepts any model chemistry the installed programs offer, typed or chosen, and $variables in its parts. A periodic level must come from a program that declares the sign convention of its stress: MOPAC does from mopac_step 2026.10.3.2, VASP from vasp_step 2026.10.3. A periodic low level applies only to periodic cells; for a cluster set it to none.

Each increment is built entirely from calculations at its own low level. A triple referenced to the molecular level subtracts the molecular-level increments of its pairs, even where those pairs are referenced to the periodic level in the sum.

Choosing the fragments#

Maximum order: 1 (monomers), 2 (pairs) or 3 (triples).
Distance between molecules: Measured between the molecules’ designated atoms (water’s O, a carbonate’s carbonyl C, an ion), between their closest atoms or closest heavy atoms, or between their centres of mass or geometry.
Cutoffs: One value, or a table by molecule type for mixtures, e.g. water water 4.5; Li+ * 3.0; * * 5.0. * matches any type, and the most specific entry wins. Every pair of types present must be covered.
Triples: connected selects a triple when at least two of its three pairs are within the triple cutoff (a hub bonded to both others). compact requires all three. A connected triple’s third pair is computed as well, since its increment needs it, even when it is longer than the pair cutoff. It does not enter the 2-body sum.

The molecules are found from the bonds (they are perceived if the structure has none) and typed by formula and topology. Charges come from the structure’s formal charges, or from the type catalog: Li⁺, BF₄⁻, PF₆⁻ and the common monatomic ions. The whole system runs with the charge its molecules add up to. If the configuration’s own charge is set and disagrees, the step refuses to run. A configuration charge of 0 counts as not set (plain xyz input has no charge), so a structure holding a Li⁺ runs at +1 even if its charge field says 0. To make a molecule neutral, give the structure formal charges or give the charge of its type.

A cell too small for the cutoffs is refused, because the same molecules could form two different fragments.

The labels#

For each configuration the step stores:

the energy (kJ/mol), the gradients (kJ/mol/Å) and, for a cell, the stress (a Voigt [6] vector in GPa, σ = −P), as properties energy#MBE#<model> and so on, with the gradients also on the atoms;
the atomic and molecular pressures, the correction and its breakdown by body order, the fragment counts and the largest increment net force, as results for variables and tables;
an extended XYZ file (default mbe_labels.extxyz in the step’s directory; job:NAME puts it in the job’s directory) with REF_energy, REF_forces and, for a cell, the nine-value REF_stress. Rerunning replaces a configuration’s frame rather than adding a second copy.

Energy offsets (eV per molecule, by type) put the labels on the scale of other training data, e.g. water 2074.69325 for the water training sets’ formation-energy scale. The default, none, gives absolute energies. Every molecule type present must have an offset when any is given.

A configuration with a failed or missing calculation gets no labels. The step reports which calculations failed, stores the complete configurations, and stops with an error. Rerunning the job reuses every finished calculation and retries the failed ones.

Running the calculations#

Each level runs through SEAMM’s task layer: as batch tasks wherever the job’s target sends them (a local pool, or bundled jobs on a cluster), or on a warm MDI engine for cheap codes run locally. The Execution settings give the cores and memory of each calculation and how many share a batch job. Finished bundles are archived, keeping a configuration to a few files. In this version the levels run one after the other.

Periodic fragments on the cell’s grid#

A plane-wave code’s energy depends slightly on where each atom sits relative to its FFT grid. The increments subtract fragments from each other and from the cell, so this error cancels only if every atom keeps the same position relative to the grid. With a periodic low level the step therefore gives the cell an explicit grid, with a spacing no larger than Largest FFT grid spacing (default 0.0829 Å), and puts each periodic fragment in a box that is a whole number of those grid steps, at least 12 Å and the fragment’s extent plus Box padding (default 7.5 Å), shifted by whole grid steps. The cell must be orthorhombic. These settings appear only when a periodic low level is chosen.

Counterpoise#

Counterpoise pairwise corrects each selected pair for the basis-set superposition error (Boys–Bernardi), at the high level and, for pairs referenced to it, the molecular low level. Each pair adds two calculations per level: each monomer in the pair’s basis, with the other monomer’s atoms as ghosts. The correction enters the 2-body sum only; triples still subtract the uncorrected pairs, so the pairs’ error does not move into the 3-body terms. Where a pair’s ghost gradients are unphysical, the energy is corrected but the forces are left uncorrected, and the step counts these pairs. The total correction and that count are stored as results.

Counterpoise needs a level that runs as batch calculations with ghost atoms, and is not available for periodic cells (it is hidden in the dialog when a periodic low level is chosen).

4-body terms come in a later version.