Multiple-Walker Well-Tempered Metadynamics#

Metadynamics fills the free-energy basin the system is sitting in with Gaussian hills, until the barrier out of it is no longer a barrier. Where umbrella sampling needs you to know in advance which values of the reaction coordinate to restrain to, metadynamics discovers them: it goes wherever it has not already been.

The well-tempered variant shrinks each new hill in proportion to the bias already accumulated at that point,

\[h_t = h_0 \exp\!\left(-\frac{V(s_t)}{k_B T (\gamma - 1)}\right)\]

so the sum converges instead of filling forever, and the converged bias can be turned back into a free-energy profile.

This example runs the multiple-walker scheme: several walkers explore the same collective variable at once, all depositing into one shared hill history, so a basin is filled roughly B times faster. Because the walkers are rows of a single batch, that costs one batched GPU force evaluation per step, not B separate simulations.

Key concepts demonstrated#

  • Depositing hills on a schedule with frequency, driven by EnhancedSampling.

  • Shared multi-walker history, and how it differs from private history.

  • Choosing a storage policy, and why preallocated raises rather than silently discarding hills.

  • Recovering a free-energy profile with free_energy().

Applications#

  • Free-energy profiles when the relevant windows are not known in advance.

  • Escaping metastable states that plain MD would stay trapped in.

  • Barrier crossing for conformational change, dissociation, or diffusion.

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,
    UpperWall,
    WellTemperedMetaDynamicsBias,
    pair_distance,
)
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"
# Keep the doc build fast; a converged run needs orders of magnitude more.
N_STEPS = 40 if os.environ.get("NVALCHEMI_SPHINX_BUILD") else 600

Build the walkers#

Four independent copies of the same argon cluster. They are not windows: no walker is restrained anywhere, and they differ only in the random velocities the thermostat gives them.

N_WALKERS = 4
N_ATOMS = 8
TEMPERATURE = 120.0  # K

torch.manual_seed(0)


def make_cluster() -> AtomicData:
    """Return one argon cluster with the buffers dynamics writes into.

    Atoms sit on a 2x2x2 cube near the LJ minimum separation; random
    positions would place some pairs inside sigma, where the repulsive wall
    is steep enough that the first step diverges.
    """
    spacing = 4.0
    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)]
    )
    data = AtomicData(
        positions=grid[:N_ATOMS] * spacing,
        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)

Define the collective variable#

The same plain-callable contract as umbrella sampling: any differentiable cv(batch) -> Tensor[B, D].

ATOM_PAIR = torch.tensor([0, 1], device=DEVICE)


def bond_distance(atoms: Batch) -> torch.Tensor:
    """Distance between atoms 0 and 1, shape ``[B, 1]``."""
    return pair_distance(atoms, ATOM_PAIR)

Configure the bias#

Three choices carry most of the physics:

sigma

Hill width, in CV units. Roughly the resolution of the resulting free energy: too wide smears out real features, too narrow needs far more hills to fill anything.

bias_factor (gamma)

Sets how high the bias is allowed to climb — the effective temperature of the CV is gamma * T. Larger explores further and converges slower. Passing None gives standard, non-converging metadynamics.

frequency

Steps between depositions. Depositing faster than the system decorrelates biases the estimate; the usual choice is a few hundred steps.

storage="preallocated" keeps the hill tensors a fixed shape for the whole run, which is what keeps energy() compilable without retracing. It raises when max_hills is exhausted rather than dropping hills: silently discarding them would change the physics of a converging run with no error to show for it.

metad = WellTemperedMetaDynamicsBias(
    cv=bond_distance,
    height=0.005,  # eV
    sigma=0.25,  # angstrom
    temperature=TEMPERATURE,
    bias_factor=8.0,
    frequency=25,
    storage="preallocated",
    max_hills=512,
    history="shared",  # multiple-walker: every walker feels every hill
    name="metad",
)

# Metadynamics pushes outward by construction, so an unbounded CV eventually
# dissociates the pair. A wall bounds the explored region without touching
# the interior, where it contributes exactly zero.
wall = UpperWall(cv=bond_distance, threshold=9.0, stiffness=20.0, name="wall")

Run#

The bias hook calls update() exactly once per due step, at AFTER_STEP so each hill marks the configuration the walker actually reached. A deposition bumps the bias state version, and the hook re-primes forces in response, so a new hill is felt on the very next step rather than one step late.

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.05},
    biases={"metad": metad, "wall": wall},
    extra_hooks=list(model.make_neighbor_hooks()),
)

