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:: PhysicalQuantity of type time

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

uniqueString()¶: Return a unique string representing the state of the object.

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 [1][2].