global/local hyperdynamics src and doc files

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

fix hyper/global command :h3

[Syntax:]

fix ID group-ID hyper/global cutbond qfactor Vmax Tequil :pre

ID, group-ID are documented in "fix"_fix.html command

hyper/global = style name of this fix command

cutbond = max distance at which a pair of atoms is considered bonded (distance units)

qfactor = max strain at which bias potential goes to 0.0 (unitless)

Vmax = height of bias potential (energy units)

Tequil = equilibration temperature (temperature units) :ul

[Examples:]

fix 1 all hyper/global 1.0 0.3 0.8 300.0 :pre

[Description:]

This fix is meant to be used with the "hyper"_hyper.html command to

perform a bond-boost hyperdynamics simulation.  The role of this fix

is a select a single pair of atoms within the system at each timestep

to add a global bias potential to, which will alter their dynamics.

This is in contrast to the "fix hyper/local"_fix_hyper_local.html

command, which can add a local bias potential to multiple pairs of

atoms at each timestep.

For a system that undergoes rare transition events, where one or more

atoms move across an energy barrier to a new potential energy basin,

the effect of the bias potential is to induce more rapid transitions.

This can lead to a dramatic speed-up in the rate at which events

occurs, without altering their relative frequencies, thus leading to

an overall dramatic speed-up in the effective elapsed time of the

simulation.

Cite various papers.

The current strain of a bond IJ is defined as

Eij = (Rij - R0ij) / R0ij :pre

Emax = is the max of the absolute value of Eij for all IJ bonds.

dVij = Vmax * (1 - (Eij/q)^2) for abs(Eij) < q

     = 0  otherwise :pre

Delta Vbias = minimum of dVij for all IJ bonds :pre

The boost factor B = exp(beta * Delta Vbias)

for a single timestep.

Thus the accumulated hypertime is simply

t_hyper = Sum (i = 1 to Nsteps) Bi * dt :pre

The {cutbond} argument is the cutoff distance for defining bonds

between pairs of nearby atoms.  A pair of atoms in their equilibrium,

minimum-energy config, which are a distance Rij < cutbond, are

defined as a bonded pair.

The {qfactor} argument is the limiting strain at which

the Vbias (the bias potential) goes to 0.0.

If {qfactor} is too big, then transitions are affected b/c

the bias energy is non-zero at the transitions.  If it is

too small than not must boost is achieved for a large system

with many bonds (some bonds Eij always exceeds qfactor).

The {Vmax} argument is the prefactor on the bias potential.

The {Tequil} argument is part of the beta term in the

exponential factor that determines how much boost is

achieved as a function of the bias potential.

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart

files"_restart.html.

The "fix_modify"_fix_modify.html {energy} option is supported by this

fix to add the energy of the bias potential to the the system's

potential energy as part of "thermodynamic output"_thermo_style.html.

This fix computes a global scalar and global vector of length 10,

which can be accessed by various "output

commands"_Section_howto.html#howto_15.  The scalar is the magnitude of

the bias potential (energy units) applied on the current timestep.

The vector stores the following quantities:

1 = boost factor on this step (unitless)

2 = max strain of any bond on this step (unitless)

3 = ID of first atom in the max-strain bond

4 = ID of second atom in the max-strain bond

5 = average # of bonds/atom on this step :ul

6 = fraction of step with no bias during this run

7 = max drift distance of any atom during this run (distance units)

8 = max bond length during this run (distance units) :ul

9 = cummulative hyper time since fix created (time units)

10 = cummulative count of event timesteps since fix created

11 = cummulative count of atoms in events since fix created :ul

The first 5 quantities are for the current timestep.  The quantities

6-8 are for the current run.  The quantities 9-11 are cummulative

across multiple runs (since the fix was defined in the input script).

For value 10, events are checked for by the "hyper"_hyper.html command

once every {Nevent} timesteps.  This value is the count of the number

of timesteps on which one (or more) events was detected.  It is NOT

