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.

# 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)