SubstitutionalGenerator¶

class SubstitutionalGenerator(host_configuration, substitutional_element, symmetry_tolerance=None)¶

A class which describes the possible substitutional defects for a given host material.

Parameters:

host_configuration (BulkConfiguration) – The host configuration.
substitutional_element (PeriodicTableElement) – The element to set as substitutional defect.
symmetry_tolerance (PhysicalQuantity of type length) – The tolerance to be used when determining the symmetries.
Default: 0.1 * Angstrom.

filterByDefectGenerators(defect_generators)¶

Method for filtering a defect generator by keeping the defects that are in one or more other defect generators.

Parameters:: defect_generators (list of BaseDefectGenerator) – The list of defect generators containing the defects to keep after filtering.
Returns:: A filtered defect generator.
Return type:: VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterByDistinctConfigurations(top_n_configurations)¶

Method for selecting a number of distinct unique defects using the MTP structural descriptor.

Parameters:: top_n_configurations (int) – Number of most distinct configurations.
Returns:: A filtered defect generator.
Return type:: VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterByLatticeSpecies(element_list)¶

Method for selecting unique defects by element. Valid only for defect types that are associated with a lattice site, e.g. Vacancies, but not Interstitials.

Parameters:: element_list (PeriodicTableElement | list of PeriodicTableElement) – List of elements to keep after filtering.
Returns:: A filtered defect generator.
Return type:: VacancyGenerator | SubstitutionalGenerator | SplitInterstitialGenerator

filterByLatticeSpeciesAndDistinctConfigurations(top_n_configurations, element)¶

Method for selecting a number of distinct unique defects using the MTP structural descriptor.

Parameters:

top_n_configurations (int) – Number of most distinct configurations.
element (PeriodicTableElement) – Element to keep after filtering.

Returns:

A filtered defect list.

Return type:

SubstitutionalGenerator

filterByPointDefect(point_defects, keep_defects=True)¶

Method for filtering the generator of unique point defects by selecting a specific defects.

Parameters:

point_defects (Sequence of BasePointDefect) – The sequence of point defects to filter.
keep_defects (bool) – Whether or not the given defects are to be kept and all other removed (True) or removed from the generator and all other defect kept (False).
Default: True

Returns:

A filtered defect generator.

Return type:

VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterByPositionInZSlices(start=None, end=None, resolution=None, in_plane_position=None)¶

Select defects along the Z-axis of the cell. This method is intended to be used for configurations that are anisotropic along one direction, such as interfaces or surfaces.

Parameters:

start (PhysicalQuantity of type length) – The start of the position interval.
Default: 0 * Angstrom.
end (PhysicalQuantity of type length) – The end of the position interval.
Default: length of the cell in z direction.
resolution (PhysicalQuantity of type length) – The size of each slice of the interface profile.
Default: 2.0 * Angstrom
in_plane_position (Sequence (2) of type float) – The selected defect in each slice is as close as possible to this fractional coordinate. Mutually exclusive with parameter select_distinct.
Default: [0.5, 0.5]
select_distinct (bool) – Select the most distinct defects per slice. This can be used to sample a diverse configuration space with a minimal number of defects. Mutually exclusive with parameter in_plane_position.
Default: False
defects_per_slice (int) – The number of defects to select per slice. This parameter is only used together with the parameter select_distinct.
Default: 1

Returns:

A filtered defect generator.

Return type:

VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterBySimilarityInZSlices(start=None, end=None, resolution=None, defects_per_slice=None)¶

Select defects along the Z-axis of the cell. This method is intended to be used for configurations that are anisotropic along one direction, such as interfaces or surfaces.

Parameters:

start (PhysicalQuantity of type length) – The start of the position interval.
Default: 0 * Angstrom.
end (PhysicalQuantity of type length) – The end of the position interval.
Default: length of the cell in z direction.
resolution (PhysicalQuantity of type length) – The size of each slice of the interface profile.
Default: 2.0 * Angstrom
defects_per_slice (int) – The number of defects to select per slice. This parameter is only used together with the parameter select_distinct.
Default: 1

Returns:

A filtered defect generator.

Return type:

VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterBySphere(center, radius)¶

Method for filtering unique defects by their position in a sphere.

Parameters:

center (PhysicalQuantity of type position) – The center of the sphere in Cartesian coordinates.
radius (PhysicalQuantity of type length) – The radius of the sphere.

Returns:

A filtered defect generator.

Return type:

VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterBySymmetryIndex(symmetry_indices)¶

Method for filtering the list of unique point defects by selecting specific symmetry indices.

Parameters:: symmetry_indices (int | list of int) – The list of symmetry indices to keep after filtering.
Returns:: A filtered defect generator.
Return type:: VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

filterByZPositionInterval(start=None, end=None)¶

Method for selecting unique defects by their position in an interval of the z axis. Note: The

Parameters:

start (PhysicalQuantity of type length) – The start of the position interval.
Default: 0 * Angstrom.
end (PhysicalQuantity of type length) – The end of the position interval.
Default: length of the cell in z direction.

Returns:

A filtered defect generator.

Return type:

VacancyGenerator | SubstitutionalGenerator | InterstitialGenerator SplitInterstitialGenerator

hostConfiguration()¶

Returns:: The host configuration.
Return type:: BulkConfiguration

indices()¶

Returns:: The defect indices for the current defect generator.
Return type:: list of int

pointDefects()¶

Returns:: The list of unique point defects.
Return type:: Vacancy | Substitutional | Interstitial | DefectCluster | SplitInterstitial

substitutionalElement()¶

Returns:: The element to add as substitutional defect.
Return type:: PeriodicTableElement

symmetryTolerance()¶

Returns:: The symmetry tolerance.
Return type:: PhysicalQuantity of type length

uniqueDefects()¶

Returns:: The list of symmetrically unique point defects with their names and symmetry indices, ordered by increasing index.
Return type:: list of NamedPointDefect

uniqueString()¶: Return a unique string representing the state of the object.

Notes¶

The SubstitutionalGenerator object generates the symmetrically unique substitutional defects for a given host material, by identifying the symmetrically equivalent atoms and positions. In multi-element configurations, substitutions are ignored if the lattice element would not change. The SubstitutionalGenerator object is derived from the BaseDefectGenerator object, and thus contains the common methods from that object.

To create a SubstitutionalGenerator object, a specific host configuration must be given along with the substitution element. Once the generator is created, filters can be added so that only the desired subset of defects are generated.

The unique defects can be returned with the uniqueDefects method as NamedPointDefect objects, which can be used as input for a ChargedPointDefectConfiguration object. The defects and generators can also be given to a Defects object to create the basic defect configurations.