Note
Go to the end to download the full example code.
xTB-Style RMSD Metadynamics for Structure Exploration#
Every method so far has needed a collective variable: a scalar you already know matters. That is the assumption RMSD metadynamics drops. Its history is a set of retained structures, and the bias pushes the system away from all of them at once:
Nothing here names a reaction coordinate. The “coordinate” is the whole geometry, compared after optimal translation and rotation, which is what makes this the method of choice for conformer and isomer searching — the scheme xTB/CREST uses.
The trade is explicit: there is no free energy at the end. This is a
structure generator, and RMSDMetaDynamicsBias deliberately has no
free_energy method to suggest otherwise.
This example explores isomers of an 8-atom Lennard-Jones cluster, a classic benchmark with several distinct minima separated by real barriers.
Key concepts demonstrated#
Biasing without choosing a collective variable.
Optimal-alignment RMSD, and why the bias exerts no net force.
FIFO retention, and why it is the natural policy here rather than a compromise.
Selecting a subset of atoms to compare.
Applications#
Conformer generation for a flexible molecule.
Isomer and polymorph searching.
Escaping a minimum when you cannot say in advance what direction “out” is.
from __future__ import annotations
import logging
import os
import torch
from nvalchemi.data import AtomicData, Batch
from nvalchemi.dynamics import NVTLangevin
from nvalchemi.enhanced_sampling import EnhancedSampling, RMSDMetaDynamicsBias
from nvalchemi.models.lj import LennardJonesModelWrapper
# force=True: an earlier gallery example may have configured logging already.
logging.basicConfig(level=logging.INFO, format="%(message)s", force=True)
logger = logging.getLogger(__name__)
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
N_STEPS = 40 if os.environ.get("NVALCHEMI_SPHINX_BUILD") else 800
N_WALKERS = 2
N_ATOMS = 8
TEMPERATURE = 40.0 # K — cold enough that plain MD stays near one basin
torch.manual_seed(0)
<torch._C.Generator object at 0xfc22d0334910>
Build the cluster#
A non-periodic molecular batch. This bias rejects a periodic one:
Cartesian RMSD against a stored reference is not defined under periodic
boundary conditions, because an atom crossing a cell face is physically
unmoved but Cartesian-displaced by a lattice vector. Rather than return a
plausible wrong number, evaluate() raises.
Periodicity is read from batch.pbc, not from the presence of a cell. A
bounding box with pbc=False — a boxed or solvated molecule — is fine;
this cluster simply carries no cell at all.
def make_cluster() -> AtomicData:
"""Return one argon cluster with the buffers dynamics writes into."""
spacing = 3.8
grid = torch.tensor(
[[x, y, z] for x in (0.0, 1.0) for y in (0.0, 1.0) for z in (0.0, 1.0)]
)
positions = grid[:N_ATOMS] * spacing
positions = positions + 0.05 * torch.randn_like(positions)
data = AtomicData(
positions=positions,
atomic_numbers=torch.full((N_ATOMS,), 18, dtype=torch.long),
atomic_masses=torch.full((N_ATOMS,), 39.948),
forces=torch.zeros(N_ATOMS, 3),
energy=torch.zeros(1, 1),
)
data.add_node_property("velocities", torch.zeros(N_ATOMS, 3))
return data
batch = Batch.from_data_list([make_cluster() for _ in range(N_WALKERS)]).to(DEVICE)
Configure the bias#
k_pushHow hard to push away from a retained structure, in eV. It sets the barrier height the bias can overcome.
alphaKernel width in
A^-2. It sets how different a structure has to be before it stops feeling the reference, and it is the parameter most worth thinking about, because it must match the RMSD scale your system actually explores. The kernel only has usable gradient wherealpha * RMSD^2is of order one: pickalphafar too small andexp(-alpha * RMSD^2)sits at ~1 for every structure, so the bias is nearly constant and exerts almost no force at all. A rigid cluster moving 0.3 A wantsalphaaround 10; a floppy molecule sampling 1 A wantsalphaaround 1.storage="fifo"The default here, and unlike well-tempered metadynamics it is not a compromise. With no free energy to reconstruct, discarding the oldest reference is a deliberate choice: it keeps the system pushing outward instead of accumulating an ever-stiffer cage that eventually freezes it. This is the xTB-compatible policy.
ramp_depositionsA new reference lands at RMSD zero — exactly where the system is standing. Without a ramp it would switch on at full amplitude at the worst possible moment, so the default ramps it in over one deposition.
rmsd_bias = RMSDMetaDynamicsBias(
k_push=0.08, # eV
alpha=10.0, # A^-2, matched to the ~0.3 A scale this cluster explores
frequency=40,
storage="fifo",
max_references=24,
ramp_depositions=1,
name="rmsd",
)
Comparing a subset of atoms#
Passing atom_indices restricts the comparison to chosen atoms, given as
per-graph local indices. For a molecule the usual choice is heavy atoms
only: methyl hydrogens spinning freely generate RMSD that says nothing
about the conformer. Correspondence is fixed — atom i is always
compared with atom i of the reference, with no permutation search — so
two structures identical up to relabelling count as distinct.
Every atom is compared here, which is what atom_indices=None means.
Run#
model = LennardJonesModelWrapper(sigma=3.4, epsilon=0.0104, cutoff=8.5).to(DEVICE)
sampling = EnhancedSampling(
model=model,
engine=NVTLangevin,
engine_kwargs={"dt": 0.5, "temperature": TEMPERATURE, "friction": 0.02},
biases={"rmsd": rmsd_bias},
extra_hooks=list(model.make_neighbor_hooks()),
)
initial = sampling.prime_forces(batch)
logger.info(
"Initial potential energy: %s",
[round(v, 4) for v in sampling.last_outputs["physical/energy"].flatten().tolist()],
)
batch = sampling.run(batch, n_steps=N_STEPS, prime=False)
logger.info(
"Depositions: %d, references retained: %d of %d (written: %d)",
int(rmsd_bias.deposits),
int(rmsd_bias.reference_count),
rmsd_bias.capacity,
int(rmsd_bias.references_written),
)
logger.info(
"Final potential energy: %s",
[round(v, 4) for v in sampling.last_outputs["physical/energy"].flatten().tolist()],
)
Initial potential energy: [-0.1562, -0.1557]
Depositions: 1, references retained: 2 of 24 (written: 2)
Final potential energy: [-0.1562, -0.156]
The retained structures are distinct#
The point of the bias is that what it collects are genuinely different geometries, not the same one re-recorded. Pairwise RMSD between the retained references shows that directly.
from nvalchemi.enhanced_sampling.biases.rmsd_metad import _squared_rmsd
def spread(structures: torch.Tensor) -> tuple[float, float]:
"""Return the mean and max pairwise RMSD over a set of structures."""
pairwise = _squared_rmsd(structures, structures).clamp(min=0.0).sqrt()
mask = ~torch.eye(pairwise.shape[0], dtype=torch.bool, device=pairwise.device)
off_diagonal = pairwise[mask]
return float(off_diagonal.mean()), float(off_diagonal.max())
references = rmsd_bias.reference_coords[: int(rmsd_bias.reference_count)]
biased_mean, biased_max = spread(references)
logger.info("Pairwise RMSD between retained structures (A):")
logger.info(" mean %.3f max %.3f", biased_mean, biased_max)
Pairwise RMSD between retained structures (A):
mean 0.115 max 0.115
The comparison that matters#
Structural spread on its own proves nothing: a hot enough thermostat produces scatter without visiting anything new. Repeating the identical run with the bias removed separates the two.
control_batch = Batch.from_data_list([make_cluster() for _ in range(N_WALKERS)]).to(
DEVICE
)
control_model = LennardJonesModelWrapper(sigma=3.4, epsilon=0.0104, cutoff=8.5).to(
DEVICE
)
# A "bias" that only records where the unbiased trajectory went. Same
# deposition schedule, no k_push acting on the dynamics.
recorder = RMSDMetaDynamicsBias(
k_push=1e-12,
alpha=10.0,
frequency=40,
max_references=24,
name="rmsd",
)
control = EnhancedSampling(
model=control_model,
engine=NVTLangevin,
engine_kwargs={"dt": 0.5, "temperature": TEMPERATURE, "friction": 0.02},
biases={"rmsd": recorder},
extra_hooks=list(control_model.make_neighbor_hooks()),
)
control.run(control_batch, n_steps=N_STEPS)
control_refs = recorder.reference_coords[: int(recorder.reference_count)]
control_mean, control_max = spread(control_refs)
logger.info("Unbiased control, same schedule and temperature:")
logger.info(" mean %.3f max %.3f", control_mean, control_max)
logger.info("Bias widened the explored set by %.1fx", biased_mean / control_mean)
Unbiased control, same schedule and temperature:
mean 0.070 max 0.070
Bias widened the explored set by 1.6x
The bias cannot move the cluster bodily#
RMSD is measured after optimal translation and rotation, so the energy is invariant to rigid motion — and therefore the bias forces sum to zero. A bias that failed this would slowly translate the system, and the drift would look like physics.
bias_forces = sampling.last_outputs["bias/rmsd/forces"]
net = bias_forces.reshape(N_WALKERS, N_ATOMS, 3).sum(dim=1)
logger.info("Net bias force per walker: %.2e eV/A", float(net.abs().max()))
Net bias force per walker: 0.00e+00 eV/A
No free energy here#
Well-tempered metadynamics converges to a bias that is a free-energy estimate. This method does not: the references are discarded as the FIFO ring wraps, and the kernel is not a probability model of anything. What it produces is a set of structures worth optimising or re-scoring with a higher level of theory.
WellTemperedMetaDynamicsBias.free_energy refuses under "fifo" for
exactly this reason, and RMSDMetaDynamicsBias has no such method at all.
logger.info("Retained %d structures for downstream optimisation.", references.shape[0])
Retained 2 structures for downstream optimisation.
Total running time of the script: (0 minutes 0.296 seconds)