the number of distinct events, since more than one physical event may

occur in the same {Nevent} time window.

For value 11, each time the "hyper"_hyper.html command checks for an

event, the event compute it uses will flag zero or more atoms as

participating in an event.  E.g. atoms that have displaced more than

some distance from the previous quench state.  This value is the count

of the number of atoms participating in any of the events that were

found.

The scalar and vector values calculated by this fix are all

"intensive".

No parameter of this fix can be used with the {start/stop} keywords of

the "run"_run.html command.  This fix is not invoked during "energy

minimization"_minimize.html.

[Restrictions:]

This fix is part of the REPLICA package.  It is only enabled if LAMMPS

was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

[Related commands:]

"fix hyper/local"_fix_hyper_local.html

[Default:] None

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

fix hyper/local command :h3

[Syntax:]

fix ID group-ID hyper/local cutbond qfactor Vmax Tequil Dcut alpha boost :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l

hyper/local = style name of this fix command :l

cutbond = max distance at which a pair of atoms is considered bonded (distance units) :l

qfactor = max strain at which bias potential goes to 0.0 (unitless) :l

Vmax = estimated height of bias potential (energy units) :l

Tequil = equilibration temperature (temperature units) :l

Dcut = min distance between boosted bonds (distance units) :l

alpha = boostostat relaxation time (time units) :l

boost = desired time boost factor (unitless) :l

zero or more keyword/value pairs may be appended :l

keyword = {histo} or {lost} or {check/bias} or {check/coeff}

  {histo} values = Nevery Nbin delta Nout

    Nevery = histogram bond bias coefficients every this many timesteps

    Nbin = # of histogram bins

    delta = width of each histogram bin

    Nout = output histogram counts every this many timesteps

  {lostbond} value = error/warn/ignore

  {check/bias} values = Nevery error/warn/ignore

  {check/coeff} values = Nevery error/warn/ignore :pre

:ule

[Examples:]

fix 1 all hyper/local 1.0 0.3 0.8 300.0 :pre

[Description:]

This fix is meant to be used with the "hyper"_hyper.html command to

perform a bond-boost hyperdynamics simulation.  The role of this fix

is a select a multiple pairs of atoms within the system at each

timestep to add a local bias potential to, which will alter their

dynamics.  This is in contrast to the "fix

hyper/global"_fix_hyper_global.html command, which adds a global bias

potential to a single pair of atoms at each timestep.

For a system that undergoes rare transition events, where one or more

atoms move across an energy barrier to a new potential energy basin,

the effect of the bias potential is to induce more rapid transitions.

This can lead to a dramatic speed-up in the rate at which events

occurs, without altering their relative frequencies, thus leading to

an overall dramatic speed-up in the effective wall-clock time of the

simulation.

Cite various papers.

The current strain of a bond IJ is defined as

Eij = (Rij - R0ij) / R0ij

Emax = is the max of the absolute value of Eij for all IJ bonds.

dVij = Vmax * (1 - (Eij/q)^2) for abs(Eij) < q

     = 0  otherwise

Delta Vbias = minimum of dVij for all IJ bonds

The boost factor B = exp(beta * Delta Vbias)

for a single timestep.

Thus the accumulated hypertime is simply

t_hyper = Sum (i = 1 to Nsteps) Bi * dt

NOTE: Add eqs for boostostat and boost coeff.

Explain how many bonds are boosted simultaneously

and how to choose boost factor and initial Vmax.

The {cutbond} argument is the cutoff distance for defining bonds

between pairs of nearby atoms.  A pair of atoms in their equilibrium,

minimum-energy config, which are a distance Rij < cutbond, are

defined as a bonded pair.

The {qfactor} argument is the limiting strain at which

the Vbias (the bias potential) goes to 0.0.

If qfactor is too big, then transitions are affected b/c

the bias energy is non-zero at the transitions.  If it is

too small than not must boost is achieved for a large system

