Usage¶

A KMCConfiguration consists of a KMCLattice and the element type information in each lattice site. A KMCConfiguration is given to the KMCLatticeModel to represent the initial geometry of the simulation.

Interface¶

class KMCLib.KMCConfiguration(lattice=None, types=None, possible_types=None, default_type=None)¶

Class for representing the configuration in a KMC simulation.

_KMCConfiguration__checkAndSetBucketsTypes(types, default_type, possible_types)¶

_KMCConfiguration__checkAndSetLongTypes(types, default_type, possible_types)¶

_KMCConfiguration__checkAndSetShortTypes(types, default_type, possible_types)¶

_KMCConfiguration__detectTypesFormat(types)¶

__init__(lattice=None, types=None, possible_types=None, default_type=None)¶

Constructor for the KMCConfiguration - the configuration object to use in the KMC simulations.

Parameters:

lattice – The lattice of the configurartion as a KMCLattice. types – The site types at the lattice points as a list, e.g. [‘type1’,’type2’,..], ordered as [a,b,c,i] with i being the fastest and a the slowest index and a, b and c refers to the cell repetitions and i refers to the specific basis point in the cell. When using this format one cannot specify a default type, and the number of elements in the types list must match the number of grid points in the lattice. Alternatively one can specify the types input as a list of tuples specifying the a,b,c,i for each type, e.g. [(0,0,1,0,’a’), (0,0,1,1,’b’), ...]. If one uses the longer tuple format a default type should be given, which then will be used for all points not explicitly specified in the list. possible_types – A list of possible types. If not given this list will be set to the types present in the types list by default. default_type – This input parameter can only be given if the types are given in long format i.e. [(0,0,1,0,’a’), (0,0,1,1,’b’), ...] The default type will then be used for lattice sites not specified in the types list.

_atkScript(types_map)¶

Generate an ATK 12.8.2 compatible BulkConfiguration script of this configuration.

Parameters:	types_map – A map between the KMCLib types used in this configuration and ATK type names as a dict, where keys are the type names used in this configuration and the corresponding values are the ATK types to be used given as strings. Any type not specified in the mapping will be left out in the ATK configuration.
Returns:	An ATK script as a string representing this configuration.

_backendTypeNames()¶

Get a tuple with the type names order the same way as the buckets backend implementation.

_script(variable_name='configuration')¶

Generate a KMCLib Python script representation of this configuration.

Parameters:	variable_name (str) – A name to use as variable name for the KMCConfiguration in the generated script.
Returns:	A KMCLib Python script, as a string, that can generate this configuration.

atomIDCoordinates()¶

Query for the coordinates per atom id.

atomIDTypes()¶

Query for the types indexed according to the atom_ids.

cellRepetitions()¶

Query for the primitive cell repetitions.

latestEventProcess()¶

Query for the process number of the latest event.

latestEventSite()¶

Query for the site index of the latest event.

lattice()¶

Query for the lattice.

movedAtomIDs()¶

Query for the moved atom_id:s of the last move.

particlesPerType()¶

Query function for the number of particles per type.

Returns:	The current number of particles per type.

possibleTypes()¶

Query function for the possible types dict.

Returns:	The stored possible types dict.

sites()¶

Query function for the lattice sites.

Returns:	The lattice sites.

types()¶

Query function for the types of the configuration.

Returns:	The stored types list.

Notes¶

For a lattice KMC simulation the lattice positions do not change during the simulation, but if move vectors are specified in the processes (see the KMCProcess documentation for details), the configuration keeps track of all individual atoms occupying the lattice sites. The KMCConfiguration has internally a dual representation of the geometry, keeping track of the type at each lattice site, as well as the coordinates for each atom-ID. The atom-IDs are assigned at the start of the simulation, or earlier when otherwise asked for via any of the query functions involving atom-IDs. The initial assignment of the atom-IDs follows the order of the given initial types.

The KMCConfiguration comes with the ability to script itself using the _script method, meaning that it can produce a string that, if interpreted as a Python script, generates a copy of the configuration. This can be a convenient way to store a configuration for later use, especially if the configuration was first generated using a more complex Python script.

As an extra bonus KMCConfiguration can also generate a corresponding ATK script for easy visualization with VNL from QuantumWise. Since the type of configuration used in VNL must have an element from the periodic system for each coordinate the _atkScript method takes a dict as argument that translates the types to periodic table elements. Any type present in the KMCConfiguration which is not in the dict will be ignored when generating the ATK script.

If you have suggestions for other scripts or file formats that you think would be convenient if the KMCConfiguration could generate you can easily extend the class with another method. You just follow the examples of the _script and _atkScript methods. We would of course be happy to see contributions of this kind being submitted back to us for inclusion in future releases.

