kmc

Function and classes for running kMC

Author: Zeyu Deng Email: dengzeyu@gmail.com

class kmcpy.kmc.KMC(**kwargs)[source]

main function of kinetic monte carlo

initialization(**kwargs)[source]

initialization function with capability on dealing with multiple versions of input

This function try to grab the api keyword in kwargs. If fail, then set api=1

Then it will call the initialization function of specified version, pass all kwargs to the initialization1 or initialization2… except the api kwargs (of course)

Notice that the initialization functions have default value for the input! It is recommended to set the parameters explicitly. It is better to overdefining the parameters rather than underdefining parameters. Do not worry passing too much argument. For example, pass immutable_sites=[“Zr”,”O”] to initialization1, The initialization1 will receive it as kwargs, do nothing on it and forget it.

Raises:

NotImplementedError – if the api parameter is strange

Returns:

list of kmc.event.Event object, generated by the different version of initialization function

Return type:

list

initialization3(occ=array([-1, -1, -1, -1, -1, -1, -1, -1, 1, -1, -1, -1, -1, -1, -1, 1, -1, 1, -1, -1, 1, -1, -1, -1, -1, -1, -1, -1]), prim_fname='./inputs/EntryWithCollCode15546_Na4Zr2Si3O12_573K.cif', fitting_results='./inputs/fitting_results.json', fitting_results_site='./inputs/fitting_results_site.json', event_fname='./inputs/events.json', supercell_shape=[2, 1, 1], v=5000000000000, T=298, lce_fname='./inputs/lce.json', lce_site_fname='./inputs/lce_site.json', immutable_sites=['Zr', 'O'], convert_to_primitive_cell=False, **kwargs)[source]

XIEWEIHANG 220608

the 3rd version of initialization process.

Parameters:

  • occ (np.array, optional) – this is the chebyshev occupation of sites, representing the initial state of the model. Defaults to np.array([-1, -1, -1, -1, -1, -1, -1, -1, 1, -1, -1, -1, -1, -1, -1, 1, -1, 1, -1, -1, 1, -1, -1, -1, -1, -1, -1, -1]).

  • prim_fname (str, optional) – the primitive cell of the input structure. Defaults to ‘./inputs/prim.cif’.

  • fitting_results (str, optional) – This is the fitting results matrix, related to the activation barrier E_kra. Defaults to ‘./inputs/fitting_results.json’.

  • fitting_results_site (str, optional) – This is the fitting results matrix, related to the site energy E_end Defaults to ‘./inputs/fitting_results_site.json’.

  • event_fname (str, optional) – record all possible event. Defaults to “./inputs/events.json”.

  • supercell_shape (list, optional) – _description_. Defaults to [2,1,1].

  • v (int, optional) – vibration frequency. Defaults to 5000000000000.

  • T (int, optional) – temperature. Defaults to 298.

  • lce_fname (str, optional) – This contains all lce orbit related to the activation barrier E_kra. Defaults to “./inputs/lce.json”.

  • lce_site_fname (str, optional) – This contains all lce orbit related to the activation barrier E_end. Defaults to “./inputs/lce_site.json”.

  • immutable_sites (list, optional) – the sites that do not participate in the monte carlo process. For example,. in NaSICON, the Zr and O do not participate, the Na/Vac and P/S pairs are considered. Defaults to [“Zr”,”O”].

  • verbose (bool, optional) – trying to enable the verbose output. Defaults to False.

  • convert_to_primitive_cell (bool) – whether or not convert input cif file to primitive cell

  • **kwargs – other parameters that are not used in this function. This is for the compatibility of different versions of initialization function.

Returns:

a list of kmc.event.Event object

Return type:

list

propose(events, random_seed=123456, use_numpy_random_kernel=True, api=2, rng=Generator(PCG64) at 0x7FC3CF5611C0, **kwargs)[source]

propose a new event to be updated by update()

Parameters:

  • events (list) – list of event

  • random_seed (int or bool, optional) – random seed, if None, then no randomseed. This only make sense if use_numpy_random_kernel. Defaults to 114514.

  • use_numpy_random_kernel (bool, optional) – whether to Use numpy random number generator. Defaults to True.

  • api (int, optional) – api version. Usage of numpy random kernel is introduced since api=2. Defaults to 2.

  • rng (np.random.generator object, optional) – a random number generator object. Defaults to np.random.default_rng(). Theoratically this function will receive a random number generator object as a input

Raises:

NotImplementedError – for API=1, “propose” function will use the python internal random function. For API=2 and use_numpy_random_kernel=True,” propose” function will use the numpy generator class to generate the random numbers. Other functions are not implemented.

Returns:

what event is chosed by the random, and the time for this event to occur

Return type:

event and time_change

run3(kmc_pass=1000, equ_pass=1, v=5000000000000, T=298, events='./inputs/events.json', comp=1, random_seed=114514, use_numpy_random_kernel=True, verbose=False, mobile_ion_specie='Na', q=1.0, dimension=3, structure_idx=1, elem_hop_distance=3.47782, **kwargs)[source]

kmc main function version 3. Previous versions are removed for readability

Parameters:

  • kmc_pass (int, optional) – number of pass to run. Defaults to 1000.

  • equ_pass (int, optional) – _description_. Defaults to 1.

  • v (int, optional) – refer to paper. Defaults to 5000000000000.

  • T (int, optional) – refer to paper, temperature. Defaults to 298.

  • events (str, optional) – path to event.json. Defaults to “./inputs/events.json”.

  • comp (int, optional) – composition, refer to paper. Defaults to 1.

  • random_seed (int, optional) – random seed. Should only be provided when test the KMC function. IF not testing as developer ,strictly set this to None. Defaults to 114514.

  • use_numpy_random_kernel (bool, optional) – whether use numpy random kernel which enable manually assign the random seed. If not testing as a developer, strictly set this to False. Defaults to True.

  • verbose (bool, optional) – verbose output. Defaults to False.

  • mobile_ion_specie (str, optional) – mobile ion specie to track. Defaults to ‘Na’.

  • q (float, optional) – charge of mobile ion specie. Defaults to 1.0.

  • dimension (int, optional) – dimension of migration. For LiCoO2 it is 2 (2D migration). for NaSICON it is 3. Defaults to 3.

  • structure_idx (int, optional) – structure index . Defaults to 1.

  • elem_hop_distance (float, optional) – the hopping distance for the mobile ion specie, for NasiCON, this is the distance between Na1 and nearest Na2 site, for LiCoO2, this is the distance between 2 Li site. Defaults to 3.47782.

Returns:

return the tracker for testing unit to assert some functions.

Return type:

kmcpy.tracker.Tracker