KineticMonteCarlo

class KineticMonteCarlo(rate_matrix, initial_state=0, superbasin_threshold=None, rng=None)

Construct a kinetic Monte Carlo simulation.

Parameters:
  • rate_matrix (PhysicalQuantity of type frequency) – A right handed (rows sum to 1) rate matrix. This must be a square matrix.
  • initial_state (int) – The initial state of the KMC simulation. This corresponds to a row index in the rate_matrix.
    Default: 0
  • superbasin_threshold (int) – The number of steps between two states before they are merged together and treated with the coarse graining algorithm. A value of None disables coarse graining.
    Default: None
  • rng (numpy.random.mtrand.RandomState) – The random number generator used to generate the random number stream. If None, a new random number generator stream will be made with a seed obtained from the operating system’s entropy pool.
    Default: None
findSuperbasin(state)

Find the superbasin that contains the state.

Parameters:state (int) – The state to find the containing superbasin of.
Returns:Superbasin if the state is in a superbasin, otherwise None.
Return type:Superbasin | None
getTransitionCount(state_1, state_2)
Parameters:
  • state_1 (int) – The first of the two states.
  • state_2 (int) – The second of the two states.
Returns:

The transition count between two states.

Return type:

int

mergeStates(state_1, state_2)

Merge two states together. If either or both states belong to a superbasin, the superbasins are merged instead.

Parameters:
  • state_1 (int) – The first of the two states to merge.
  • state_2 (int) – The second of the two states to merge.
nlprint(stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Print out the trajectory of the KMC simulation.

Parameters:stream (A stream that supports strings being written to using 'write'.) – The stream to write the trajectory to.
Default: sys.stdout
numberOfSteps()
Returns:The total number of steps taken in this KMC simulation.
Return type:int
setRateMatrix(rate_matrix)

Set a new rate matrix.

Parameters:rate_matrix (PhysicalQuantity of type frequency) – A right handed (rows sum to 1) rate matrix. This must be a square matrix.
setSuperbasinThreshold(superbasin_threshold)

Sets the superbasin threshold.

Parameters:superbasin_threshold (int) – The number of steps between two states before they are merged together and treated with the coarse graining algorithm. A value of “None” disables coarse graining.
Default: None
state()
Returns:The current state of the Markov chain.
Return type:int
step()

Take a single KMC step.

Returns:The escape time from the current state.
Return type:PhysicalQuantity of type frequency
superbasinThreshold()
Returns:Return the superbasin threshold.
Return type:int
superbasins()
Returns:The list of superbasins.
Return type:list of type Superbasin
time()
Returns:The total time that has elapsed during the KMC simulation.
Return type:float
times()
Returns:The times associated with each state in the trajectory.
Return type:PhysicalQuantity of type time
trajectory()
Returns:The KMC trajectory. This is a list of integer state numbers (row index in the rate matrix).
Return type:list of type int
updateTransitionCount(state_1, state_2)

Update the transition count between two states. This method also merges states together when the transition count equals the superbasin threshold parameter.

Parameters:
  • state_1 (int) – The first of the two states.
  • state_2 (int) – The second of the two states.

Usage Examples

Setup a simple KMC simulation with three states and print the results.

# Define a rate matrix. The ij entries describe the reaction rate from state i to state j.
rate_matrix = [
    [ 0.0, 1e9, 0.0 ],
    [ 1e8, 0.0, 1e7 ],
    [ 0.0, 1e6, 0.0 ],
]/Second

kmc = KineticMonteCarlo(
    rate_matrix,
    initial_state=0,
    )

for i in range(1000):
    kmc.step()

nlprint(kmc)

kmc.py

Notes

KineticMonteCarlo objects are normally passed to the AdaptiveKineticMonteCarlo class.

This class can also be used to setup a KMC simulation manually. The only input that is required is the matrix of reaction rates. No configurations are used. It is up to the user to give meaning to each of states in the KMC trajectory.

The treatment of superbasins using the Monte Carlo with absorbing Markov chains (MCAMC) algorithm is described in refs [Nov95][CWT+14].

[CWT+14]S. T. Chill, M. Welborn, R. Terrell, L. Zhang, J.-C. Berthet, A. Pedersen, H. Jónsson, and G. Henkelman. Eon: software for long time simulations of atomic scale systems. Modelling Simul. Mater. Sci. Eng., 22(5):055002, 2014. doi:10.1088/0965-0393/22/5/055002.
[Nov95]M. A. Novotny. Monte carlo algorithms with absorbing markov chains: Fast local algorithms for slow dynamics. Phys. Rev. Lett., 74:1–5, Jan 1995. doi:10.1103/PhysRevLett.74.1.