Usage¶

A KMCInteractions object is given as one of the arguments when constructing the KMCLatticeModel, and contains information about all interactions in the simulated system. The KMCInteractions is constructed with a list of all possible elementary processes in the simulated system as a list of KMCProcess objects, and can also be equipped with a KMCRateCalculatorPlugin by calling its setRateCalculator method. An added custom rate calculator will have the ability to dynamically update the rate constants associated with the elementary processes at different lattice sites during the simulation.

Interface¶

class KMCLib.KMCInteractions(processes=None, implicit_wildcards=None)¶

Class for holding information about all possible interactions used in a Lattice KMC simulation.

__init__(processes=None, implicit_wildcards=None)¶

Constructor for the KMCInteractions.

Parameters:	processes – A list of possible processes in the simulation. implicit_wildcards (bool) – A flag indicating if implicit wildcards should be used in the matching of processes with the configuration. The default is True, i.e. to use implicit wildcards.

implicitWildcards()¶

Query for the implicit wildcard flag.

Returns:	The implicit wildcard flag stored.

rateCalculator()¶

Query for the rate calculator. :returns: The stored rate calculator.

setRateCalculator(rate_calculator=None)¶

Set the rate calculator of the class. The rate calculator must be set before the backend is generated to take effect.

Parameters:	rate_calculator – A class inheriting from the KMCRateCalculatorPlugin interface. If not given the rates specified for each process will be used unmodified.

Notes¶

The implicit_wildcards parameter to the constructor specifies how the local geometries of the KMCProcess input should be interpreted, and will have a crucial impact on the outcome of a simulation. If implicit_wildcards=True (default behavior), then the geometries of all processes will be compared to the geometry of the lattice at the type of basis site where the process is applicable as specified on construction of each KMCProcess object. If there are lattice sites within the cutoff of the process that are not specified in the process geometry these sites will be added to the process with a wild-card marker as type, meaning that any type on the corresponding lattice position will be regarded as a match when the process is compared to a lattice site. If implicit_wildcards=False only wild-cards explicitly specified in each KMCProcess will be considered. See the KMCProcess documentation for further details.

Usage¶

A KMCProcess represents an elementary process in the KMC simulation. Every possible way to move particles in the simulation must be represented with KMCProcess objects. A list of KMCProcess objects containing all this information must be specified to construct the the KMCInteractions object.

Interface¶

class KMCLib.KMCProcess(coordinates=None, elements_before=None, elements_after=None, move_vectors=None, basis_sites=None, rate_constant=None)¶

Class for representing a possible process in a lattice KMC simulation.

__eq__(other)¶

Implements the equal oprator.

__init__(coordinates=None, elements_before=None, elements_after=None, move_vectors=None, basis_sites=None, rate_constant=None)¶

Constructor for the KMCProcess.

Parameters:

coordinates – The local coordinates, corresponding to the lattice positions of the surrounding of the center where the process will be preformed. elements_before – The elements, as a list of strings, before the process is preformed. This list of elements will be used to match the local surroundings of each center in the simulation, to determine at which sites the process can be performed. elements_after – The elements, as a list of strings, after the process is preformed. This list of elements will be used to update the local surrounding of the site where the process is performed. move_vectors – A set of vectors in the local coordinates that define which elements are moved to which place in the move. The vectors are given as a list of tuples, where the first element in each tuple indicates which index is moved and the second element in the tuple is a vector in local coordinates indicating where the move is to. basis_sites – The basis sites in the lattice at which the process can possibly be applied. Only if the length of this list is 1 can implicit wildcards be used for the matching. rate_constant (float) – The rate constant associated with this process.

elementsAfter()¶

Query for the elements before.

Returns:	The elements before stored on the class.

elementsBefore()¶

Query for the elements before.

Returns:	The elements before stored on the class.

Notes¶

A process can be specified with or without move vector input. The simplest form of the KMCProcess uses no move vectors. In this case the KMCProcess is constructed with the local geometry around the type of lattice site it should be applied to, as well as with the corresponding list of types at the lattice sites before and after the process is applied. When the process is applied at a lattice site the type information at the involved sites is updated. With no move vectors given, the types information is updated without keeping track of which specific atom went to which new site. Tracking of individual atoms is some times necessary, e.g. when calculating the mean square displacement of atoms with the built in OnTheFlyMSD analysis. To keep track of the positions of the individual atoms (or particles) in a simulation move vectors must be specified for all relevant processes.

The KMCProcess can be specified with the use of wild-cards for matching any type at a certain lattice site. If a wild-card is explicitly specified (using the ‘*’ symbol as type) it must stay in the same position in the elements_before and elements_after lists. Wild-cards can also be used by simply omitting the corresponding positions in the coordinates and elements lists and instead use the implicit_wildcards=True option when constructing the KMCInteractions. A restriction applies that implicit wild-cards can only be used for processes that are applicable at one type of basis site only (i.e. with len(basis_sites)=1).