with many bonds (some bonds Eij always exceeds qfactor).

The {Vmax} argument is the initial prefactor on the bias potential.

Should be chosen as estimate of final.  Will be adjusted by

boost cooeficient

The {Tequil} argument is part of the beta term in the

exponential factor that determines how much boost is

achieved as a function of the bias potential.

The {Dcut} argument is the distance required between two bonds for

them to be selected as both being boosted.  The distance is between

the center points of each bond.  Actually between any pair of atoms in

either bond.

The {alpha} argument is a pre-factor on the update equation

for each atom's boostostat:

NOTE: give equation above

Note that the units for {alpha} are in time units, similar

to other thermostat or barostat damping parameters

The {boost} argument is the desired boost factor (e.g. 100x)

that all the atoms in the system will experience.  

NOTE: explain how to choose good value for this.  If this parameter is

chosen to be too large, then the bias potential applied to pairs of

bonded atoms may become unphysically large, leading to bad dynamics.

If chosen too small, the hyperdynamics run may be inefficient in the

sense that events take a long time to occur.

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart

files"_restart.html.

The "fix_modify"_fix_modify.html {energy} option is supported by this

fix to add the energy of the bias potential to the the system's

potential energy as part of "thermodynamic output"_thermo_style.html.

This fix computes a global scalar and global vector of length 23,

which can be accessed by various "output

commands"_Section_howto.html#howto_15.  The scalar is the magnitude of

the bias potential (energy units) applied on the current timestep,

summed over all biased bonds.  The vector stores the following

quantities:

1 = # of boosted bonds on this step

2 = max strain of any bond on this step (unitless)

3 = average bias potential for all bonds on this step (energy units)

4 = average bonds/atom on this step

5 = average neighbor bonds/bond on this step :ul

6 = fraction of steps and bonds with no bias during this run

7 = max drift distance of any atom during this run (distance units)

8 = max bond length during this run (distance units)

9 = average # of boosted bonds/step during this run

10 = average bias potential for all bonds during this run (energy units)

11 = max bias potential for any bond during this run (energy units)

12 = min bias potential for any bond during this run (energy units)

13 = max distance from my box of any ghost atom with maxstrain < qfactor during th

is run (distance units)

14 = max distance outside my box of any ghost atom with any maxstrain during this run (distance units)

15 = count of ghost neighbor atoms not found on reneighbor steps during this run

16 = count of lost bond partners during this run

17 = average bias coeff for lost bond partners during this run

18 = count of bias overlaps found during this run

19 = count of non-matching bias coefficients found during this run :ul

20 = cummulative hyper time since fix created (time units)

21 = cummulative count of event timesteps since fix created

22 = cummulative count of atoms in events since fix created

23 = cummulative # of new bonds since fix created :ul

The first quantities (1-5) are for the current timestep.  The

quantities 6-19 are for the current hyper run.  They are reset each

time a new hyper run is performed.  The quantities 20-23 are

cummulative across multiple hyper runs,  They are only set to initial

values once, when this fix is defined in the input script.

For value 6, the numerator is a count of all biased bonds on every

timestep whose bias value = 0.0.  The denominator is the count of all

biased bonds on all timesteps.

For values 13 and 14, the maxstrain of a ghost atom is the maxstrain

of any bond it is part of, and it is checked for ghost atoms within

the bond neighbor cutoff.

The scalar and vector values calculated by this fix are all

"intensive".

No parameter of this fix can be used with the {start/stop} keywords of

the "run"_run.html command.  This fix is not invoked during "energy

minimization"_minimize.html.

[Restrictions:]

This fix is part of the REPLICA package.  It is only enabled if LAMMPS

was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

[Related commands:]

"hyper"_hyper.html, "fix hyper/global"_fix_hyper_global.html

[Default:] None

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

hyper command :h3

[Syntax:]

hyper N Nevent fixID computeID keyword values ... :pre

N = # of timesteps to run :ulb,l

