.. _move-vmmc:

===============================
Virtual-Move Monte Carlo (VMMC)
===============================

:Keyword: ``MOVE_VMMC``
:Move code: 14
:Status: experimental (requires ``EXPERIMENTAL_FEATURES : True``)

VMMC (Whitelam & Geissler, *J. Chem. Phys.* **127**, 154101, 2007) is a collective
move that lets correlated groups of chains move together, escaping the kinetic
traps that single-chain moves hit in strongly-attractive / condensed phases.

How it works
============

A **seed** chain is chosen and given a trial rigid translation. PIMMS then builds a
moving **cluster** around it by recruiting neighbours according to
*interaction-energy gradients*: a neighbouring chain is pulled in when moving the
seed *alone* would break their mutual attraction. Concretely, for a cluster member
:math:`m` and an interacting neighbour :math:`j`, a **link** is formed with
probability

.. math::
   :label: vmmc-link

   p^\text{f}_{mj} = \max\!\Bigl(0,\; 1 - e^{-(E^{+}_{mj} - E^0_{mj})/T}\Bigr),

where :math:`E^0_{mj}` is the current :math:`m`-:math:`j` interaction energy and
:math:`E^{+}_{mj}` is that energy after displacing :math:`m` alone by the trial
vector. If moving :math:`m` alone would raise the energy (weaken the bond),
:math:`j` is recruited. Recruitment iterates outward until no further chains join,
and the whole cluster is then translated rigidly. This way an attractively-bound
group moves as a unit instead of being torn apart bond-by-bond.

Why detailed balance holds
==========================

VMMC is a **Metropolis-Hastings** move in which the *recruitment is the proposal*.
The probability of proposing a particular cluster move is the product, over every
neighbour pair tested, of forming the links that were formed and failing the links
that were not:

.. math::

   g(x\to y) = \Bigl(\textstyle\prod_\text{formed} p^\text{f}\Bigr)
               \Bigl(\textstyle\prod_\text{failed} (1-p^\text{f})\Bigr).

The reverse move is generated by the *same* construction with the trial
displacement reversed, giving link-formation/failure probabilities
:math:`p^\text{r}` and :math:`1-p^\text{r}` evaluated from the
:math:`-` (reverse) virtual displacement. The Metropolis-Hastings acceptance
:eq:`mh` is then

.. math::

   A(x\to y) = \min\!\left(1,\;
   e^{-\Delta E/T}\,
   \prod_\text{formed}\frac{p^\text{r}}{p^\text{f}}\,
   \prod_\text{boundary}\frac{1-p^\text{r}}{1-p^\text{f}}\right),

where :math:`\Delta E` is the total (interfacial) energy change of the rigid
cluster move - intra-cluster interactions are unchanged - and the "boundary"
product runs over the cluster-surface pairs whose link was tested but not formed.
A formed link with :math:`p^\text{r}=0`, or a boundary link with
:math:`p^\text{r}=1`, makes the reverse move impossible and is rejected outright.
Because this is exactly the Hastings ratio for the recruitment proposal, the move
satisfies detailed balance for *any* interaction model.

Two further ingredients keep it correct and efficient:

* a **cluster-size cutoff** drawn from :math:`Q(n_c)\propto 1/n_c` *before* growth,
  which is direction-independent (it cancels between forward and reverse) and
  enforces equal per-chain move frequency;
* a **hard-core check** - if the rigid translation overlaps a non-cluster bead the
  move is rejected (an infinite-energy state).

The implementation computes :math:`\Delta E` from a full, exact energy recompute
and is validated by a detailed-balance test in a dense, strongly-attractive system
(crank+VMMC reaches the same equilibrium as crankshaft alone while accepting many
multi-chain cluster moves).

Configuration
=============

``MOVE_VMMC`` : float
    Probability of selecting a VMMC move (all ``MOVE_*`` must sum to 1.0).

``VMMC_MAX_DISPLACEMENT`` : int
    Maximum magnitude (per dimension, lattice units) of the trial translation. Use
    **small** values (1-2): large rigid translations almost never clear hard-core
    clashes in dense phases. Default 3.

``VMMC_MAX_CLUSTER`` : int
    Upper bound on the cluster-size cutoff draw (clamped to the number of chains at
    runtime). Default 1000.

VMMC is the move of choice for rearranging dense/condensed phases and studying
self-assembly, where it dramatically outperforms single-chain moves at escaping
kinetic traps.