Usage¶

The KMCLocalConfiguration is used to internally represent local geometry around a lattice site in the KMCProcess object.

Interface¶

class KMCLib.KMCLocalConfiguration(coordinates=None, types=None, center=None)¶

Class for representing the local environment around a central site in a Lattice KMC simulation.

__init__(coordinates=None, types=None, center=None)¶

Constructor for the KMCLocalConfiguration.

Parameters:

coordinates – The coordinates of the configuration given as a 3xN sequence of floating point numbers, where N is the number of local sites. types – The lattice site types at the specified coordinates given as a sequence of strings of length N. center (int) – The coordinate in the list to treat as the central site indexed from zero. If not given it will default to the first coordinate (i.e. center == 0).

coordinates()¶

Query function for the coordinates stored on the class.

Returns:	The stored coordinates.

types()¶

Query function for the types stored on the class.

Returns:	The stored types.

Usage¶

The KMCUnitCell is given as an argument when constructing a KMCLattice to use with a KMCConfiguration. The KMCUnitCell is specified both to obtain information on the basis sites to use in the repeated primitive cell when constructing the lattice, and also to obtain a mapping from Cartesian space to the internal geometry based on the lattice vectors of the primitive cell. This mapping has currently only one usage in KMCLib, when using the OnTheFlyMSD analysis where a transformation to Cartesian coordinates is performed using the information provided from the KMCUnitCell class.

Interface¶

class KMCLib.KMCUnitCell(cell_vectors=None, basis_points=None)¶

Class for describing a unitcell.

__init__(cell_vectors=None, basis_points=None)¶

Constructor for the KMCUnitCell class.

Parameters:	cell_vectors – A 3x3 matrix, nested lists or numpy array with rows corresponding to the a, b and c vectors in cartesian coordinates. basis_points – A Nx3 matrix, nested lists or numpy array with each row corresponding to the fractional coordinates of a basis point.

basis()¶

Query for the bais points.

Returns:	The basis points stored on the class.

cellVectors()¶

Query for the cell vectors.

Returns:	The cell vectors stored on the class.

transformToCartesian(r)¶

Transform an internal coordinate list to cartesian coordinates.

Returns:	The coordinates in cartesian units.

Usage¶

The KMCLattice is used to define the topology of a lattice KMC simulation. It consists of a KMCUnitCell and information about repetitions of this cell and the periodicity of the lattice. The KMCLattice is used for input when constructing the KMCConfiguration.

Interface¶

class KMCLib.KMCLattice(unit_cell=None, repetitions=None, periodic=None)¶

Class for describing the lattice used in a KMC simulation.

__init__(unit_cell=None, repetitions=None, periodic=None)¶

Constructor for the Lattice used in the KMC simulations.

Parameters:

unit_cell – The unitcell object to represent the periodicity of the lattice. repetitions – The repetitions of the unitcell along the a,b and c directions to create the full lattice, given as a list or tuple of three integers > 0. If not given this defaults to (1,1,1) periodic ((bool,bool,bool)) – A list or tuple indicating if periodicity should be used along the a, b and c directions. If not specified it defaults to (True,True,True)

basis()¶

Query function for the basis.

Returns:	The basis of the unit cell.

periodic()¶

Query function for the periodicity.

Returns:	The periodicity information along the a b and c directions.

repetitions()¶

Query function for the repetitions.

Returns:	The repetitions used to construct the full lattice from the unit cell.

sites()¶

Query function for the sites data.

Returns:	The sites data in fractional units of the original unit cell.

unitCell()¶

Query function for the unit cell.

Returns:	The unit cell.

Usage¶

The KMCLatticeModel is the central object in KMCLib to perform a lattice KMC simulation. The model is constructed with a KMCConfiguration and KMCInteractions, and is run by calling its run method with parameters given in a KMCControlParameters object.

Interface¶

class KMCLib.KMCLatticeModel(configuration=None, interactions=None)¶

Class for representing a lattice KMC model.

__init__(configuration=None, interactions=None)¶

The KMCLatticeModel class is the central object in the KMCLib framework for running a KMC simulation. Once a configuration with a lattice is defined and a set of interactions are setup, the KMCLatticeModel object unites this information, checks that the given interactions match the configurations, and provides means for running a KMC Lattice simulation.

Parameters:	configuration – The KMCConfiguration to run the simulation for. interactions – The KMCInteractions that specify possible local states and barriers to use in the simulation.

run(control_parameters=None, trajectory_filename=None, trajectory_type=None, analysis=None, breakers=None)¶