Nevent = check for events every this many steps :l

fixID = ID of a fix that applies a global or local bias potential :l

computeID = ID of a compute that identifies when an event has occurred :l

zero or more keyword/value pairs may be appended :l

keyword = {min} or {time} :l

  {min} values = etol ftol maxiter maxeval

    etol = stopping tolerance for energy, used in quenching

    ftol = stopping tolerance for force, used in quenching

    maxiter = max iterations of minimize, used in quenching

    maxeval = max number of force/energy evaluations, used in quenching

  {time} value = {steps} or {clock}

    {steps} = simulation runs for N timesteps (default)

    {clock} = simulation runs until hyper time exceeds N timesteps :pre

:ule

[Examples:]

hyper 5000 100 global event :pre

[Description:]

Run a bond-boost hyperdynamics (HD) simulation where time is

accelerated by application of a bias potential to a one or more pairs

of atoms in the system.  This command can be used to run both global

and local hyperdyamics.  In global HD a single bond (nearby pair of

atoms) within the system is biased on a given timestep.  In local HD

multiple bonds (separated by a sufficient distance) can be biased

simultaneously at each timestep.

Make next paragraph more HD-specific.

Both global and local HD are described in "this paper"_#Voter2013 by

Art Voter and collaborators.  They are methods for performing

accelerated dynamics that is suitable for infrequent-event systems

that obey first-order kinetics.  A good overview of accelerated

dynamics methods for such systems in given in "this review

paper"_#Voter2002prd from the same group.  To quote from the paper:

"The dynamical evolution is characterized by vibrational excursions

within a potential basin, punctuated by occasional transitions between

basins."  The transition probability is characterized by p(t) =

k*exp(-kt) where k is the rate constant.  Running multiple replicas

gives an effective enhancement in the timescale spanned by the

multiple simulations, while waiting for an event to occur.

How different than PRD.

An HD run has several stages, which are repeated each time an "event"

occurs, as defined below.  The logic for a HD run is as follows:

quench

reset list of bonds :pre

while (time remains):

  run dynamics for Nevery steps

  quench

  check for an event

  if event occurred: reset list of bonds

  restore pre-quench state :pre

Explain each of the steps above.  Explain what list of bonds is and

how event is detected.

Explain the specified fix and compute.

Statistics about the number of events, the number of bonds that a bias

potential is applied to, the accumulated hyper time, etc are stored by

the fix and can be output with thermodynamic output.

:line

[Restrictions:]

This command can only be used if LAMMPS was built with the REPLICA

package.  See the "Making LAMMPS"_Section_start.html#start_3 section

for more info on packages.

NOTE: is this true?

This command cannot be used when any fixes are defined that keep track

of elapsed time to perform time-dependent operations.  Examples

include the "ave" fixes such as "fix ave/chunk"_fix_ave_chunk.html.

Also "fix dt/reset"_fix_dt_reset.html and "fix

deposit"_fix_deposit.html.

[Related commands:]

"fix hyper/global"_fix_hyper_global.html, "fix

hyper/local"_fix_hyper_local.html, "compute

event/displace"_compute_event_displace.html

[Default:]

The option defaults are min = 0.1 0.1 40 50 and time = steps.

:line

:link(Voter2013)

[(Voter2013)] S. Y. Kim, D. Perez, A. F. Voter, J Chem Phys, 139,

144110 (2013).

:link(Voter2002prd)

[(Voter2002)] Voter, Montalenti, Germann, Annual Review of Materials

Research 32, 321 (2002).

/* ----------------------------------------------------------------------

   LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator

   http://lammps.sandia.gov, Sandia National Laboratories

   Steve Plimpton, sjplimp@sandia.gov

   Copyright (2003) Sandia Corporation.  Under the terms of Contract

   DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains

   certain rights in this software.  This software is distributed under

   the GNU General Public License.

   See the README file in the top-level LAMMPS directory.

------------------------------------------------------------------------- */

