.. _user-guide:

**********
User Guide
**********

The Dimer Builder step generates sets of configurations of a pair (or small
cluster) of molecules across a range of separations and relative orientations.
The configurations are stored as conformers of a new system, ready to be fed to
a quantum-chemistry step for computing interaction energies, or exported as a
training set for machine-learned force fields (in the spirit of the DES370K
dataset).

Input
=====

Set **Input** to choose how the structures are provided:

**two monomer sets**
    Assemble dimers from conformers of *monomer A* and *monomer B* at random
    relative orientations. Each of the two monomers is given as:

    * ``current`` -- the current system;
    * a **system name** -- use that system's configurations as the conformer
      pool, selected by the *using configurations* control (``all``, ``last``,
      ``first``, or a name pattern); or
    * a ``$variable`` holding a list of configurations (all are used).

**prepared dimers**
    Take already-assembled complexes (from *monomer A*) and scan each one,
    sliding a "movable" group relative to a "fixed" group. The two groups come
    from ``fixed`` / ``movable`` subsets on the input if present (so you can
    group several molecules per side); otherwise the last molecule is movable
    and the rest are fixed.

Orientation sampling
====================

For "two monomer sets", **Number of orientations** samples are generated. Each
sample independently draws a random conformer of A, a random conformer of B, and
a random relative orientation. Monomer A is held fixed (centered on its
principal axes) so it is a stable visual anchor across the whole run; monomer B
carries the randomness. Set **Random seed** to an integer for reproducible
orientations, or leave it as ``random``.

The radial scan
===============

For each orientation the center-to-center separation is scanned from just inside
contact out to a maximum:

* **Find contact using** -- ``van der Waals radii`` (a fast geometric estimate)
  or ``energy`` (see below).
* **Innermost gap** -- how far inside the contact distance to start (a small
  negative value gives a slight overlap).
* **Maximum separation** -- the largest center-to-center distance.
* **Spacing** -- ``geometric`` (the default; points cluster near contact and
  thin out in the tail), ``linear``, ``explicit`` (a list you provide in
  **Separations**, as gaps beyond contact), or ``energy-stratified`` (see
  below; requires the ``energy`` contact method).
* **Number of separations** -- how many points per scan (for geometric/linear;
  for energy-stratified it sets the resolution of the ΔE profile).

Energy-based contact
--------------------