logger.info(
    "Initial CV per walker: %s",
    [round(v, 3) for v in bond_distance(batch).flatten().tolist()],
)

batch = sampling.run(batch, n_steps=N_STEPS)

logger.info(
    "Final CV per walker:   %s",
    [round(v, 3) for v in bond_distance(batch).flatten().tolist()],
)
logger.info(
    "Depositions: %d, hills stored: %d of %d",
    int(metad.deposits),
    int(metad.hill_count),
    metad.capacity,
)
Initial CV per walker: [4.0, 4.0, 4.0, 4.0]
Final CV per walker:   [3.979, 3.979, 4.01, 3.975]
Depositions: 2, hills stored: 8 of 512

Hill heights decay#

This is the well-tempered signature. As the bias accumulates, each new hill is shorter than the last; a run whose recent hills are still near h_0 has not begun to converge.

heights = metad.hill_heights[: int(metad.hill_count)]
logger.info("First hill height: %.6f eV", float(heights[0]))
logger.info("Last hill height:  %.6f eV", float(heights[-1]))
First hill height: 0.005000 eV
Last hill height:  0.003797 eV

Recover the free-energy profile#

F(s) = -(gamma / (gamma - 1)) V(s), up to an additive constant. The profile is only meaningful where hills were actually deposited; the flat regions beyond simply mean the walkers never went there.

grid = torch.linspace(3.0, 8.0, 26, device=DEVICE).unsqueeze(-1)
free_energy = metad.free_energy(grid)
free_energy = free_energy - free_energy.min()

logger.info("Free-energy profile (eV, shifted to zero minimum):")
for value, energy in zip(grid.flatten().tolist(), free_energy.tolist(), strict=True):
    logger.info("  d = %.2f A   F = %.4f eV", value, energy)
Free-energy profile (eV, shifted to zero minimum):
  d = 3.00 A   F = 0.0402 eV
  d = 3.20 A   F = 0.0399 eV
  d = 3.40 A   F = 0.0378 eV
  d = 3.60 A   F = 0.0286 eV
  d = 3.80 A   F = 0.0105 eV
  d = 4.00 A   F = 0.0000 eV
  d = 4.20 A   F = 0.0115 eV
  d = 4.40 A   F = 0.0294 eV
  d = 4.60 A   F = 0.0380 eV
  d = 4.80 A   F = 0.0399 eV
  d = 5.00 A   F = 0.0402 eV
  d = 5.20 A   F = 0.0402 eV
  d = 5.40 A   F = 0.0402 eV
  d = 5.60 A   F = 0.0402 eV
  d = 5.80 A   F = 0.0402 eV
  d = 6.00 A   F = 0.0402 eV
  d = 6.20 A   F = 0.0402 eV
  d = 6.40 A   F = 0.0402 eV
  d = 6.60 A   F = 0.0402 eV
  d = 6.80 A   F = 0.0402 eV
  d = 7.00 A   F = 0.0402 eV
  d = 7.20 A   F = 0.0402 eV
  d = 7.40 A   F = 0.0402 eV
  d = 7.60 A   F = 0.0402 eV
  d = 7.80 A   F = 0.0402 eV
  d = 8.00 A   F = 0.0402 eV

Shared versus private history#

history="shared" is what makes this multiple-walker metadynamics rather than four independent runs: one history, filled four times as fast.

The alternatives are "walker", which gives each walker its own private history and so runs B genuinely independent simulations in one batch, and "state", which keys the history by thermodynamic_state_id for a replica-exchange ladder.

Under "shared" every hill is unowned, which is what the -1 here records.

logger.info("Hill owners (-1 means shared): %s", metad.hill_owner[:4].tolist())
Hill owners (-1 means shared): [-1, -1, -1, -1]

Diagnostics#

As with every bias, the runner separates the physical contribution from each bias and from the total.

for key in sorted(sampling.last_outputs):
    logger.info("  %-28s shape=%s", key, tuple(sampling.last_outputs[key].shape))
bias/metad/energy            shape=(4, 1)
bias/metad/forces            shape=(32, 3)
bias/metad/state_version     shape=(4,)
bias/wall/energy             shape=(4, 1)
bias/wall/forces             shape=(32, 3)
bias_total/energy            shape=(4, 1)
bias_total/forces            shape=(32, 3)
physical/energy              shape=(4, 1)
physical/forces              shape=(32, 3)
total/energy                 shape=(4, 1)
total/forces                 shape=(32, 3)

Total running time of the script: (0 minutes 0.161 seconds)

Gallery generated by Sphinx-Gallery