Run the KMC lattice model simulation with specified parameters.

Parameters:

control_paramters – An instance of KMCControlParameters specifying number of steps to run etc. trajectory_filename – The filename of the trajectory. If not given no trajectory will be saved. trajectory_type – The type of trajectory to use. Either ‘lattice’ or ‘xyz’. The ‘lattice’ format shows the types at the latice points. The ‘xyz’ format gives type and coordinate for each particle. The default type is ‘lattice’. analysis – A list of instantiated analysis objects that should be used for on-the-fly analysis. breakers – A list of instantiated breaker objects to break the Monte Carlo loop with a custom criterion.

Notes¶

When running the model the KMCControlParameters specify how often the trajectory will be saved and how often information should be printed to standard output. This is controlled with the dump_intervall parameter in the KMCControlParameters class. If no trajectory is needed the trajectory_filename argument can be left empty. This will produce a warning message that no trajectory file is specified but the simulation will run correctly only without storing trajectory information. If no trajectory information is needed it can still be useful to store the last configuration to make a restart point to continue the simulation from if needed. This can be achieved by specifying a trajectory file name and setting the dump_intervall equal to the number_of_steps in the KMCControlParameters. A potential drawback using such approach is that no information will be printed to standard output during the simulation.

Two different types of trajectory formats are currently implemented. trajectory_type='lattice' gives a lattice trajectory, where the lattice positions is specified only once, and at each step only the type at each lattice site is stored. Using trajectory_type='xyz' instead causes the trajectory to be stored with the coordinates and type for each atom-ID at each saved step. This type of trajectory is only meaningful if the processes specify move_vectors for how the individual atoms move during the simulation.

Much flexibility and extendability is added to KMCLib with the possibility to specify custom on-the-fly analysis objects that can be used in the simulation. These objects must inherit from the KMCAnalysisPlugin interface and are given to the run method in a list using the analysis=[...] parameter. How often analysis is performed is controlled using the analysis_intervall parameter in the KMCControlParameters class.

Usage¶

KMCControlParameters is a container for parameters such as the number of steps and the seed to the random number generator, needed to run a KMCLatticeModel.

Interface¶

class KMCLib.KMCControlParameters(number_of_steps=None, dump_interval=None, analysis_interval=None, seed=None, dump_time_interval=None, rng_type=None)¶

Class for handling the control parameters that goes in to a KMC simulation.

__init__(number_of_steps=None, dump_interval=None, analysis_interval=None, seed=None, dump_time_interval=None, rng_type=None)¶

Constructuor for the KMCControlParameters object that holds all parameters controlling the flow of the KMC simulation.

Parameters:

number_of_steps (int) – The number of KMC steps to take. If not provided the default value 0 will be used. dump_interval (int) – The number of steps between subsequent trajectory dumps. The default value is 1, i.e. dump every step. analysis_interval (int) – The number of steps between subsequent calls to the custom analysis ‘registerStep’ functions. The default value is 1, i.e. analysis every step. seed (int) – The seed value to use for the backend random number generator. If no seed value is given the random numnber generator will be seeded based on the wall-clock time. dump_time_interval – The simulation time between subsequent trajectory dumps. The default value is None, causing the dump_interval parameter to determine the behavior. rng_type (str) – The type of pseudo random number generator to use. The random number generators are the once in the standard C++ library and the supported types maps directly to the given C++ construction as indicated here: ‘MT’ for Mersenne-Twister (Default) [rng = std::mt19937], ‘MINSTD’ for the ‘minimum standard’ rng [rng = std::minstd_rand], ‘RANLUX24’ for the 24-bit version of the ranlux rng [rng = std::ranlux24], ‘RANLUX48’ for the 48-bit version of the ranlux rng [rng = std::ranlux48]. The sequence of pseudo-random numbers are then generated by repeated calls to std::generate_canonical<double, 32>(rng); See: http://en.cppreference.com/w/cpp/numeric/random for further details on C++ random number generators. There is also the option ‘DEVICE’ for using a random device installed on the macine through [rng = std::random_device] in C++. Note however that you should spend some time evaluating this option to make sure it works as you expect if you have a random device installed.

analysisInterval()¶

Query for the analysis interval.

Returns:	The analysis interval.

dumpInterval()¶

Query for the dump interval.

Returns:	The dump interval.

dumpTimeInterval()¶

Query for the dump time interval.

Returns:	The dump time interval.

numberOfSteps()¶

Query for the number of steps.

Returns:	The number of steps.

rngType()¶

Query for the pseudo random number generator type.

seed()¶

Query for the seed value.

Returns:	The seed value.

timeSeed()¶

Query for the time seed value.

Returns:	The time seed value.