Kinetics#

Directory: libfly/kinetic

The kinetic folder contains a data-structures and algorithms for choosing mechanisms according to the KMC and Super-KMC algorithms. Everything is contained within the namespace fly::kinetic.

Basins#

File: libfly/kinetic/basin.hpp

Representation of a state in a Markov chain and utilities for discretising states.

auto fly::kinetic::hash(Eigen::Index num_atoms, fly::env::Catalogue const &cat) -> std::size_t#

Compute a hash encoding the ID’s of the local environments of each atom loaded into the catalogue.

Parameters:

  • num_atoms – Number of atoms loaded into the catalogue.

  • cat – A catalogue in the ready state.

class Basin#

Represents a basin of the potential energy of the entire system.

Stores a reference image of the system and a list of all mechanisms accessible from the basin. Implements standard KMC algorithm on this list. Stored Mechanisms are pointers into a Catalogue.

Public Functions

Basin(Options const &opt, system::SoA<Position const&> state, fly::env::Catalogue const &cat)#

Construct a new Basin.

Parameters:

  • opt – The options for this Basin.

  • state – The state of the system.

  • cat – A catalogue in the ready state for this system.

auto kmc_choice(Xoshiro &psudo_rng) const -> Choice#

Choose a mechanisms in the basin using standard n-fold-way kmc algorithm.

auto most_likely(double tol) -> std::vector<Choice>#

Fetch every mechanisms that is accessible that with a probability greater than tol.

inline auto rate_sum() const noexcept -> double#

Fetch the sum of the rates of all mechanisms from this basin.

inline auto state() const noexcept -> system::SoA<Position> const&#

Fetch the state (positions of the atoms in the basin).

class Choice#

A result type to indicate a randomly selected mechanism in a basin/superbasin.

Public Members

int atom#

The index of the atom chosen.

double dt#

The time elapsed if this mechanisms is carried out.

env::Mechanism const &mech#

A reference to the mechanism stored in the catalogue.

struct Options#

Configure the Basin class.

Public Members

bool debug = false#

Controls printing of debugging data.

double max_barrier = std::numeric_limits<double>::max()#

Maximum energy barrier, higher energy mechanisms are ignored.

double temp = 300#

Temperature of simulation in kelvin.

Superbasins#

File: libfly/kinetic/superbasin.hpp

Representation of a collection of basins.

class SuperBasin#

Manages a superbasin: a collection of low-barrier-linked basins.

This implements a variation of bac-MRM, the basin auto-constructing mean rate method, to analytically accelerate KMC. This solves the “low-barrier problem” for small numbers (< a few hundred) of flickering states.

Public Functions

inline SuperBasin(Options const &opt, Basin &&basin)#

Construct a new SuperBasin object containing a single basin.

auto connect_from(std::size_t basin, int atom, env::Mechanism const &m) -> void#

Connect mechanism mech from basin basin to the currently occupied basin.

This marks mech as an internal, transient mechanism and fills in the internal transition probability matrix.

Parameters:

  • basin – The index of the basin which the mechanism starts from.

  • atom – The index of the atom which the mechanism is centred on.

  • m – The mechanism that connect basin to the currently occupied basin.

inline auto expand_occupy(Basin &&basin) -> std::size_t#

Expand the SuperBasin by adding basin to it and setting basin as the currently occupied basin.

Parameters:

basin – The basin to add to the SuperBasin.

Returns:

Returns the previously occupied basin’s index.

auto find_occupy(std::size_t hash, system::SoA<Position const&> in, double tol) -> std::optional<std::size_t>#

Find and occupy a basin in the SuperBasin whose state matches in.

Searches through the basins in the superbasin, if one is found that matches (all active atoms within L2 tolerance tol) make it the occupied basin.

Parameters:

  • hash – Of in as computed by fly::kinetic::hash().

  • in – The input state.

  • tol – The L2 tolerance between in and a basin state for them to be considered “the same”.

Returns:

Returns the previously occupied basin’s index or std::nullopt if no match is found.

auto kmc_choice(Xoshiro &pseudo_rng) const -> Choice#

Choose a mechanism using the modified mean-rate-method.

This will pick a non-transient mechanism, e.g. a mechanisms that “escapes” the superbasin (although it may be an internal mechanisms that has not been traversed yet).

Note

The mechanism may start from a basin that the system is not currently in.

Parameters:

pseudo_rng – The pseudo random number generator to use.

inline auto size() const -> std::size_t#

Get the number of basins in the SuperBasin.

inline auto state(std::size_t basin) const -> system::SoA<Position> const&#

Get the state of the Basin indexed by basin.

class Choice#

A result type to indicate a randomly selected mechanism in a basin/superbasin.

Public Members

int atom#

The index of the atom chosen.

std::size_t basin#

The index of the basin that mech starts from.

bool basin_changed#

True if occupied basin changed during selection.

double dt#

The time elapsed if this mechanisms is carried out.

env::Mechanism const &mech#

A reference to the mechanism stored in the catalogue.

struct Options#

Configure the SuperBasin class.

Public Members

bool debug = false#

Controls printing of debugging data.

Super(super)basins#

File: libfly/kinetic/cache.hpp

Representation of a collection of basins.

class SuperCache#

Manages a collection of superbasins.

A SuperCache dynamically manages a collection of superbasin to remove the overhead of exploring/building a superbasin. The is particularly useful when superbasins are frequently re-entered upon exit.

