CHARMM c28a3 adumb.doc

===============================================================================


File: ADUMB ]-[ Node: Top
Up: (commands.doc) -=- Next: Syntax



                   Adaptive Umbrella Sampling Module 

    Setting up of adaptive umbrella potentials. Currently supported types
of umbrella potentials are functions of dihedral angles and functions of the 
potential energy of the system (energy sampling).

WARNING: The module is still being developed and some details are likely
         to change in future versions.
         Please report problems to Christian Bartels at cb@brel.u-strasbg.fr

REFERENCES:
         C. Bartels & M. Karplus, J. Comp. Chem. 18 (1997) 1450-
         C. Bartels & M. Karplus, J. Phys. Chem. 102 (1998) 865-
         M. Schaefer, C. Bartels, & M. Karplus, J. Mol. Biol. (1998)

* Menu:

* Syntax::      Syntax of the ADUMB commands
* Function::    Purpose of each of the commands
* Examples::    Usage examples of the ADUMB module



File: ADUMB ]-[ Node: Syntax
Up: Top -=- Previous: Top -=- Next: Function



                                 Syntax

[SYNTAX ADUMB functions]

Syntax:

ADUMb DIHE    NRES int  TRIG int  POLY int  4X(atom-spec)

ADUMb ENER    NRES int   TRIG int   POLY int
              MAXE real  MINE real  [MAXT real] [MINT real]

ADUMb INIT    NSIM int  [UPDA int] [EQUI int]  [TEMP real] 
              [AGIN real] [NEXT int] [THRE real]
              [UCUN int]  [WUNI int] [RUNI int]

ADUMb PROB    UCUN int [TEMP real] [PUNI int] [TUNI int]

ADUMb STON

ADUMb STOFf

where:      atom-spec ::= { segid resid iupac }
                          { resnumber iupac   }




File: ADUMB ]-[ Node: Function
Up: Top -=- Previous: Syntax -=- Next: Examples

 



0.  Introduction

    The module provides commands to define degrees of freedom along which 
adaptive umbrella potentials are applied in molecular dynamics 
simulations. Statistics on the sampling of the degrees of freedom are recorded
during the md simulations and periodically used to update the umbrella
potential such that uniform sampling of the degrees of freedom can be
expected. Currently, dihedral angles and the potential energy are supported
as degrees of freedom.

   If several degrees of freedom are defined, multidimensional adaptive
umbrella sampling is performed.

   Two sorts of input/output files are used by the module. The "umbrella" 
files contain the umbrella potentials that were used in the simulations 
together with the statistics of the sampling of the bins during the 
simulations. Based on this information the potential of mean force can be 
calculated and the umbrella potential expected to lead to uniform sampling 
can be determined. The second sort of files contains the values of the 
umbrella coordinates (=degree of freedom for adaptive umbrella sampling) 
for each time step in which coordinates were saved to the trajectory files. 
The umbrella coordinates are normalized to the range 0 to 1, independent of 
the degrees of freedom used. From the umbrella coordinates saved, weighting 
factors can be calculated which are needed to calculate average properties of 
the unbiased system.



1.  ADUMb DIHE 

    Define a dihedral angle as degree of freedom for adaptive umbrella
sampling. To record the statistics the degree of freedom is partitioned
into NRES bins. The umbrella potentials are represented as a linear combination
of two times TRIG trigonometric functions and polynomial functions of degree 
0 to POLY - 1. Repeating the command results in a multidimensional adaptive
umbrella potential.

    The coordinates written to the umbrella coordinates file are normalized 
to the range 0 to 1 with 0 corresponding to -180 degrees and 1 corresponding
to +180 degrees.



2.  ADUMb ENER

    Define the potential energy as degree of freedom for adaptive umbrella
sampling. NRES, TRIG and POLY have the same meaning as in ADUMb DIHE.
MINE and MAXE specify the potential energy range: Statistics on the sampling 
are recorded in the range MINE-0.5*(MAXE-MINE) to MAXE+0.5*(MAXE-MINE). In 
the range outside of MINE to MAXE the umbrella potential is kept constant 
to prevent the system from leaving the range in which statistics are recorded. 
MINT and MAXT (default values: 273 K and 1000 K, respectively) are minimal 
and maximal temperatures to restrict sampling in the relevant temperature 
range. To set up a system, get a rough estimate of the potential energy of the 
system at the desired TMIN and TMAX (from short unbiased simulations at 
TMIN and TMAX).  Set EMIN and EMAX to the values determined minus/plus a 
small tolerance, respectively.

    The coordinates written to the umbrella coordinates file are normalized 
to the range 0 to 1 with 0 corresponding to MINE-0.5*(MAXE-MINE) and 1
corresponding to MAXE+0.5*(MAXE-MINE).



3.  ADUMb INIT

    Defines or redefines the parameters for adaptive umbrella sampling and
initializes the umbrella potential. The umbrella potential is updated
every UPDAte steps. After each update, no statistics are recorded for
EQUI steps. For the remaining UPDA - EQUI steps, statistics on the sampling
of the umbrella coordinates are recorded and stored separately from previous
statistics and together with the umbrella potential active when recording the 
statistics. NSIM separate statistics can be kept in memory. If the number of 
updates performed in a run exceeds NSIM, the oldest statistics are discarded 
to make space for the most recent statistics.

    After each update the umbrella potential and the statistics are written
to standard output (the log file). The written table contains, from left
to right, the number of the bin, the number of integration time steps in
which the system was in the bin since the last update, the potential of mean
force calculated with the WHAM equations, the negative of the updated
umbrella potential (potential of mean force modified to restrict sampling if 
necessary and fitted to the set of trigonometric and polynomial functions),
the total number of times the bin was visited in the entire simulation, and
the umbrella coordinates of the center of the bin.

    The temperature TEMP should be set to the temperature used in 
the simulations. It is used to calculate the umbrella potentials from
the sampling statistics and to restrict sampling if potential energy 
sampling is performed. 

    Umbrella coordinates are written to unit UCUN. At each update,
the statistics are written to unit WUNI together with the umbrella potential 
active when recording the statistics. Statistics from previous runs can
be read from unit RUNI. The statistics read must be from adaptive umbrella
sampling simulations with the same parameters as the present one, in 
particular, the same degrees of freedom have to be used as umbrella 
coordinates. If adaptive umbrella sampling of the potential energy is 
used, umbrella potentials from runs at different temperatures can
be read by repeating the ADUMb INIT command with RUNI set to the unit
containing the statistics of each of the runs and TEMP set to the temperature
of the run.

    To define the umbrella potential of bins for which no statistics 
have been acquired so far, the umbrella potential has to be extrapolated.
In the current implementation (might change in future implementations),
the umbrella potential of the bins that were not sampled is set to 
the same value (ext-cons). To determine ext-cons, the potential of the bins
that were sampled is linearly extrapolated for NEXT bins, and the maximal
value (max-extrapolated) of the linearly extrapolated potentials is 
determined. Then, the minimal value (min-sampled) of the potentials of the
bins that were sampled is determined and ext-cons is set to min-sampled
or max-extrapolated whatever value is smaller.

    A few statistics that differ significantly from the rest of the 
statistics can be due to problems with the convergence caused by the 
extrapolation or due to the occurrence of rare events. In the former case, 
outliers should occur only in the first few simulations and it is advantageous 
to eliminate them. By default, the module eliminates statistics that 
differ from the averaged statistics by THRE times the average deviation. If
one wants to prevent statistics from being eliminated THRE has to be set to 
a value larger than NSIM. At each update, the deviations of the statistics
from the averaged statistics is printed to standard output (log file), e.g.,

 0 Deviation of simulation     1 :    0.955    
 0 Deviation of simulation     2 :    0.513E-01
 0 Deviation of simulation     3 :    0.787E-01
 0 Deviation of simulation     4 :    0.292    
 0 Deviation of simulation     5 :    0.170    
 0 Deviation of simulation     6 :    0.201    
 0 Deviation of simulation     7 :    0.933    
 0 Deviation of simulation     8 :    0.208    
 0 Deviation of simulation     9 :    0.270    
 0 Deviation of simulation    10 :    0.131    
 0 Deviation of simulation    11 :    0.394    
 0 Deviation of simulation    12 :     1.52    
 0 Deviation of simulation    13 :    0.969    
 0 Deviation of simulation    14 :    0.502    
 0 Deviation of simulation    15 :     1.47    
 0 Deviation of simulation    16 :     2.97    
-1 Deviation of simulation    17 :     210.    
 0 Deviation of simulation    18 :    0.695E-01
 0 Deviation of simulation    19 :    0.160    
 0 Deviation of simulation    20 :    0.450    

The 0 or -1 on each line indicates whether the statistics of a particular 
simulation are used (0) or were discarded (-1) based on the THRE criterion.

    For complex systems, there might exist no umbrella potential that
enables the system to diffuse rapidly along the umbrella coordinate. In 
such cases it has been found to be advantageous to give a higher weight 
to the most recent statistics. This is implemented using the AGINg factor. 
For an umbrella potential calculated from n statistics, the i'th statistics
(i=1,2,..,n) are weighted by AGINg**(n-i).



4. ADUMb PROB

    Average properties of the unbiased system can be obtained by weighting
the conformations of an adaptive umbrella sampling run by appropriate
factors. The ADUMb PROB command calculates these weighting factors from
the umbrella coordinates read from unit UCUN and writes them to unit PUNI. 
For the command to work the umbrella potentials and statistics from the
run must have been read with the ADUMb INIT command. If the potential
energy was used as umbrella coordinate, the TEMP specifies the temperature
at which properties of the unbiased system should be calculated.



5. ADUMb STON
   ADUMb STOFf
    By default statistics on the sampling of the umbrella coordinates are
recorded in each call to the energy routines. The ADUMb STOFf command
prevents that statistics are recorded. This might be useful when doing
a minimization or running a md simulation with an umbrella potential
that should not change during the simulation.







File: ADUMB ]-[ Node: Examples
Up: Top -=- Previous: Function -=- Next: Top



                                Examples

        This examples are meant to be a partial guide in setting up
an input file for ADUMB. There are three test files, adumb-phichi.inp,
adumb-enum.inp and ace2.inp.

Example (1) 
-----------
Set up and run an adaptive umbrella sampling simulation using two dihedral
angles as umbrella coordinates.


! define the phi and chi1 dihedral angle as the two umbrella coordinates
umbrella dihe nresol 36 trig  6 poly 1 pept 1 N  pept 1 CA pept 1 CB pept 1 OG1
umbrella dihe nresol 36 trig  6 poly 1 pept 1 CY  pept 1 N pept 1 CA pept 1 C

umbrella init nsim 100 update 10000 equi 1000 thresh 10 temp 300 -
              ucun 10 wuni 11

! perform adaptive umbrella sampling md simulation
dynamics nose tref 300 qref 20 start -
             nstep 20000 timestep 0.001 -
             ihbfrq 0 inbfrq 10  ilbfrq 5 -
             iseed 12 -
             nprint 1000  iprfreq 1000 -
             isvfrq 1000  iunwrite -1 iunread -1 -
             wmin 1.2

Example(2)
----------
Set up and run an adaptive umbrella sampling simulation using the potential
energy as umbrella coordinate (=energy sampling, multicanonical simulation,
entropic sampling).

! set up umbrella; the range of relevant potential energies is assumed to
! extend form -50 kcal/mol to 100 kcal/mol. 
umbrella ener nresol 200 trig 20 poly 5 mine -50 maxe 100.0 mint 280 maxt 2000

open write formatted   unit 9 name  @9enum.umb
open write formatted   unit 10 name @9enum.uco
open write unformatted unit 11 name  @9enum.cor 

umbrella init nsim 100 update 10000 equi 1000 temp 1000 thres 100 -
              wuni 9 ucun 10

! energy sampling simulation 
dynamics langevin start -
             nstep 50000 timestep 0.001 -
             inbfrq 10  ilbfrq 10 rbuffer 0.0 tbath 1000 -
             iseed 12 -
             nprint 1000  iprfreq 1000 -
             isvfrq 1000  iunwrite -1 iunread -1 -
             nsavc  100 iuncrd 11  -
             wmin 1.2

Example(3)
----------
Determine the weighting factors to calculate properties of the
unbiased system.

! define the umbrella coordinates
umbrella ener nresol 200 trig 20 poly 5 mine -50 maxe 100.0 mint 280 maxt 2000
         
open read formatted    unit 10 name ../scr/@n.umb
umbrella init nsim 100 update 10000 equi 1000 runi 10 temp 1000 thres 200

! translate umbrella coordinates into probability factors at 300K
open read formatted    unit 11 name ../scr/@n.uco
open write formatted   unit 12 name ../scr/@nT300K.pfa

umbrella prob ucun 11 puni 12 temp 300

! translate umbrella coordinates into probability factors at 1000K
open read formatted    unit 11 name ../scr/@n.uco
open write formatted   unit 12 name ../scr/@nT1000K.pfa

umbrella prob ucun 11 puni 12 temp 1000


CHARMM .doc Homepage


Information and HTML Formatting Courtesy of:

NIH/DCRT/Laboratory for Structural Biology
FDA/CBER/OVRR Biophysics Laboratory
Modified, updated and generalized by C.L. Brooks, III
The Scripps Research Institute