docs/doxygen/lib/awh.md

   1 The accelerated weight histogram method (AWH) {#page_awh}
   2 =============================================
   3
   4 Accelerating sampling with AWH
   5 ==============================
   6
   7 AWH calculates the free energy along an order parameter of the system.
   8 Free energy barriers are overcome by adaptively tuning a bias potential along
   9 the order parameter such that the biased distribution along the parameter
  10 converges toward a chosen target distribution.
  11 The fundamental equation governing the tuning is: log(target) = bias - free energy, where
  12 the bias and free energy are initially unknown. Typically the target distribution is simply
  13 chosen uniform, such that the bias completely flattens the free energy landscape.
  14
  15
  16 Design of the AWH module
  17 ========================
  18
  19 The module implements AWH for the case when the order parameter corresponds to a reaction coordinate,
  20 here referred to as coordinate for short, i.e. a function of the system configuration.
  21 The bias is coupled to the system by a bias potential: either in the form of an harmonic ("umbrella") potential
  22 Monte-Carlo (MC) "jumping" around the current coordinate value, or as a smooth convolution of the umbrellas.
  23
  24 The AWH module is organizes as follows:
  25 The Awh class is the interface between the outside and inside of the module.
  26 The Awh class contains one or more BiasCoupledToSystem objects.
  27 The BiasCoupledToSystem class takes care of the reaction coordinate input
  28 and force output for the single Bias object it containts.
  29 The Bias class is a container and wrapper for a object BiasState + helpers.
  30 All computation takes place in the BiasState object and its sub-classes.
  31 The Bias class also contains a BiasWriter object that takes care of i/o.
  32
  33 Use of AWH in mdrun
  34 ===================
  35
  36 The basic use of Awh in mdrun consists of 2 method calls:
  37 Call the constructor Awh() after the pull module has been initialized.
  38 Call applyBiasForcesAndUpdateBias() at every MD step after the pull
  39 potential calculation function has been called.
  40
  41 In grompp the pull potential provider should be registered using
  42 registerAwhWithPull() so grompp can check for unregistered potentials.
  43
  44 The main tasks of AWH are:
  45 - calculate and set the bias force given the current coordinate value.
  46 - after accumulating a number of coordinate samples, update the free energy estimate and the bias.
  47
  48 AWH currently relies on the pull code for the first task. Pull provides AWH with updated coordinate values
  49 and distributes the bias force that AWH calculates to the atoms making up the coordinate. This
  50 also means that there are some order dependencies where pull functions need to be called before AWH
  51 functions (see below).
  52
  53 The implementation is quite general. There can be multiple independent AWH biases coupled to the system
  54 simultaneously. This makes sense if the system is made up of several fairly independent parts,
  55 like monomers in a protein. Each bias acts on exactly one, possibly multidimensional, coordinate.
  56 Each coordinate dimension maps to exactly one pull coordinate. Thus, an n-dimensional
  57 biased coordinate is defined by a set of n pull coordinates. Periodicity is taken care of for coordinate
  58 dimensions that require it (dihedral angles). For increased parallelism, there is the option of
  59 having multiple communicating simulations sharing all samples. All simulations would then share a single
  60 bias and free energy estimate. Alternatively, one may partition the sampling domain into smaller
  61 subdomains with some overlap and have multiple independent simulations sample each subdomain.
  62
  63 Note that internally the AWH module keep tracks of free energies in units
  64 of the thermal energy kT. This is because we mostly deal with free energies
  65 in the form of -log(probability) and using any other unit would be bug prone.
  66 All energy type variables are explicitly documented to be in units of kT.
  67 Also the checkpoint and energy file data is in units of kT. The analysis
  68 tool will by default convert energies to kJ/mol, but there is also
  69 a kT option.
  70