With **Find contact using** = ``energy``, the step drives a quantum-chemistry
engine to find the energy **minimum** along each approach direction and anchors
the scan there; orientations with no binding well fall back to the van der Waals
contact. This requires a **Model Chemistry step before the Dimer Builder step**
to define the engine and method; the dialog reminds you if one is missing. The
semiempirical engines (**MOPAC**, **xTB**) are driven over `MDI
<https://molssi-mdi.github.io/MDI_Library/>`_ as resident engines; **ORCA**
runs the points as separate calculations, a whole grid of separations at once
(concurrently on this machine, or batched on the job's cluster queue), and so
does MOPAC when the job's calculations go to a cluster queue. A cheap
method is usually the right choice: the energy only *places* the scan, it does
not produce the final data set, and ORCA is much heavier than the semiempirical
engines. The step reports which model chemistry was used and how many times it
was called.

Energy-stratified sampling
--------------------------

With **Spacing** = ``energy-stratified`` (which needs the ``energy`` contact
method) the step builds a set of dimers that is **flat in interaction energy**
rather than evenly spaced in distance. This is usually what you want for a
machine-learned force field: the model must be accurate everywhere it will be
queried -- the repulsive wall, the bottom of the attractive well, and the
long-range tail -- so the training set should cover that whole energy range
evenly, instead of piling most configurations in the shallow, nearly
non-interacting region that uniform sampling produces.

It works by pooling candidate configurations from *all* orientations and then
down-selecting about **Target configurations** of them. **Down-select by**
chooses how:

* ``energy bins + diversity`` (default) -- sort the candidates into interaction-
  energy bins (flat in energy) and, within each bin, keep a *geometrically
  diverse, de-duplicated* subset by clustering the collective variables
  (separation, approach direction, relative orientation, closest contact). This
  gives a set that is flat in energy, reaches deep into the attractive well, and
  is not dominated by near-identical geometries.
* ``descriptor diversity`` -- a single global clustering (the DIRECT method) over
  those collective variables **plus** the interaction energy, keeping one per
  cluster. **Energy weight** sets how strongly ΔE counts relative to each
  geometric variable (larger = flatter in energy, less geometric spread). This
  maximizes geometric diversity but the energy flatness depends on the weight.
* ``energy bins`` -- energy bins with a plain random pick per bin (flat in
  energy, no geometric de-duplication).

Other controls:

* **Number of energy bins** -- how many ΔE bins to spread the kept
  configurations across (the two binned methods).
* **Target configurations** -- the approximate total to keep. Deeply bound
  geometries are rare, so the total may come out smaller; raise **Number of
  orientations** to find more deep configurations.
* **ΔE levels** -- sets the energy window. The most repulsive value (default
  ``+5*kBT``) caps the wall, so no configuration is pushed to an absurd
  repulsive energy; the symbols ``De`` (well depth) and ``kBT`` (thermal energy
  at the **Sampling temperature**) may be used.
* **Weight orientations by well depth** -- an optional pre-filter. The default
  ``none`` keeps every orientation; ``reject shallow orientations`` /
  ``downweight by depth`` bias toward the more strongly bound orientations first
  (using **Minimum well depth**).

Because the interaction energy varies almost entirely at short range, a
flat-in-energy set naturally has most of its configurations at short
separations; that is expected.

Covering the long-range tail and the repulsive wall
---------------------------------------------------

Being flat *in energy* clips both ends of the physical range, which can leave a
machine-learned force field under-constrained where it still needs to be right:

* the weak **long-range tail** (beyond ~5 Å the interaction is ≈ 0, so it maps to
  a single energy bin) even though dynamics visits it constantly; and
* the steep **repulsive wall** above the ``+5*kBT`` cap, which the energy window
  deliberately excludes -- so a force field has no data there and extrapolates
  the wall too softly, a stability risk in high-temperature or non-equilibrium
  dynamics.

Two optional supplements fill these regions independently of interaction
strength. Both come **out of Target configurations** (they are not added on top),
so raise the target to keep the same coverage of the strongly interacting core,
and the analysis reports how the total splits between the core, the tail, and the
wall.

* **Add long-range distance coverage** (on by default) adds a
  *distance-coverage floor* -- **Tail configurations per bin** in every **Tail
  coverage spacing** bin from **Tail coverage from** out to the maximum
  separation -- plus a few **Asymptote anchors** at large separation (out to
  **Anchor separation**) to pin the interaction energy to zero.
* **Add repulsive-wall coverage** (off by default -- a robustness / high-*T*
  add-on that costs extra energy evaluations) walks the scan further *up* the
  wall, to **Wall coverage up to**, and keeps **Wall configurations per bin** in
  each **Wall coverage spacing** energy bin from the ``+5*kBT`` cap up to that
  ceiling. Turn it on when the model must stay stable under compression or at
  high temperature.

Both supplements pick a geometrically diverse subset in each bin, and their
configurations are excluded from the reported energy-flatness metric (which then
describes only the flat-in-energy core, not the deliberately off-core tail and
wall points).

What is stored
==============

All the generated configurations become conformers of a **new system** (named
from the two monomers by default). On each configuration the step:

* records the scan geometry as properties -- the separation and the gap beyond
  contact, the approach-direction angles, and the movable group's orientation
  (Euler) angles, plus the interaction energy and well depth when the ``energy``
  contact method was used -- so configurations can be filtered and analyzed
  later (toggle with **Save scan variables as properties**); and
* marks the two pieces as ``fixed`` and ``movable`` **subsets**, so a downstream
  interaction-energy or counterpoise calculation can find them.

**Name the configurations** controls the configuration names:
``orientation,distance`` (e.g. ``2,1`` -- orientation 2, point 1; the points of
one scan group together), ``separation``, or ``sequential``.

Sampling diagnostics
====================

Set **Sampling diagnostics** to check *what kind of coverage a run actually
produced* -- how the configurations are spread over separation, contact
distance, approach direction, relative orientation, and (with the ``energy``
contact method) interaction energy:

* ``none`` -- skip the diagnostics.
* ``basic`` -- print a short numerical summary and write a single combined
  dashboard, ``dimer_sampling.graph``, that opens interactively in the SEAMM
  Dashboard.
* ``detailed`` -- also write each panel as its own graph
  (``dimer_sampling_<panel>.graph``) for a closer look.

To also save the graphs as static images, add ``graph-formats`` to the Dimer
Builder section of ``~/SEAMM/dimer_builder.ini`` (or pass ``--graph-formats``),
e.g. ``graph-formats = png pdf svg``.

Reading the dashboard
---------------------

The header line summarizes the run: **N** (number of configurations), the
separation range **R**, the **approach concentration**, and -- when energies
were computed -- the minimum interaction energy **ΔE_min** and the percentage of
configurations that are attractive (ΔE < 0). The panels are:

**Separation coverage**
    Histogram of the center-to-center separation *R*. Shows how far apart the
    molecules are across the set. With energy-stratified sampling most points
    sit at short *R* (that is where the interaction changes), with a thin tail
    to the maximum separation.

**Contact distribution**
    The shaded histogram is the *closest* atom-atom distance between the two
    molecules in each configuration -- the practical measure of how tightly they
    touch. The overlaid lines are the most common element-pair distances (e.g.
    O--H, H--H); a peak at short O--H, for example, is the fingerprint of
    hydrogen bonding. Watch for a build-up at very short distances, which means
    hard atomic clashes.

**Approach direction (A frame)**
    Where molecule B sits relative to molecule A, drawn on a flattened sphere
    (a Mollweide map) in A's own frame; with energies, each point is colored by
    its ΔE. Points spread evenly over the whole map mean B approaches from all
    directions equally (isotropic); points clustered in one region mean the
    sampling favors particular docking directions. The single-number version of
    this is the **approach concentration**: **0 = perfectly isotropic**, **1 =
    all from one direction**. A low value with a directional interaction like a
    hydrogen bond signals that the orientations are *not* concentrated on the
    physically important motif.

**Relative orientation**
    Histogram of the angle between the two molecules' long axes -- how the
    partners are turned relative to each other, independent of which side they
    approach from.

**Energy distribution** *(energy contact method only)*
    Histogram of the interaction energy ΔE. For energy-stratified sampling this
    should be roughly **flat** from the repulsive side (positive) through zero to
    the bottom of the well (negative). The title reports a **flatness CV**
    (coefficient of variation of the bar heights): **0 is perfectly flat**;
    values well below ~0.5 are good, while a value near ~2 means the sample is
    piled up in one energy range (what uniform sampling gives).

**Binding-curve envelope** *(energy contact method only)*
    A 2-D density of ΔE versus separation *R* -- the interaction energy as the
    molecules come together, pooled over all orientations. The lower edge traces
    the best (deepest) binding curve; the spread at each *R* shows how much the
    energy depends on orientation.

A "good" energy-stratified run therefore shows a flat **Energy distribution**
(low flatness CV) that reaches well into the attractive region, a clean
**Binding-curve envelope**, and no pile-up of hard clashes in the **Contact
distribution**. The **approach concentration** tells you separately whether the
*orientational* coverage is biased or isotropic.

Indices and tables
==================

* :ref:`genindex`
* :ref:`search`