#include <stdlib.h>

#include <string.h>

#include "fix_event_hyper.h"

#include "atom.h"

#include "update.h"

#include "domain.h"

#include "neighbor.h"

#include "comm.h"

#include "universe.h"

#include "memory.h"

#include "error.h"

using namespace LAMMPS_NS;

using namespace FixConst;

/* ---------------------------------------------------------------------- */

FixEventHyper::FixEventHyper(LAMMPS *lmp, int narg, char **arg) :

  FixEvent(lmp, narg, arg)

{

  if (narg != 3) error->all(FLERR,"Illegal fix event command");

  restart_global = 1;

  event_number = 0;

  event_timestep = update->ntimestep;

  clock = 0;

}

/* ----------------------------------------------------------------------

   save current atom coords as an event (via call to base class)

   called when an event occurs in some replica

   set event_timestep = when event occurred in a particular replica

   update clock = elapsed time since last event, across all replicas

------------------------------------------------------------------------- */

void FixEventHyper::store_event_hyper(bigint ntimestep, int delta_clock)

{

  store_event();

  event_timestep = ntimestep;

  clock += delta_clock;

  event_number++;

}

/* ----------------------------------------------------------------------

   pack entire state of Fix into one write

------------------------------------------------------------------------- */

void FixEventHyper::write_restart(FILE *fp)

{

  int n = 0;

  double list[6];

  list[n++] = event_number;

  list[n++] = event_timestep;

  list[n++] = clock;

  list[n++] = replica_number;

  list[n++] = correlated_event;

  list[n++] = ncoincident;

  if (comm->me == 0) {

    int size = n * sizeof(double);

    fwrite(&size,sizeof(int),1,fp);

    fwrite(list,sizeof(double),n,fp);

  }

}

/* ----------------------------------------------------------------------

   use state info from restart file to restart the Fix

------------------------------------------------------------------------- */

void FixEventHyper::restart(char *buf)

{

  int n = 0;

  double *list = (double *) buf;

  event_number = static_cast<int> (list[n++]);

  event_timestep = static_cast<bigint> (list[n++]);

  clock = static_cast<bigint> (list[n++]);

  replica_number = static_cast<int> (list[n++]);

  correlated_event = static_cast<int> (list[n++]);

  ncoincident = static_cast<int> (list[n++]);

}

/* -*- c++ -*- ----------------------------------------------------------

   LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator

   http://lammps.sandia.gov, Sandia National Laboratories

   Steve Plimpton, sjplimp@sandia.gov

   Copyright (2003) Sandia Corporation.  Under the terms of Contract

   DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains

   certain rights in this software.  This software is distributed under

   the GNU General Public License.

   See the README file in the top-level LAMMPS directory.

------------------------------------------------------------------------- */

#ifdef FIX_CLASS

FixStyle(EVENT/HYPER,FixEventHyper)

#else

#ifndef LMP_FIX_EVENT_HYPER_H

#define LMP_FIX_EVENT_HYPER_H

#include "fix_event.h"

namespace LAMMPS_NS {

class FixEventHyper : public FixEvent {

 public:

  int event_number;      // event counter

  bigint event_timestep; // timestep of last event on any replica

  bigint clock;          // total elapsed timesteps across all replicas

  int replica_number;    // replica where last event occured

  int correlated_event;  // 1 if last event was correlated, 0 otherwise

  int ncoincident;       // # of simultaneous events on different replicas

  FixEventHyper(class LAMMPS *, int, char **);

  ~FixEventHyper() {}

  void write_restart(FILE *);

  void restart(char *);

  // methods specific to FixEventHyper, invoked by hyper

  void store_event_hyper(bigint, int);

};

}

#endif

#endif

/* ERROR/WARNING messages:

E: Illegal ... command

Self-explanatory.  Check the input script syntax and compare to the

documentation for the command.  You can use -echo screen as a

command-line option when running LAMMPS to see the offending line.

*/