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)
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].