Public Functions

inline SuperCache(Options const &opt, SuperBasin &&sb)#

Construct a new SuperCache object initialised with a single superbasin.

Parameters:

  • opt – The options for this SuperCache.

  • sb – The initial superbasin.

void connect_from(std::size_t basin, int atom, env::Mechanism const &mech, system::SoA<Position const&> cell, env::Catalogue const &cat)#

Manages the internal superbasins.

Identifies which (if any) basin cell matches, makes that basins’s superbasin the active superbasin and then connects the mechanism mech with fly::kinetic::SuperBasin::connect_from() if this was a low barrier mechanism.

Parameters:

  • basin – The index of the basin which the mechanism starts from in the active superbasin.

  • atom – The index of the atom which the mechanism is centred on.

  • mech – The mechanism that was chosen.

  • cell – The system after reconstructing mech onto the previous state.

  • cat – The catalogue in the ready state (i.e. called cat.rebuild() with argument cell).

inline auto kmc_choice(Xoshiro &psudo_rng) const -> SuperBasin::Choice#

Forward the call to the active superbasin’s fly::kinetic::SuperBasin::kmc_choice().

inline void reset(SuperBasin &&sb)#

Reset the cache to contain only a single superbasin sb.

inline std::size_t size() const noexcept#

Get the number of superbasins in the SuperCache.

inline auto const &state(std::size_t basin) const#

Get the state of the Basin indexed by basin in the active basin.

struct Options#

Configure the SuperCache class.

Public Members

double barrier_tol = 0.3#

Tolerance for mechanisms to be considered high-barrier.

std::size_t cache_size = 128#

Max number of SuperBasins in the cache.

bool debug = false#

Controls debug printing.

bool debug_pause = false#

If true waits for input when barrier_tol is adjusted.

bool dynamic_tol = true#

If true barrier_tol is dynamically adjusted.

std::size_t max_superbasin_size = 256#

Maximum number basins in SB before tol_shrink.

Basin::Options opt_basin = {}#

Basin::Options options.

SuperBasin::Options opt_sb = {}#

SuperBasin::Options options.

double state_tol = 0.1#

L2 norm between atoms for basins to be considered the same.

double tol_grow = 1.5#

Multiplier by which barrier_tol increases by.

double tol_shrink = 0.5#

Multiplier by which barrier_tol decreases by.

Super kinetic Monte Carlo#

File: libfly/kinetic/skmc.hpp

Objects that coordinate and run an OLKMC simulation.

class SKMC#

Coordinate the running of an OLKMC simulation.

Public Functions

inline SKMC(Options const &opt, system::Box const &box, system::TypeMap<Mass> const &map, minimise::LBFGS const &min, potential::Generic const &pot, saddle::Dimer const &dimer)#

Construct a new SKMC object.

Parameters:

  • opt – The configuration options.

  • box – The simulation box that the simulation is contained within.

  • map – The type map for the simulation.

  • min – The minimiser, used for minimisation during saddle-point searches and for relaxing the cell.

  • pot – Potential energy function.

  • dimer – For saddle-point searches.

template<typename Map, typename ...T, typename F>
auto skmc(system::Supercell<Map, T...> const &cell, int num_threads, F const &f) -> void#

Run an OLKMC simulation starting with ‘’cell’’.

Example:

#include "libfly/kinetic/skmc.hpp"

using namespace fly;

void example_skmc(system::Supercell<system::TypeMap<Mass>, Position, Frozen> cell,
                  potential::Generic potential_func) {
  // Construct am SKMC object with some non-default options.
  kinetic::SKMC runner = {
      {
          .debug = true,
          .opt_cache = {
              .debug = true,
              .opt_basin = {
                  .debug = true,
                  .temp = 500, ///< Set the temperature of the simulation
              },
              .opt_sb = {
                  .debug = true,
              },
          },
          .opt_master = {},
      },
      cell.box(),
      cell.map(),
      { {}, cell.box() },
      potential_func,
      { {}, {}, cell.box() },
  };

  // Run an OLKMC simulation using the runner object.
  runner.skmc(cell,
              omp_get_max_threads(),
              [&](double time,                         ///< Total time just after system at post.
                  system::SoA<Position const &> pre,   ///< State just before mech applied.
                  double E0,                           ///< Energy of the system in state pre.
                  int atom,                            ///< Index of central atom of mechanism.
                  env::Mechanism const &mech,          ///< Chosen mechanism.
                  system::SoA<Position const &> post,  ///< Final state of system after this iteration/mech.
                  double Ef                            ///< Energy of system in state post.
              ) {
                // Called every step of the simulation.
                // Can output pre/post do processing etc.
                // Return true to stop and false to continue simulation.
                return false;
              });
}

Parameters:

  • cell – The initial state of the simulation.

  • num_threads – The number of (openMP) threads to use.

  • f – The callback which determines the stopping criterion, see example above/below.

struct Options#

Configure the SKMC class.

Public Members

bool debug = false#

Configure debug printing.

std::string fread = "cat.bin"#

The name of the file to read the catalogue from.

std::string fwrite = fread#

The name of the file to write the catalogue to.

SuperCache::Options opt_cache = {}#

Options for the superbasin.

saddle::Master::Options opt_master = {}#

Options for the saddle-point finder.