structure

Tools for structure generation, defect identification and visualization

Functions

create_def_structure_for_visualization	Create defect structure for visualization software.
create_interstitial_structures	Create interstitial structures based on Voronoi with pymatgen, staring from a bulk structure (unit cell or supercell).
create_substitution_structures	Create substitution structures for each non-equivalent site, staring from a bulk structure (unit cell or supercell).
create_vacancy_structures	Create Vacancy objects for each non-equivalent site, staring from a bulk structure (unit cell or supercell).
defect_finder	Find defects by comparing defect and bulk structures.
get_trajectory_for_visualization	Create trajectory from defect and bulk structures for visualization.
write_extxyz_for_visualization	Write extxyz file for visualization.

create_def_structure_for_visualization(structure_defect, structure_bulk, defects=None, sort_to_bulk=False, tol=0.001)

Create defect structure for visualization software. The vacancies are shown by inserting in the vacant site the element of same row and next group on the periodic table. If sort_to_bulk is True the Sites are sorted to match the Bulk structure.

Parameters:

• structure_defect (Structure) – Defect structure.

• structure_bulk (Structure) – Bulk structure.

• defects (list) – List of defect objects. If None defect_finder is used.

• sort_to_bulk (bool) – Sort Sites of the defect structure to match the order of coordinates in the bulk structure (useful if the non-relaxed defect structure is not available). If False only the dummy atoms are inserted and not further changes are made.

• tol (float) – Tolerance for site comparison. The distance between sites in target and reference stucture is used, periodicity is accounted for. The tolerance is normalized with respect to lattice vector size. The default is 1e-03.

Returns:

new_structure – Structure with dummy atoms as vacancies and interstitials at the end of the list. The order of the sites follow the order of the Bulk structure.

Return type:

Structure

create_interstitial_structures(structure, elements, supercell_size=None, **kwargs)

Create interstitial structures based on Voronoi with pymatgen, staring from a bulk structure (unit cell or supercell). Uses Interstitial objects generated with the generator module.

Parameters:

• structure (Structure) – Bulk structure.

• elements (list) – List of element symbols.

• supercell_size (int) – Input for the make_supercell function of the Structure class. If None the input structure is not modified.

• kwargs –

  Kwargs to pass to VoronoiInterstitialGenerator:

  • clustering_tol: Tolerance for clustering the Voronoi nodes.

  • min_dist: Minimum distance between an interstitial and the nearest atom.

  • ltol: Tolerance for lattice matching.

  • stol: Tolerance for structure matching.

  • angle_tol: Angle tolerance for structure matching.

  • kwargs: Additional keyword arguments for the TopographyAnalyzer constructor.

Returns:

structures – List of interstitial structures.

Return type:

list

create_substitution_structures(structure, elements_to_replace, supercell_size=None, **kwargs)

Create substitution structures for each non-equivalent site, staring from a bulk structure (unit cell or supercell). Uses Substitution objects generated with the generator module.

Parameters:

• structure (Structure) – Bulk structure, both unit cell or supercell can be used as input.

• elements_to_replace (dict) – Dict with element symbol of specie to be replaced as keys and element symbol of the species to be replaced with as values ({‘old_El’:’new_El’}).

• supercell_size (int or numpy array) – Input for the make_supercell function of the Structure class. If None the input structure is not modified.

• kwargs (dict) –

  Kwargs to pass to SpaceGroupAnalyzer class:

  • symprec (float):

    Tolerance for symmetry finding. Defaults to 0.01, which is fairly strict and works well for properly refined structures with atoms in the proper symmetry coordinates. For structures with slight deviations from their proper atomic positions (e.g., structures relaxed with electronic structure codes), a looser tolerance of 0.1 (the value used in Materials Project) is often needed.

  • angle_tolerance (float):

    Angle tolerance for symmetry finding. Defaults to 5 degrees.

Returns:

structures – List of substitution structures.

Return type:

list

create_vacancy_structures(structure, elements=None, supercell_size=None, **kwargs)

Create Vacancy objects for each non-equivalent site, staring from a bulk structure (unit cell or supercell). Uses Vacancy objects generated with the generator module.

Parameters:

• structure (Structure) – Bulk structure, both unit cell or supercell can be used as input.

• elements (str) – Symbol of the elements for which vacancies are needed. If None all of the elements are considered.

• supercell_size (int or numpy array) – Input for the make_supercell function of the Structure class. If None the input structure is not modified.

• kwargs (dict) –

  Kwargs to pass to SpaceGroupAnalyzer class:

  • symprec (float):

    Tolerance for symmetry finding. Defaults to 0.01, which is fairly strict and works well for properly refined structures with atoms in the proper symmetry coordinates. For structures with slight deviations from their proper atomic positions (e.g., structures relaxed with electronic structure codes), a looser tolerance of 0.1 (the value used in Materials Project) is often needed.

  • angle_tolerance (float):

    Angle tolerance for symmetry finding. Defaults to 5 degrees.

Returns:

structures – List of vacancy structures.

Return type:

(list)

defect_finder(structure_defect, structure_bulk, tol=0.001, max_number_of_defects=None, verbose=False)

Find defects by comparing defect and bulk structures.

Parameters:

• structure_defect (Structure) – Defect structure.

• structure_bulk (Structure) – Bulk structure.

• tol (float) – Tolerance for fractional coordinates comparison (default is 1e-3).

• max_number_of_defects (int) – Impose a max number of defects to be found. If set, defects are ranked based on the coordinate distance btw defect and bulk sites (descending order), the first max_number_of_defects in the list are given as the output (as single defect or defect complex).

• verbose (bool) – Print output.

Return type:

Defect object (Vacancy, Substitution, Interstitial, DefectComplex). Not implemented for Polaron.

get_trajectory_for_visualization(structure_defect, structure_bulk, defects=None, tol=0.001, file=None)

Create trajectory from defect and bulk structures for visualization. The vacancies are shown by inserting in the vacant site the element of same row and next group on the periodic table.

Parameters:

• structure_defect (Structure) – Defect structure.

• structure_bulk (Structure) – Bulk structure.

• defects (list) – List of Defect objects. If None defect_finder is used.

• tol (float) – Tolerance for site comparison. The distance between sites in target and reference stucture is used, periodicity is accounted for. The tolerance is normalized with respect to lattice vector size. The default is 1e-03.

• file (str) – File to save XDATCAR.

Return type:

Trajectory object.

write_extxyz_for_visualization(file, structure_defect, structure_bulk, defects=None, tol=0.001)

Write extxyz file for visualization. The displacements w.r.t the bulk structure are included. The vacancies are shown by inserting in the vacant site the element of same row and next group on the periodic table.

Parameters:

• file (str) – Path to save file.

• structure_defect (Structure) – Defect structure.

• structure_bulk (Structure) – Bulk structure.

• defects (list) – List of Defect objects. If None defect_finder is used.

• tol (float) – Tolerance for site comparison. The distance between sites in target and reference stucture is used, periodicity is accounted for. The tolerance is normalized with respect to lattice vector size. The default is 1e-03.