.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "examples/advanced/13_replica_exchange.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_13_replica_exchange.py: Temperature Replica Exchange (REMD) =================================== A single low-temperature trajectory gets stuck: the barrier it needs to cross is many :math:`k_BT` high, so it may never be crossed in the time available. Replica exchange runs a ladder of temperatures at once and periodically swaps which walker sits at which temperature. A configuration that wanders up the ladder crosses barriers easily at high temperature, and when it comes back down it lands in a basin the cold replica might never have reached on its own. The whole ladder is **one batch**: each graph is a walker, and ``thermodynamic_state_id`` records which rung it currently occupies. One batched force evaluation advances every replica per step. Exchange swaps **labels, not coordinates**. A walker keeps its execution slot, its velocities, and its integrator arrays; the temperature assigned to it changes. That makes the move local — nothing is copied between rows — which is what allows it inside a batched GPU step. Key concepts demonstrated ------------------------- * Building a geometric temperature ladder with :class:`~nvalchemi.enhanced_sampling.ThermodynamicState`. * The even/odd pair schedule and the Metropolis acceptance rule. * Reading per-pair acceptance rates, which is how a ladder is tuned. * Confirming the integrator's target temperature follows the assignment. Applications ------------ * Conformer and reaction-path exploration where barriers exceed a few kT. * Crystal polymorph search and nucleation. * Generating diverse training configurations for a potential. .. GENERATED FROM PYTHON SOURCE LINES 49-73 .. code-block:: Python from __future__ import annotations import logging import os import torch from nvalchemi.data import AtomicData, Batch from nvalchemi.dynamics import KB_EV, NVTLangevin from nvalchemi.enhanced_sampling import ( EnhancedSampling, ReplicaExchange, ThermodynamicState, ) 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 = 80 if os.environ.get("NVALCHEMI_SPHINX_BUILD") else 400 .. GENERATED FROM PYTHON SOURCE LINES 74-80 Build the temperature ladder ---------------------------- A geometric spacing keeps the acceptance rate roughly uniform across rungs: the acceptance depends on the *ratio* of neighbouring temperatures, not their difference, so evenly spaced temperatures would exchange readily at the cold end and almost never at the hot end. .. GENERATED FROM PYTHON SOURCE LINES 80-91 .. code-block:: Python N_REPLICAS = 4 BASE_TEMPERATURE = 80.0 # K — argon is liquid around here LADDER_FACTOR = 1.25 states = [ ThermodynamicState(state_id=i, temperature=BASE_TEMPERATURE * LADDER_FACTOR**i) for i in range(N_REPLICAS) ] logger.info("Temperature ladder (K): %s", [round(s.temperature, 1) for s in states]) .. rst-class:: sphx-glr-script-out .. code-block:: none Temperature ladder (K): [80.0, 100.0, 125.0, 156.2] .. GENERATED FROM PYTHON SOURCE LINES 92-96 One walker per rung ------------------- Output buffers must exist up front — dynamics writes model outputs back in place rather than creating the fields. .. GENERATED FROM PYTHON SOURCE LINES 96-123 .. code-block:: Python N_ATOMS = 8 def make_cluster(seed: int) -> AtomicData: """Return an argon cluster on a cube at the LJ minimum separation.""" 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)] ) torch.manual_seed(seed) positions = grid[:N_ATOMS] * spacing + 0.05 * torch.randn(N_ATOMS, 3) 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(seed) for seed in range(N_REPLICAS)]).to( DEVICE ) .. GENERATED FROM PYTHON SOURCE LINES 124-131 Configure the exchange ---------------------- ``initial_state_ids`` must be a permutation: replica exchange presumes one walker per rung, and a duplicate would let two walkers claim the same temperature. Acceptance randomness is derived from ``random_seed`` plus an attempt counter, so a run is reproducible and a checkpoint needs only two integers rather than an RNG blob. .. GENERATED FROM PYTHON SOURCE LINES 131-142 .. code-block:: Python exchange = ReplicaExchange( states=states, initial_state_ids=torch.arange(N_REPLICAS), attempt_interval=10, # dynamics steps per exchange segment random_seed=2024, ) logger.info("Acceptance rule inferred from the ladder: %s", exchange.acceptance) logger.info("Segment 0 pairs: %s", exchange.pair_schedule(0)) logger.info("Segment 1 pairs: %s", exchange.pair_schedule(1)) .. rst-class:: sphx-glr-script-out .. code-block:: none Acceptance rule inferred from the ladder: temperature Segment 0 pairs: [(0, 1), (2, 3)] Segment 1 pairs: [(1, 2)] .. GENERATED FROM PYTHON SOURCE LINES 143-150 Run --- The strategy validates up front that the engine can rebind a thermodynamic state. An integrator that could only accept the new label would keep sampling the old temperature — wrong, and with no symptom the run would show — so ``NVE`` and friends are rejected rather than silently mis-sampled. .. GENERATED FROM PYTHON SOURCE LINES 150-169 .. 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": BASE_TEMPERATURE, "friction": 0.05, }, biases={}, # pure temperature REMD; biases would compose here replica_exchange=exchange, steps_per_epoch=100, extra_hooks=list(model.make_neighbor_hooks()), ) batch = sampling.run(batch, n_steps=N_STEPS) .. GENERATED FROM PYTHON SOURCE LINES 170-176 Read the acceptance statistics ------------------------------ Per-pair rates are what a ladder is tuned on. A pair far below the others is a gap the walkers cannot cross, and the ladder needs another rung there; uniformly high rates mean the rungs are closer than they need to be and the ladder is wasting replicas. .. GENERATED FROM PYTHON SOURCE LINES 176-201 .. code-block:: Python logger.info("") logger.info( "Overall acceptance: %d/%d = %.2f", exchange.accepted, exchange.attempts, exchange.acceptance_rate, ) for index, rate in enumerate(exchange.pair_acceptance_rates()): logger.info( " states %d <-> %d (%.0f K <-> %.0f K): %.2f", index, index + 1, states[index].temperature, states[index + 1].temperature, rate, ) # Expect near-unit acceptance here: an 8-atom cluster has energy fluctuations # far smaller than the spread between rungs, so the Metropolis exponent stays # close to zero and almost everything is accepted. That is the "rungs closer # than they need to be" regime — a production system of thousands of atoms # has much larger fluctuations, and the ladder would be widened until the # rates land near the usual 20-30% target. .. rst-class:: sphx-glr-script-out .. code-block:: none Overall acceptance: 11/11 = 1.00 states 0 <-> 1 (80 K <-> 100 K): 1.00 states 1 <-> 2 (100 K <-> 125 K): 1.00 states 2 <-> 3 (125 K <-> 156 K): 1.00 .. GENERATED FROM PYTHON SOURCE LINES 202-208 Confirm the swap was indivisible -------------------------------- The label, the integrator's target temperature, the velocity scaling, and the forces all have to move together. A walker whose label says one rung while its thermostat still targets another would sample the wrong ensemble silently, so it is worth asserting rather than assuming. .. GENERATED FROM PYTHON SOURCE LINES 208-224 .. code-block:: Python assignment = batch.thermodynamic_state_id.reshape(-1).tolist() engine = sampling.dynamics() targets = (engine._state.temperature.reshape(-1) / KB_EV).tolist() logger.info("") logger.info("Final assignment (walker -> state): %s", assignment) for walker, state_id in enumerate(assignment): expected = states[state_id].temperature logger.info( " walker %d holds state %d: target %.1f K (ladder says %.1f K)", walker, state_id, targets[walker], expected, ) .. rst-class:: sphx-glr-script-out .. code-block:: none Final assignment (walker -> state): [0, 2, 1, 3] walker 0 holds state 0: target 80.0 K (ladder says 80.0 K) walker 1 holds state 2: target 125.0 K (ladder says 125.0 K) walker 2 holds state 1: target 100.0 K (ladder says 100.0 K) walker 3 holds state 3: target 156.3 K (ladder says 156.2 K) .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.075 seconds) .. _sphx_glr_download_examples_advanced_13_replica_exchange.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: 13_replica_exchange.ipynb <13_replica_exchange.ipynb>` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: 13_replica_exchange.py <13_replica_exchange.py>` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: 13_replica_exchange.zip <13_replica_exchange.zip>` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_