Analysis¶
All built in analysis in KMCLib is implemented using the KMCAnalysisPlugin interface and is performed on-the-fly during the simulation. At present there are two analysis options included, the OnTheFlyMSD for mean square displacement analysis and the TimeStepDistribution analysis for recoding the distribution of time steps during the simulation. On-the-fly analysis objects are used by giving them as as a arguments to the run function of the KMCLatticeModel. Have a look at the Usage examples for details.
How often analysis is performed during the simulation is controlled by the analysis_interval parameter of the KMCControlParameters. For future releases we will consider to let each analysis object itself decide how often it should be used, but for the moment all analysis is performed equally often.
On-the-fly mean square displacement (MSD)¶
Usage¶
The OnTheFlyMSD analysis is used by giving it as an argument to the run function of the KMCLatticeModel. Have a look at the Usage examples for details.
Interface¶
- class KMCLib.OnTheFlyMSD(history_steps=None, n_bins=None, t_max=None, track_type=None)¶
Class for performing on-the-fly MSD analysis.
- __init__(history_steps=None, n_bins=None, t_max=None, track_type=None)¶
Constructor for the OnTheFlyMSD.
Parameters:
- binCounters()¶
Query function for the bin counters.
Returns: The number of values that was averaged over in each bin.
- finalize()¶
Recieves the finalize call after the MC loop.
- printResults(stream=<open file '<stdout>', mode 'w' at 0x2b9b574a91e0>)¶
Print the results to a stream.
Parameters: stream – The stream to print to. Defaults to ‘sys.stdout’.
- registerStep(step, time, configuration)¶
Recieves the step call from the MC loop.
Parameters:
- results()¶
Query function for the result.
Returns: The results as a 7*N numpy array with the MSD data in the x, y and z, direction and averaged over the xy, xz, and yz planes finally over all space xyz (expressed in cartesian coordinates).
- safeCutoff()¶
Query function for the safe cutoff as determined by the start of the last contributing convolution.
Returns: The bin index for the cutoff.
- setup(step, time, configuration)¶
Recieves the setup call from the before the MC loop.
Parameters:
- stdDev()¶
Query function for the standard deviation.
Returns: The standard deviation of the results, as a 7*N numpy array where the columns correspond to the directions in the results data.
- timeSteps()¶
Query function for the time steps.
Returns: The bin center time values of the MSD(t) histogram.
Notes¶
The OnTheFlyMSD analysis implements the method described in [Ref.7]. It produces the MSD curves with correct error estimates for Brownian motion but can overestimate the errors for confined motion or diffusion with flow. See [Ref.7] for details.
You have to give the element type to track as argument to the constructor. If you want to calculate the MSD of several different types simultaneously you can instantiate and use several different OnTheFlyMSD objects at the same time.
Note that to be meaningful this analysis requires that move vectors are given to the processes so that individual atom movements can be traced. See the KMCProcess documentation for details.
Future versions might include a way to automatically obtain a reasonable starting guess for the parameters. For the moment, however, you will have to find a good set of parameters yourself. The method can be sensitive and you should make sure you run with a reasonable bin-size, max time and number of history steps. You should be careful and plot the resulting MSD curve after a short simulation to make sure your parameters are reasonable before you run and longer production simulations to estimate the diffusion constants.
One way to estimate reasonable parameters is to look at the TimeStepDistribution of a short simulation with the same system and chose a bin_size roughly equal to the mean of the time step distribution, and use as many bins as you have history steps.
Time-step distribution¶
Usage¶
The TimeStepDistribution analysis is used by giving it as an argument to the run function of the KMCLatticeModel in the same way as the OnTheFlyMSD analysis. You can have a look at the Usage examples for details.
Interface¶
- class KMCLib.TimeStepDistribution(binsize=None)¶
Class for collecting the time step distribution during a simulation.
- __init__(binsize=None)¶
Constructor for the time step distribution analysis object.
Parameters: binsize (float) – The size of the bins in the histogram.
- finalize()¶
Recieves the finalize call after the MC loop.
- histogram()¶
Query function for the histogram.
Returns: The raw histogram as a numpy array.
- normalizedHistogram()¶
Query function for the histogram normalized to 1.
Returns: The normalized historgram.
- printResults(stream=<open file '<stdout>', mode 'w' at 0x2b9b574a91e0>)¶
Print the results to the stream.
Parameters: stream – The stream to print to.
- registerStep(step, time, configuration)¶
Recieves the step call from the MC loop.
- setup(step, time, configuration)¶
Recieves the setup call from before the MC loop.
- timeSteps()¶
Query function for the time steps (x-values).
Returns: The time steps as a numpy array.
Notes¶
The TimeStepDistribution analysis is very simple and could serve as a good example if you want to implement your own analysis. Have a look at the source code.
Your contributions¶
I have implemented the type of analysis I needed for the specific projects I was working on. There is often no point in guessing what people need. Better to wait for your input. If you have suggestions of what type of analysis would be useful please let me know.
With a little bit of Python knowledge implementing your own analysis module is simple. Follow the example of the TimeStepDistribution and have a look at the KMCAnalysisPlugin documentation. If you have analysis contributions you wish to share, or perhaps even include in the next official release don’t hesitate to let me know.