.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "examples/advanced/12_umbrella_sampling.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_examples_advanced_12_umbrella_sampling.py: Batched Umbrella Sampling with EnhancedSampling =============================================== Umbrella sampling computes a free-energy profile along a reaction coordinate by running several simulations, each restrained to a different value of that coordinate. The restraints keep the system in regions it would otherwise never visit; the resulting biased histograms are recombined afterwards with WHAM or MBAR. The usual cost is that every window is a separate simulation. Here all windows are **rows of one batch**: each graph carries a ``thermodynamic_state_id`` selecting its own window center, so a single :class:`~nvalchemi.enhanced_sampling.HarmonicUmbrellaBias` serves all of them in one batched GPU force evaluation. This example restrains the distance between two argon atoms in a Lennard-Jones cluster across five windows, and adds an :class:`~nvalchemi.enhanced_sampling.UpperWall` to stop any window wandering off to dissociation. Key concepts demonstrated ------------------------- * A collective variable as a plain callable over :func:`~nvalchemi.enhanced_sampling.pair_distance`. * Per-window centers selected by ``thermodynamic_state_id``. * Composing two biases; they are summed against the *same* unmodified model output, so neither observes the other's forces. * Reading per-bias diagnostics from ``sampling.last_outputs``. Applications ------------ * Free-energy profiles along a bond, a distance, or a coordination number. * Potential of mean force for ion transport or ligand unbinding. * Restrained sampling to generate training data in a targeted region. .. GENERATED FROM PYTHON SOURCE LINES 51-77 .. code-block:: Python 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, HarmonicUmbrellaBias, UpperWall, 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 real run needs orders of magnitude more steps. N_STEPS = 20 if os.environ.get("NVALCHEMI_SPHINX_BUILD") else 200 .. GENERATED FROM PYTHON SOURCE LINES 78-83 Build one window per restraint center ------------------------------------- Every window is an independent copy of the same cluster. The output buffers (``forces``, ``energy``) must exist up front: dynamics writes model outputs back in place rather than creating the fields. .. GENERATED FROM PYTHON SOURCE LINES 83-121 .. code-block:: Python WINDOW_CENTERS = [3.0, 3.5, 4.0, 4.5, 5.0] # angstrom N_ATOMS = 8 torch.manual_seed(0) def make_cluster() -> AtomicData: """Return one argon cluster with the buffers dynamics writes into. Atoms sit on a 2x2x2 cube at the LJ minimum separation. Random positions would place some pairs well inside sigma = 3.4 A, where the repulsive wall is steep enough that the first step diverges — the restraint is then blamed for what is really an overlapping start. """ spacing = 4.0 # ~2^(1/6) * sigma, near the LJ minimum 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 # Atoms 0 and 1 are a cube edge apart, so the CV starts at `spacing`. 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 WINDOW_CENTERS]).to(DEVICE) # Each graph gets its own window. This is the field HarmonicUmbrellaBias # indexes to pick a center, and it is what makes one batch five windows. batch["thermodynamic_state_id"] = torch.arange(len(WINDOW_CENTERS), device=DEVICE) .. GENERATED FROM PYTHON SOURCE LINES 122-126 Define the collective variable ------------------------------ A CV is any differentiable ``cv(batch) -> Tensor[B, D]``. No base class, no registration — a closure over :func:`pair_distance` is a complete CV. .. GENERATED FROM PYTHON SOURCE LINES 126-135 .. code-block:: Python 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) .. GENERATED FROM PYTHON SOURCE LINES 136-141 Build the biases ---------------- ``centers`` has shape ``[S, D]`` — one row per window, one column per CV dimension. ``stiffness`` broadcasts across windows here, but could equally be per-window with shape ``[S, D, D]``. .. GENERATED FROM PYTHON SOURCE LINES 141-159 .. code-block:: Python umbrella = HarmonicUmbrellaBias( cv=bond_distance, centers=torch.tensor(WINDOW_CENTERS).unsqueeze(-1), # [5, 1] stiffness=5.0, # eV/A^2 name="umbrella", ) # A one-sided wall stops a window that escapes its basin from running away to # dissociation. It contributes exactly zero energy and force while the # distance stays below the threshold. wall = UpperWall( cv=bond_distance, threshold=8.0, stiffness=20.0, name="dissociation_wall", ) .. GENERATED FROM PYTHON SOURCE LINES 160-166 Run biased dynamics ------------------- ``EnhancedSampling`` is a ``DynamicsStrategy``: a recipe for the engine rather than a wrapper around a live one. It contributes hooks and leaves everything else alone — the model, the integrator, and the thermostat are unchanged. .. GENERATED FROM PYTHON SOURCE LINES 166-189 .. code-block:: Python 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": 120.0, "friction": 0.05}, biases={"umbrella": umbrella, "dissociation_wall": wall}, # A cutoff model needs its neighbour list rebuilt at BEFORE_COMPUTE. # ``extra_hooks`` are registered after the strategy's own, and priming # fires that stage too, so the first force evaluation is as valid as # every later one. extra_hooks=list(model.make_neighbor_hooks()), ) logger.info("Initial CV per window: %s", bond_distance(batch).flatten().tolist()) batch = sampling.run(batch, n_steps=N_STEPS) final_cv = bond_distance(batch).flatten().tolist() logger.info("Target centers: %s", WINDOW_CENTERS) logger.info("Final CV per window: %s", [round(v, 3) for v in final_cv]) .. rst-class:: sphx-glr-script-out .. code-block:: none Initial CV per window: [4.0, 4.0, 4.0, 4.0, 4.0] Target centers: [3.0, 3.5, 4.0, 4.5, 5.0] Final CV per window: [3.885, 3.941, 4.001, 4.034, 4.085] .. GENERATED FROM PYTHON SOURCE LINES 190-198 Read the diagnostics -------------------- ``last_outputs`` separates the physical model contribution from each bias and from the total. These are the tensors a WHAM/MBAR post-processing step needs: the CV value, the physical energy, and the bias energy per window. Free-energy reconstruction is deliberately **not** built in — the raw per-window data is returned for ``pymbar`` or an equivalent tool. .. GENERATED FROM PYTHON SOURCE LINES 198-213 .. code-block:: Python for key in sorted(sampling.last_outputs): value = sampling.last_outputs[key] logger.info(" %-28s shape=%s", key, tuple(value.shape)) umbrella_energy = sampling.last_outputs["bias/umbrella/energy"].flatten() logger.info( "Umbrella energy per window (eV): %s", [round(float(v), 4) for v in umbrella_energy] ) # The wall should be dormant: every window is well inside 8 A. wall_energy = sampling.last_outputs["bias/dissociation_wall/energy"].flatten() logger.info( "Wall energy per window (eV): %s", [round(float(v), 4) for v in wall_energy] ) .. rst-class:: sphx-glr-script-out .. code-block:: none bias/dissociation_wall/energy shape=(5, 1) bias/dissociation_wall/forces shape=(40, 3) bias/umbrella/energy shape=(5, 1) bias/umbrella/forces shape=(40, 3) bias_total/energy shape=(5, 1) bias_total/forces shape=(40, 3) physical/energy shape=(5, 1) physical/forces shape=(40, 3) total/energy shape=(5, 1) total/forces shape=(40, 3) Umbrella energy per window (eV): [1.9582, 0.486, 0.0, 0.5434, 2.0913] Wall energy per window (eV): [0.0, 0.0, 0.0, 0.0, 0.0] .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.085 seconds) .. _sphx_glr_download_examples_advanced_12_umbrella_sampling.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: 12_umbrella_sampling.ipynb <12_umbrella_sampling.ipynb>` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: 12_umbrella_sampling.py <12_umbrella_sampling.py>` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: 12_umbrella_sampling.zip <12_umbrella_sampling.zip>` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_