Merge pull request #1836 from lammps/hyper-upgrade

* alpha = boostostat relaxation time (time units)

* Btarget = desired time boost factor (unitless)

* zero or more keyword/value pairs may be appended

* keyword = *check/ghost* or *check/bias*

* keyword = *bound* or *reset* or *check/ghost* or *check/bias*

  .. parsed-literal::

       *bound* value = Bfrac

         Bfrac =  -1 or a value >= 0.0

       *reset* value = Rfreq

         Rfreq = -1 or 0 or timestep value > 0

       *check/ghost* values = none

       *check/bias* values = Nevery error/warn/ignore

.. parsed-literal::

   fix 1 all hyper/local 1.0 0.3 0.8 300.0

   fix 1 all hyper/local 1.0 0.3 0.8 300.0 bound 0.1 reset 0

Description

"""""""""""

   Cij are initialized to 1.0 and the boostostatting procedure typically

   operates slowly enough that there can be a time period of bad dynamics

   if *Vmax* is set too large.  A better strategy is to set *Vmax* to the

   smallest barrier height for an event (the same as for GHD), so that

   the Cij remain near unity.

   slightly smaller than the lowest barrier height for an event (the same

   as for GHD), so that the Cij remain near unity.

The *Tequil* argument is the temperature at which the system is

simulated; see the comment above about the :doc:`fix langevin <fix_langevin>` thermostatting.  It is also part of the

Here is additional information on the optional keywords for this fix.

The *bound* keyword turns on min/max bounds for bias coefficients Cij

for all bonds.  Cij is a prefactor for each bond on the bias potential

of maximum strength Vmax.  Depending on the choice of *alpha* and

*Btarget* and *Vmax*\ , the boostostatting can cause individual Cij

values to fluctuate.  If the fluctuations are too large Cij\*Vmax can

exceed low barrier heights and induce bad event dynamics.  Bounding

the Cij values is a way to prevent this.  If *Bfrac* is set to -1 or

any negative value (the default) then no bounds are enforced on Cij

values (except they must always be >= 0.0).  A *Bfrac* setting >= 0.0

sets a lower bound of 1.0 - Bfrac and upper bound of 1.0 + Bfrac on

each Cij value.  Note that all Cij values are initialized to 1.0 when

a bond is created for the first time.  Thus *Bfrac* limits the bias

potential height to *Vmax* +/- *Bfrac*\ \*\ *Vmax*\ .

The *reset* keyword allow *Vmax* to be adjusted dynamically depending

on the average value of all Cij prefactors.  This can be useful if you

are unsure what value of *Vmax* will match the *Btarget* boost for the

system.  The Cij values will then adjust in aggregate (up or down) so

that Cij\*Vmax produces a boost of *Btarget*\ , but this may conflict

with the *bound* keyword settings.  By using *bound* and *reset*

together, *Vmax* itself can be reset, and desired bounds still applied

to the Cij values.

A setting for *Rfreq* of -1 (the default) means *Vmax* never changes.

A setting of 0 means *Vmax* is adjusted every time an event occurs and

bond pairs are recalculated.  A setting of N > 0 timesteps means

*Vmax* is adjusted on the first time an event occurs on a timestep >=

N steps after the previous adjustment.  The adjustment to *Vmax* is

computed as follows.  The current average of all Cij\*Vmax values is

computed and the *Vmax* is reset to that value.  All Cij values are

changed to new prefactors such the new Cij\*Vmax is the same as it was

previously.  If the *bound* keyword was used, those bounds are

enforced on the new Cij values.  Henceforth, new bonds are assigned a

Cij = 1.0, which means their bias potential magnitude is the new

*Vmax*\ .

The *check/ghost* keyword turns on extra computation each timestep to

compute statistics about ghost atoms used to determine which bonds to

bias.  The output of these stats are the vector values 14 and 15,

No information about this fix is written to :doc:`binary restart files <restart>`.

The :doc:`fix\_modify <fix_modify>` *energy* option is supported by this

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

potential energy as part of :doc:`thermodynamic output <thermo_style>`.

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

energy as part of :doc:`thermodynamic output <thermo_style>`.

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

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

which can be accessed by various :doc:`output commands <Howto_output>`.

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 biased bonds on this step

* 2 = max strain Eij of any bond on this step (absolute value, unitless)

* 3 = average bias coeff for all bonds on this step (unitless)

* 4 = average # of bonds/atom on this step

* 5 = average neighbor bonds/bond on this step within *Dcut*

* 6 = max bond length during this run (distance units)

* 7 = average # of biased bonds/step during this run

* 8 = fraction of biased bonds with no bias during this run

* 9 = fraction of biased bonds with negative strain during this run

* 10 = average bias coeff for all bonds during this run (unitless)

* 11 = min bias coeff for any bond during this run (unitless)

* 12 = max bias coeff for any bond during this run (unitless)

* 13 = max drift distance of any bond atom during this run (distance units)

* 14 = max distance from proc subbox of any ghost atom with maxstrain < qfactor during this run (distance units)

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

* 16 = count of ghost atoms that could not be found on reneighbor steps during this run

* 17 = count of bias overlaps (< Dcut) found during this run

* 18 = cumulative hyper time since fix created (time units)

* 19 = cumulative count of event timesteps since fix created

* 20 = cumulative count of atoms in events since fix created

* 21 = cumulative # of new bonds formed since fix created

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

6-17 are for the current hyper run.  They are reset each time a new

hyper run is performed.  Quantities 18-21 are cumulative across

* 1 = average boost for all bonds on this step (unitless)

* 2 = # of biased bonds on this step

* 3 = max strain Eij of any bond on this step (absolute value, unitless)

* 4 = value of Vmax on this step (energy units)

* 5 = average bias coeff for all bonds on this step (unitless)

* 6 = min bias coeff for all bonds on this step (unitless)

* 7 = max bias coeff for all bonds on this step (unitless)

* 8 = average # of bonds/atom on this step

* 9 = average neighbor bonds/bond on this step within *Dcut*

* 10 = average boost for all bonds during this run (unitless)

* 11 = average # of biased bonds/step during this run

* 12 = fraction of biased bonds with no bias during this run

* 13 = fraction of biased bonds with negative strain during this run

* 14 = max bond length during this run (distance units)

* 15 = average bias coeff for all bonds during this run (unitless)

* 16 = min bias coeff for any bond during this run (unitless)

* 17 = max bias coeff for any bond during this run (unitless)

* 18 = max drift distance of any bond atom during this run (distance units)

* 19 = max distance from proc subbox of any ghost atom with maxstrain < qfactor during this run (distance units)

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

* 21 = count of ghost atoms that could not be found on reneighbor steps during this run

* 22 = count of bias overlaps (< Dcut) found during this run

* 23 = cumulative hyper time since fix created (time units)

* 24 = cumulative count of event timesteps since fix created

* 25 = cumulative count of atoms in events since fix created

* 26 = cumulative # of new bonds formed since fix created

27 = average boost for biased bonds on this step (unitless)

28 = # of bonds with absolute strain >= q on this step

The first quantities 1-9 are for the current timestep.  Quantities

10-22 are for the current hyper run.  They are reset each time a new

hyper run is performed.  Quantities 23-26 are cumulative across

multiple runs (since the point in the input script the fix was

defined).

For value 8, the numerator is a count of all biased bonds on each

For value 10, each bond instantaneous boost factor is given by the

equation for Bij above.  The total system boost (average across all

bonds) fluctuates, but should average to a value close to the

specified Btarget.

For value 12, the numerator is a count of all biased bonds on each

timestep whose bias energy = 0.0 due to Eij >= *qfactor*\ .  The

denominator is the count of all biased bonds on all timesteps.

For value 9, the numerator is a count of all biased bonds on each

For value 13, the numerator is a count of all biased bonds on each

timestep with negative strain.  The denominator is the count of all

biased bonds on all timesteps.

Values 13-17 are mostly useful for debugging and diagnostic purposes.

Values 18-22 are mostly useful for debugging and diagnostic purposes.

For value 13, drift is the distance an atom moves between two quenched

For value 18, drift is the distance an atom moves between two quenched

states when the second quench determines an event has occurred.  Atoms

involved in an event will typically move the greatest distance since

others typically remain near their original quenched position.

For values 14-16, neighbor atoms in the full neighbor list with cutoff

For values 19-21, neighbor atoms in the full neighbor list with cutoff

*Dcut* may be ghost atoms outside a processor's sub-box.  Before the

next event occurs they may move further than *Dcut* away from the

sub-box boundary.  Value 14 is the furthest (from the sub-box) any

sub-box boundary.  Value 19 is the furthest (from the sub-box) any

ghost atom in the neighbor list with maxstrain < *qfactor* was

accessed during the run.  Value 15 is the same except that the ghost

accessed during the run.  Value 20 is the same except that the ghost

atom's maxstrain may be >= *qfactor*\ , which may mean it is about to

participate in an event.  Value 16 is a count of how many ghost atoms

participate in an event.  Value 21 is a count of how many ghost atoms

could not be found on reneighbor steps, presumably because they moved

too far away due to their participation in an event (which will likely

be detected at the next quench).

Typical values for 14 and 15 should be slightly larger than *Dcut*\ ,

Typical values for 19 and 20 should be slightly larger than *Dcut*\ ,

which accounts for ghost atoms initially at a *Dcut* distance moving

thermally before the next event takes place.

Note that for values 14 and 15 to be computed, the optional keyword

Note that for values 19 and 20 to be computed, the optional keyword

*check/ghost* must be specified.  Otherwise these values will be zero.

This is because computing them incurs overhead, so the values are only

computed if requested.

Value 16 should be zero or small.  As explained above a small count

Value 21 should be zero or small.  As explained above a small count

likely means some ghost atoms were participating in their own events

and moved a longer distance.  If the value is large, it likely means

the communication cutoff for ghosts is too close to *Dcut* leading to

above, the :doc:`comm\_modify cutoff <comm_modify>` command can be used

to set a longer cutoff.

For value 17, no two bonds should be biased if they are within a

For value 22, no two bonds should be biased if they are within a

*Dcut* distance of each other.  This value should be zero, indicating

that no pair of biased bonds are closer than *Dcut* from each other.

Note that for values 17 to be computed, the optional keyword

Note that for value 22 to be computed, the optional keyword

*check/bias* must be specified and it determines how often this check

is performed.  This is because performing the check incurs overhead,

so if only computed as often as requested.

in bonds which found other atoms in bonds too close, so it is almost

always an over-count of the number of too-close bonds.

Value 18 is simply the specified *boost* factor times the number of

Value 23 is simply the specified *boost* factor times the number of

timesteps times the timestep size.

For value 19, events are checked for by the :doc:`hyper <hyper>` command

For value 24, events are checked for by the :doc:`hyper <hyper>` command

once every *Nevent* timesteps.  This value is the count of those

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

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

same *Nevent* time window.

For value 20, each time the :doc:`hyper <hyper>` command checks for an

For value 25, each time the :doc:`hyper <hyper>` command checks for an

event, it invokes a compute to flag zero or more atoms as

participating in one or more events.  E.g. atoms that have displaced

more than some distance from the previous quench state.  Value 20 is

more than some distance from the previous quench state.  Value 25 is

the cumulative count of the number of atoms participating in any of

the events that were found.

Value 21 tallies the number of new bonds created by the bond reset

Value 26 tallies the number of new bonds created by the bond reset

operation.  Bonds between a specific I,J pair of atoms may persist for

the entire hyperdynamics simulation if neither I or J are involved in

an event.

Value 27 computes the average boost for biased bonds only on this step.

Value 28 is the count of bonds with an absolute value of strain >= q

on this step.

The scalar and vector values calculated by this fix are all

"intensive".

Default

"""""""

The check/ghost and check/bias keywords are not enabled by default.

The default settings for optimal keywords are bounds = -1 and reset =

-1.  The check/ghost and check/bias keywords are not enabled by

default.

----------

Bessarab

Beutler

Bext

Bfrac

bgq

Bh

Biersack

create_atoms 1 single 27.5 9.5 4

create_atoms 1 single 16 9 4

create_atoms 1 single 10 12 4

create_atoms 1 single 31 44 4

create_atoms 1 single 13 17 4

create_atoms 1 single 8.5 28.5 4

create_atoms 1 single 23 26 4

create_atoms 1 single 38 27 4

create_atoms 1 single 37.5 4.5 4

create_atoms 1 single 41.5 47.5 4

create_atoms 1 single 20.5 37.5 4

create_atoms 1 single 5 8 4

create_atoms 1 single 2.5 16.5 4

create_atoms 1 single 38.5 45.5 4

create_atoms 1 single 9 0 4

create_atoms 1 single 39 32 4

create_atoms 1 single 45.5 11.5 4

create_atoms 1 single 40 0 4

create_atoms 1 single 44.5 2.5 4

create_atoms 1 single 4.5 44.5 4

create_atoms 1 single 24.5 13.5 4

create_atoms 1 single 47.5 23.5 4

create_atoms 1 single 1 20 4

create_atoms 1 single 38.5 31.5 4

create_atoms 1 single 12.5 12.5 4

create_atoms 1 single 2 27 4

create_atoms 1 single 21 5 4

create_atoms 1 single 47 12 4

create_atoms 1 single 32.5 46.5 4

create_atoms 1 single 9.5 40.5 4

create_atoms 1 single 8.5 2.5 4

create_atoms 1 single 41.5 22.5 4

create_atoms 1 single 29 11 4

create_atoms 1 single 3.5 3.5 4

create_atoms 1 single 5 21 4

create_atoms 1 single 46.5 31.5 4

create_atoms 1 single 35 46 4

create_atoms 1 single 40.5 41.5 4

create_atoms 1 single 10 22 4

create_atoms 1 single 43.5 14.5 4

create_atoms 1 single 42 42 4

create_atoms 1 single 4 26 4

create_atoms 1 single 19 34 4

create_atoms 1 single 33 9 4

create_atoms 1 single 0.5 45.5 4

create_atoms 1 single 30.5 32.5 4

create_atoms 1 single 25.5 5.5 4

create_atoms 1 single 47.5 39.5 4

create_atoms 1 single 15 13 4

create_atoms 1 single 21 21 4

create_atoms 1 single 14 28 4

create_atoms 1 single 9 34 4

create_atoms 1 single 7 38 4

create_atoms 1 single 11 35 4

create_atoms 1 single 20.5 45.5 4

create_atoms 1 single 30.5 31.5 4

create_atoms 1 single 32.5 2.5 4

create_atoms 1 single 21.5 3.5 4

create_atoms 1 single 23 12 4

create_atoms 1 single 4.5 33.5 4

create_atoms 1 single 46 43 4

create_atoms 1 single 42.5 45.5 4

create_atoms 1 single 4.5 10.5 4

create_atoms 1 single 33.5 15.5 4

create_atoms 1 single 24 5 4

create_atoms 1 single 13 16 4

create_atoms 1 single 16.5 23.5 4

create_atoms 1 single 45.5 28.5 4

create_atoms 1 single 44.5 5.5 4

create_atoms 1 single 27.5 46.5 4

create_atoms 1 single 44.5 12.5 4

create_atoms 1 single 12 41 4

create_atoms 1 single 6 4 4

create_atoms 1 single 31.5 10.5 4

create_atoms 1 single 1 44 4

create_atoms 1 single 31 4 4

create_atoms 1 single 21 33 4

create_atoms 1 single 3 33 4

create_atoms 1 single 15 10 4

create_atoms 1 single 28.5 22.5 4

create_atoms 1 single 43 1 4

create_atoms 1 single 3.5 0.5 4

create_atoms 1 single 41 37 4

create_atoms 1 single 18.5 43.5 4

create_atoms 1 single 17 27 4

create_atoms 1 single 3 5 4

create_atoms 1 single 18.5 23.5 4

create_atoms 1 single 31.5 14.5 4

create_atoms 1 single 41 31 4

create_atoms 1 single 22 3 4

create_atoms 1 single 14.5 40.5 4

create_atoms 1 single 9 38 4

create_atoms 1 single 36 42 4

create_atoms 1 single 33 22 4

create_atoms 1 single 15.5 47.5 4

create_atoms 1 single 3 0 4

create_atoms 1 single 25.5 27.5 4

create_atoms 1 single 2.5 28.5 4

create_atoms 1 single 29.5 28.5 4

create_atoms 1 single 44.5 18.5 4

create_atoms 1 single 26 40 4

create_atoms 1 single 41 27 4

create_atoms 1 single 39.5 5.5 4

create_atoms 1 single 3 38 4

create_atoms 1 single 35 29 4

create_atoms 1 single 11 19 4

create_atoms 1 single 18 1 4

create_atoms 1 single 39.5 40.5 4

create_atoms 1 single 46 17 4

create_atoms 1 single 1.5 23.5 4

create_atoms 1 single 28.5 23.5 4

create_atoms 1 single 10 28 4

create_atoms 1 single 19 47 4

create_atoms 1 single 10.5 16.5 4

create_atoms 1 single 38 45 4

create_atoms 1 single 42.5 41.5 4

create_atoms 1 single 47.5 42.5 4

create_atoms 1 single 38 7 4

create_atoms 1 single 10 44 4

create_atoms 1 single 29.5 27.5 4

create_atoms 1 single 45 30 4

create_atoms 1 single 3 9 4

create_atoms 1 single 8.5 35.5 4

create_atoms 1 single 24 44 4

create_atoms 1 single 47 4 4

create_atoms 1 single 7.5 8.5 4

create_atoms 1 single 32.5 41.5 4

create_atoms 1 single 0.5 34.5 4

create_atoms 1 single 11 8 4

create_atoms 1 single 2 40 4

create_atoms 1 single 25 24 4

create_atoms 1 single 47.5 6.5 4

create_atoms 1 single 39.5 28.5 4

create_atoms 1 single 17 21 4

create_atoms 1 single 32 43 4

create_atoms 1 single 16.5 29.5 4

create_atoms 1 single 34 34 4

create_atoms 1 single 11.5 3.5 4

create_atoms 1 single 39 22 4

create_atoms 1 single 24.5 36.5 4

create_atoms 1 single 33 31 4

create_atoms 1 single 35.5 35.5 4

create_atoms 1 single 14.5 34.5 4

create_atoms 1 single 34 28 4

create_atoms 1 single 37 41 4

create_atoms 1 single 33 46 4

create_atoms 1 single 27.5 28.5 4

create_atoms 1 single 40.5 22.5 4

create_atoms 1 single 27.5 1.5 4

create_atoms 1 single 12 2 4

create_atoms 1 single 36 43 4

create_atoms 1 single 28.5 9.5 4

create_atoms 1 single 20.5 25.5 4

create_atoms 1 single 3 3 4

create_atoms 1 single 38 33 4

create_atoms 1 single 3 20 4

create_atoms 1 single 35 11 4

create_atoms 1 single 5 25 4

create_atoms 1 single 36.5 6.5 4

create_atoms 1 single 19.5 24.5 4

create_atoms 1 single 27 41 4

create_atoms 1 single 39.5 11.5 4

create_atoms 1 single 21.5 2.5 4

create_atoms 1 single 46.5 15.5 4

create_atoms 1 single 13 24 4

create_atoms 1 single 11 37 4

create_atoms 1 single 11.5 31.5 4

create_atoms 1 single 47 0 4

create_atoms 1 single 25.5 17.5 4

create_atoms 1 single 32 11 4

create_atoms 1 single 8 17 4

create_atoms 1 single 27.5 12.5 4

create_atoms 1 single 25 7 4

create_atoms 1 single 25.5 37.5 4

create_atoms 1 single 12 15 4

create_atoms 1 single 1 7 4

create_atoms 1 single 18.5 47.5 4

create_atoms 1 single 5 38 4

create_atoms 1 single 42 19 4

create_atoms 1 single 30.5 7.5 4

create_atoms 1 single 42.5 7.5 4

create_atoms 1 single 26.5 18.5 4

create_atoms 1 single 18.5 1.5 4

create_atoms 1 single 41.5 10.5 4

create_atoms 1 single 5 9 4

create_atoms 1 single 4.5 7.5 4

create_atoms 1 single 6 6 4

create_atoms 1 single 5 6 4

create_atoms 1 single 4.5 1.5 4

create_atoms 1 single 6.5 7.5 4

create_atoms 1 single 10.5 5.5 4

create_atoms 1 single 2.5 1.5 4

create_atoms 1 single 3.5 4.5 4

create_atoms 1 single 0 10 4

create_atoms 1 single 11 10 4

create_atoms 1 single 6.5 10.5 4

create_atoms 1 single 3.5 5.5 4

create_atoms 1 single 7.5 10.5 4

create_atoms 1 single 1.5 1.5 4

create_atoms 1 single 1.5 6.5 4

create_atoms 1 single 7 2 4

create_atoms 1 single 4 0 4

create_atoms 1 single 9 0 4

create_atoms 1 single 4 9 4

create_atoms 1 single 10 7 4

create_atoms 1 single 4 4 4

create_atoms 1 single 9.5 2.5 4

create_atoms 1 single 1 5 4

create_atoms 1 single 7 10 4

create_atoms 1 single 0 4 4

create_atoms 1 single 1 10 4

create_atoms 1 single 7.5 6.5 4

create_atoms 1 single 4 10 4

create_atoms 1 single 6.5 3.5 4

create_atoms 1 single 3 6 4

create_atoms 1 single 8.5 4.5 4

create_atoms 1 single 6.5 0.5 4

create_atoms 1 single 1 4 4

create_atoms 1 single 8.5 11.5 4

create_atoms 1 single 3 9 4

create_atoms 1 single 2 3 4

create_atoms 1 single 6.5 8.5 4

create_atoms 1 single 1 0 4

create_atoms 1 single 0.5 10.5 4

create_atoms 1 single 4 11 4

create_atoms 1 single 3 5 4

create_atoms 1 single 0 1 4

create_atoms 1 single 2 11 4

create_atoms 1 single 2 0 4

create_atoms 1 single 7.5 11.5 4

create_atoms 1 single 1 7 4

create_atoms 1 single 3.5 10.5 4

create_atoms 1 single 0 2 4

create_atoms 1 single 8 4 4