dimer-builder-step 2026.7.27

SEAMM Dimer Builder Plug-in

A SEAMM plug-in for Dimer Builder

• Free software: BSD-3-Clause

• Documentation: https://molssi-seamm.github.io/dimer_builder_step/index.html

• Code: https://github.com/molssi-seamm/dimer_builder_step

History

2026.7.27 – Repulsive-wall coverage, and progress output for long runs

• Energy-stratified sampling is flat in interaction energy, which also clips the steep repulsive wall: it caps the repulsive side at the largest positive ΔE level (~+5·kBT), so the training set gets no points higher up the wall and a machine-learned force field extrapolates it too softly – a stability risk under high-temperature or non-equilibrium dynamics. A new Add repulsive-wall coverage option (off by default, since it 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 above the cap. Like the long-range tail coverage, these come out of Target configurations (they are not added on top), so raise the target to keep the same coverage of the attractive region; the analysis reports the three-way split between the flat-in-energy core, the tail, and the wall.

• Long runs (many orientations, each driving many energy evaluations) now print a throttled progress line – percent complete, elapsed time, and an estimate of the time remaining – no more often than once a minute, so short runs stay quiet while a multi-hour run shows that it is making progress.

2026.7.23.1 – Long-range distance coverage for energy-stratified sampling

• Energy-stratified sampling is flat in interaction energy, which starves the weak long-range tail (beyond ~5 Å the interaction is ≈0, so it gets only about one energy bin) even though molecular dynamics visits it constantly – leaving a machine-learned force field under-constrained and prone to an unphysical bump in that region. A new Add long-range distance coverage option (on by default) supplements the kept set, independently of interaction strength, with:

  • a distance-coverage floor – a minimum number of configurations in each separation bin from Tail coverage from out to the maximum separation (controlled by Tail coverage spacing and Tail configurations per bin, chosen for geometric diversity); and

  • Asymptote anchors – a handful of far-separation configurations out to Anchor separation that pin the interaction energy to zero at large distance.

• The tail configurations come out of Target configurations (they are not added on top), so raise the target to keep the same coverage of the strongly interacting region. The analysis now reports the split – how many configurations came from the energy-stratified selection versus the long-range coverage.

• The reported energy-flatness now describes the energy-stratified core only; the deliberately near-zero tail configurations are excluded so they no longer distort the flatness metric.

2026.7.23 – Diverse down-selection of the sampled dimers

• Energy-stratified sampling can now keep a geometrically diverse, de-duplicated set rather than just a flat-in-energy one, so redundant near-identical configurations are dropped and distinct binding geometries are all represented. A new Down-select by control chooses how the pooled candidates are reduced to about Target configurations:

  • energy bins + diversity (the new default) keeps the flat-in-energy bins and, within each bin, selects a diverse subset by clustering the configurations’ geometry (separation, approach direction, relative orientation, and contacts);

  • descriptor diversity clusters globally over that geometry together with the interaction energy (weighted by Energy weight) – the most diverse, with energy flatness controlled by the weight; and

  • energy bins is the previous flat-in-energy behavior.

• This follows the DIRECT selection method (Qi et al., npj Comput. Mater. 2024) and adds scikit-learn as a dependency.

2026.7.20 – Energy-stratified sampling and sampling diagnostics

• Added an energy-stratified spacing (with the energy contact method) that produces a set of dimers flat in interaction energy — evenly covering the repulsive wall, the attractive well, and the long-range tail — which is what a machine-learned force field needs, rather than the pile-up near zero interaction that uniform sampling gives. It works globally: candidate configurations are pooled across all orientations, sorted into interaction-energy bins, and each bin is capped at the same count. Two controls, “Number of energy bins” and “Target configurations”, set the resolution and the approximate total (deep-well energies are rare, so those bins — and the total — may come out smaller; raise the number of orientations to fill them).

• The scan is anchored on the actual energy minimum found from the engine, and the repulsive side is capped at the largest “ΔE level” (default +5·kBT), so configurations are never pushed to absurd repulsive energies and the van der Waals estimate is only a starting guess (the “innermost gap” setting does not apply to this spacing).

• Orientations may optionally be pre-filtered by how deeply they bind (reject shallow, or downweight by depth); the default keeps every orientation and lets the global stratification balance the set.

• The interaction energy is now recorded for every configuration whenever the energy contact method is used (any spacing), and saved as a property.

• Added sampling diagnostics: after a build, the step reports a short summary and, with “Sampling diagnostics” set to basic or detailed, writes interactive graphs for the Dashboard — separation coverage, contact distances, approach direction, relative orientation, and (when energies were computed) the interaction-energy distribution and binding-curve envelope. detailed also writes each panel as its own graph. Extra image formats (PDF, PNG, SVG, …) can be requested with graph-formats in seamm.ini.

2026.7.9 – ORCA engine for energy contact, and consistent CoM separation

• The energy-based contact search can now use ORCA (via a Model Chemistry step), in addition to MOPAC and xTB. Any MDI-capable model chemistry works; the model chemistry’s method and, for ORCA, its basis set are passed to the engine automatically.

• seamm_mdi is now a declared dependency (it was previously imported lazily), so the energy contact method works out of the box.

• The center-to-center separation for prepared dimers is now measured between the centers of mass of the “fixed” and “movable” groups, matching the two-monomer-sets path (which was already mass-weighted). Previously the prepared-dimers path used the unweighted geometric center, so the reported dimer separation / dimer gap properties now have a single, consistent meaning across both input modes.

2026.7.6 – Energy-based contact and GUI refinements

• Added an energy contact method: with a Model Chemistry step before the Dimer Builder step, the contact distance is found from the energy minimum along each approach direction (falling back to the van der Waals estimate for orientations with no binding well). It uses the new seamm_mdi MDI driver to evaluate the energy, and reports which model chemistry was used and how many times it was called.

• Configuration names now use a comma (e.g. 2,1) rather than a slash, which is reserved for separating system and configuration names.

• The dialog no longer shows the unused Flowchart tab, and reminds you to add a Model Chemistry step when the energy contact method is chosen and none precedes this step.

2026.6.30 – Initial release

• Generates sets of dimer (molecule-pair) configurations across a range of separations and relative orientations, for building interaction-energy data sets and training sets for machine-learned force fields.

• Two ways to provide the input structures:

  • two sets of monomer conformers, which are assembled into dimers at random relative orientations; or

  • prepared complexes, each scanned along the axis between a “fixed” and a “movable” group (taken from subsets if present, otherwise the last molecule is movable and the rest are fixed).

• For each orientation, scans the center-to-center separation from just inside the van der Waals contact distance out to a chosen maximum, with geometric (default), linear, or explicit spacing.

• Records the scan geometry on every configuration as properties – separation, gap beyond contact, the approach-direction angles, and the movable group’s orientation angles – and marks the two molecules as “fixed” and “movable” subsets, so the pieces are easy to find downstream.

• Stores all the generated structures as conformers of a new system, named by orientation and point (1/1, 1/2, …) by default.