Kinetic database

One of the bottlenecks in an aKMC simulation is performing the saddle point searches. The kinetic database of Terrell et al. [KDB_TWCH12] stores each good process as it is registered and uses it to start the next search of a matching state.

In the following figure, the hydrogen of a carboxyl group on an Au(111) surface transfers to the other oxygen (a). In this process, the hydrogen is determined to be the only moving atom, and the two oxygen atoms to be its neighbors. The other atoms are stripped from the system and the resulting configurations are stored in the database (b). If in the future the system passes through a state with a local configuration closely resembling either minimum of (b), the kinetic database will suggest a saddle to converge with a dimer search. The dimer starts with this suggested configuration and mode, and if it is a good suggestion, converges very rapidly to the saddle.

Carboxyl group on an Au(111)

Snapshots of Carboxyl group on an Au(111). (a) Hydrogen of carboxyl transfers to another oxygen. (b) Other atoms are stripped and stored.

Where a process is stored

The reactant, saddle, and product frames go into the run’s readcon-db corpus (readcon.db next to config.ini). The saddle frame carries the process mode in its displacements section, and the line-2 JSON names that section. readcon returns the mode as frame.disp, an N by 3 array in file order. The barrier in eV, the prefactor in s^-1, the same mode components, and the readcon-db frame keys go into amsel.KdbStore. The catalog directory is Paths.kdb (default <main_directory>/kdb/). KdbStore opens that directory. mode_<id>.dat remains the file the client wrote beside the process.

A suggestion refines from the stored saddle. The direction is the stored mode when its absolute cosine with the reactant-to-saddle vector is at least kdb_mac, and that vector otherwise. Each stored process is offered once. The next search is a random displacement when none remain. With kdb_only = true and an empty catalog, no random search is submitted.

use_kdb = true does not import the PyPI kdb package. It needs amsel and readcon-db. A missing amsel logs amsel is not installed and leaves the state unmarked, so a later iteration can try again.

The retired reader imported aselite from the kdb module of the tsase package. This catalog does not import that module.

The three match numbers are kdb_nf, kdb_dc, and kdb_mac:

  • kdb_nf is the neighbor fudge, a fraction. The default is 0.2.

  • kdb_dc is the distance cutoff in angstroms. The default is 0.3. A stored reactant matches the current state when every atom is within kdb_dc * (1 + kdb_nf) angstroms.

  • kdb_mac is the minimum absolute cosine between the stored mode and the reactant-to-saddle displacement. The default is 0.7. At or above that cosine the refine uses the stored mode, flipped when the cosine is negative. Below it, the refine uses the reactant-to-saddle vector.

A query log line contains the kdb_nf value from the ini.

Resetting a run

python -m eon.server --reset removes the catalog directory Paths.kdb with the rest of the run’s data, wherever that path points. A catalog shared between runs or curated by hand needs a copy outside the run, or a Paths.kdb that names a copy. The readcon-db corpus readcon.db is not removed, so after a reset it holds frames that no catalog references. Delete it as well to start from an empty database.

Configuration

[KDB]
pydantic model eon.schema.KDBConfig[source]
Fields:

  • use_kdb (bool)

  • kdb_only (bool)

  • remove_duplicates (bool)

  • kdb_name (str)

  • kdb_nf (float)

  • kdb_dc (float)

  • kdb_mac (float)

field use_kdb: bool = False
field kdb_only: bool = False

Only use KDB in an AKMC simulation, no random searches.

field remove_duplicates: bool = False

KDB will not make duplicate suggestions. This can slow KDB querying, so it may be best to use this only for slow potentials (DFT, etc.).

field kdb_name: str = 'kdb.db'

Unused name kept so old ini files still parse. The catalog directory is Paths.kdb.

field kdb_nf: float = 0.2

Neighbor fudge, a fraction. The match tolerance is kdb_dc * (1 + kdb_nf) angstroms.

field kdb_dc: float = 0.3

Distance cutoff in angstroms. A stored reactant whose atoms sit farther than kdb_dc * (1 + kdb_nf) from the current state is not a match.

field kdb_mac: float = 0.7

Minimum absolute cosine between the stored mode and the reactant-to-saddle displacement. At or above this value the refine uses the stored mode. Below it, the refine uses the reactant-to-saddle vector.

References

[KDB_TWCH12]

Rye Terrell, Matthew Welborn, Samuel T. Chill, and Graeme Henkelman. Database of atomistic reaction mechanisms with application to kinetic Monte Carlo. The Journal of Chemical Physics, 137(1):014105, July 2012. doi:10.1063/1.4730746.