event_generator

kmcpy.event_generator.find_atom_indices(structure, mobile_ion_identifier_type='specie', atom_identifier='Li+')[source]

a function for generating a list of site indices that satisfies the identifier

Parameters:

  • structure (kmcpy.external.pymatgen_structure) – structure object to work on

  • mobile_ion_identifier_type (str, optional) – elect from: [“specie”,”label”]. Defaults to “specie”.

  • atom_identifier (str, optional) – identifier of atom. Defaults to “Li+”.

  • input (typical) –

  • mobile_ion_identifier_type=specie –

  • atom_identifier="Li+" –

  • mobile_ion_identifier_type=label –

  • atom_identifier="Li1" –

  • mobile_ion_identifier_type=list –

  • atom_identifier=[0 –

  • 1 –

  • 2 –

  • 3 –

  • 4 –

  • 5] –

Raises:

ValueError – mobile_ion_identifier_type argument is strange

Returns:

list of atom indices that satisfy the identifier

Return type:

list

kmcpy.event_generator.generate_event_kernal(len_structure, events_site_list, event_kernal_fname='event_kernal.csv')[source]
event_kernal.csv:

event_kernal[i] tabulates the index of sites that have to be updated after event[i] has been executed

kmcpy.event_generator.generate_events3(prim_cif_name='210.cif', convert_to_primitive_cell=False, local_env_cutoff_dict={('Li+', 'Cl-'): 4.0, ('Li+', 'Li+'): 3.0}, mobile_ion_identifier_type='label', mobile_ion_specie_1_identifier='Na1', mobile_ion_specie_2_identifier='Na2', species_to_be_removed=['O2-', 'O'], distance_matrix_rtol=0.01, distance_matrix_atol=0.01, find_nearest_if_fail=True, export_local_env_structure=True, supercell_shape=[2, 1, 1], event_fname='events.json', event_kernal_fname='event_kernal.csv', verbosity='WARNING', **kwargs)[source]

220603 XIE WEIHANG 3rd version of generate events, using the x coordinate and label as the default sorting criteria for neighbors in local environment therefore should behave similar as generate_events1. Comparing generate_events1, this implementation accelerate the speed of finding neighbors and add the capability of looking for various kind of mobile_ion_specie_1s (not only Na1 in generate_events1). In addtion, generate events3 is also capable of identifying various kind of local environment, which can be used in grain boundary models. Although the _generate_event_kernal is not yet capable of identifying different types of environment. The speed is improved a lot comparing with version2

Parameters:

  • prim_cif_name (str, optional) – the file name of primitive cell of KMC model. Strictly limited to cif file because only cif parser is capable of taking label information of site. This cif file should include all possible site i.e., no vacancy. For example when dealing with NaSICON The input cif file must be a fully occupied composition, which includes all possible Na sites N4ZSP; the varied Na-Vacancy should only be tuned by occupation list.

  • convert_to_primitive_cell (bool, optional) – whether convert to primitive cell. For rhombohedral, if convert_to_primitive_cell, will use the rhombohedral primitive cell, otherwise use the hexagonal primitive cell. Defaults to False.

  • local_env_cutoff_dict (dict, optional) – cutoff dictionary for finding the local environment. This will be passed to local_env.cutoffdictNN`. Defaults to {(“Li+”,”Cl-“):4.0,(“Li+”,”Li+”):3.0}.

  • mobile_ion_identifier_type (str, optional) – atom identifier type, choose from [“specie”, “label”].. Defaults to “specie”.

  • mobile_ion_specie_1_identifier (str, optional) – identifier for mobile_ion_specie_1. Defaults to “Li+”.

  • mobile_ion_specie_2_identifier (str, optional) – identifier for the atom that mobile_ion_specie_1 will diffuse to . Defaults to “Li+”.

  • species_to_be_removed (list, optional) – list of species to be removed, those species are not involved in the KMC calculation. Defaults to [“O2-“,”O”].

  • distance_matrix_rtol (float, optional) – r tolerance of distance matrix for determining whether the sequence of neighbors are correctly sorted in local envrionment. For grain boundary model, please allow the rtol up to 0.2~0.4, for bulk model, be very strict to 0.01 or smaller. Smaller rtol will also increase the speed for searching neighbors. Defaults to 0.01.

  • distance_matrix_atol (float, optional) – absolute tolerance , . Defaults to 0.01.

  • find_nearest_if_fail (bool, optional) – if fail to sort the neighbor with given rtolerance and atolerance, find the best sorting that have most similar distance matrix? This should be False for bull model because if fail to find the sorting ,there must be something wrong. For grain boundary , better set this to True because they have various coordination type. Defaults to True.

  • export_local_env_structure (bool, optional) – whether to export the local environment structure to cif file. If set to true, for each representatibe local environment structure, a cif file will be generated for further investigation. This is for debug purpose. Once confirming that the code is doing correct thing, it’s better to turn off this feature. Defaults to True.

  • supercell_shape (list, optional) – shape of supercell passed to the kmc_build_supercell function, array type that can be 1D or 2D. Defaults to [2,1,1].

  • event_fname (str, optional) – file name for the events json file. Defaults to “events.json”.

  • event_kernal_fname (str, optional) – file name for event kernal. Defaults to ‘event_kernal.csv’.

  • verbosity (str, optional) – verbosity that passed to logging.logger. Select from [“INFO”,”warning”], higher level not yet implemented. Defaults to “INFO”.

Raises:

  • NotImplementedError – the atom identifier type=list is not yet implemented

  • ValueError – unrecognized atom identifier type

  • ValueError – if no events are generated, there might be something wrong with cif file? or atom identifier?

Returns:

nothing is returned

Return type:

nothing

kmcpy.event_generator.normalize_supercell_tuple(site_belongs_to_supercell=[5, 1, 7], image_of_site=(0, -1, 1), supercell_shape=[5, 6, 7], additional_input=False, verbose=False)[source]

finding the equivalent position in periodic supercell considering the periodic boundary condition. i.e., normalize the supercell tuple to make sure that each component of supercell is greater than zero

for example,

# 5 1 7 with image 0 -1 1 -> 5 0 8 -> in periodic 567 supercell should change to 561, suppose supercell start with index1

input: site_belongs_to_supercell: site belongs to which supercell

Returns:

supercell tuple

Return type:

tuple