# pymatgen.transformations.site_transformations module¶

class AddSitePropertyTransformation(site_properties)[source]

Simple transformation to add site properties to a given structure

Parameters: site_properties (dict) – site properties to be added to a structure
apply_transformation(structure)[source]

apply the transformation

Parameters: structure (Structure) – structure to add site properties to
inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.

class InsertSitesTransformation(species, coords, coords_are_cartesian=False, validate_proximity=True)[source]

This transformation substitutes certain sites with certain species.

Parameters: species – A list of species. e.g., [“Li”, “Fe”] coords – A list of coords corresponding to those species. e.g., [[0,0,0],[0.5,0.5,0.5]]. coords_are_cartesian (bool) – Set to True if coords are given in cartesian coords. Defaults to False. validate_proximity (bool) – Set to False if you do not wish to ensure that added sites are not too close to other sites. Defaults to True.
apply_transformation(structure)[source]

Applies the transformation to a structure. Depending on whether a transformation is one-to-many, there may be an option to return a ranked list of structures.

Parameters: structure – input structure return_ranked_list – Boolean stating whether or not multiple structures are returned. If return_ranked_list is a number, that number of structures is returned. depending on returned_ranked list, either a transformed structure or a list of dictionaries, where each dictionary is of the form {‘structure’ = …. , ‘other_arguments’} the key ‘transformation’ is reserved for the transformation that was actually applied to the structure. This transformation is parsed by the alchemy classes for generating a more specific transformation history. Any other information will be stored in the transformation_parameters dictionary in the transmuted structure class.
inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.

class PartialRemoveSitesTransformation(indices, fractions, algo=1)[source]

Remove fraction of specie from a structure. Requires an oxidation state decorated structure for ewald sum to be computed.

Parameters: indices – A list of list of indices. e.g. [[0, 1], [2, 3, 4, 5]] fractions – The corresponding fractions to remove. Must be same length as indices. e.g., [0.5, 0.25] algo – This parameter allows you to choose the algorithm to perform ordering. Use one of PartialRemoveSpecieTransformation.ALGO_* variables to set the algo.

Given that the solution to selecting the right removals is NP-hard, there are several algorithms provided with varying degrees of accuracy and speed. The options are as follows:

ALGO_FAST:
This is a highly optimized algorithm to quickly go through the search tree. It is guaranteed to find the optimal solution, but will return only a single lowest energy structure. Typically, you will want to use this.
ALGO_COMPLETE:
The complete algo ensures that you get all symmetrically distinct orderings, ranked by the estimated Ewald energy. But this can be an extremely time-consuming process if the number of possible orderings is very large. Use this if you really want all possible orderings. If you want just the lowest energy ordering, ALGO_FAST is accurate and faster.
ALGO_BEST_FIRST:
This algorithm is for ordering the really large cells that defeats even ALGO_FAST. For example, if you have 48 sites of which you want to remove 16 of them, the number of possible orderings is around 2 x 10^12. ALGO_BEST_FIRST shortcircuits the entire search tree by removing the highest energy site first, then followed by the next highest energy site, and so on. It is guaranteed to find a solution in a reasonable time, but it is also likely to be highly inaccurate.
ALGO_ENUMERATE:
This algorithm uses the EnumerateStructureTransformation to perform ordering. This algo returns complete orderings up to a single unit cell size. It is more robust than the ALGO_COMPLETE, but requires Gus Hart’s enumlib to be installed.
ALGO_BEST_FIRST = 2
ALGO_COMPLETE = 1
ALGO_ENUMERATE = 3
ALGO_FAST = 0
apply_transformation(structure, return_ranked_list=False)[source]

Apply the transformation.

Parameters: structure – input structure return_ranked_list (bool) – Whether or not multiple structures are returned. If return_ranked_list is a number, that number of structures is returned. Depending on returned_ranked list, either a transformed structure or a list of dictionaries, where each dictionary is of the form {“structure” = …. , “other_arguments”} the key “transformation” is reserved for the transformation that was actually applied to the structure. This transformation is parsed by the alchemy classes for generating a more specific transformation history. Any other information will be stored in the transformation_parameters dictionary in the transmuted structure class.
best_first_ordering(structure, num_remove_dict)[source]
complete_ordering(structure, num_remove_dict)[source]
enumerate_ordering(structure)[source]
fast_ordering(structure, num_remove_dict, num_to_return=1)[source]

This method uses the matrix form of ewaldsum to calculate the ewald sums of the potential structures. This is on the order of 4 orders of magnitude faster when there are large numbers of permutations to consider. There are further optimizations possible (doing a smarter search of permutations for example), but this wont make a difference until the number of permutations is on the order of 30,000.

inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.

class RemoveSitesTransformation(indices_to_remove)[source]

Remove certain sites in a structure.

Parameters: indices_to_remove – List of indices to remove. E.g., [0, 1, 2]
apply_transformation(structure)[source]

Applies the transformation to a structure. Depending on whether a transformation is one-to-many, there may be an option to return a ranked list of structures.

Parameters: structure – input structure return_ranked_list – Boolean stating whether or not multiple structures are returned. If return_ranked_list is a number, that number of structures is returned. depending on returned_ranked list, either a transformed structure or a list of dictionaries, where each dictionary is of the form {‘structure’ = …. , ‘other_arguments’} the key ‘transformation’ is reserved for the transformation that was actually applied to the structure. This transformation is parsed by the alchemy classes for generating a more specific transformation history. Any other information will be stored in the transformation_parameters dictionary in the transmuted structure class.
inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.

class ReplaceSiteSpeciesTransformation(indices_species_map)[source]

This transformation substitutes certain sites with certain species.

Parameters: indices_species_map – A dict containing the species mapping in int-string pairs. E.g., { 1:”Na”} or {2:”Mn2+”}. Multiple substitutions can be done. Overloaded to accept sp_and_occu dictionary. E.g. {1: {“Ge”:0.75, “C”:0.25} }, which substitutes a single species with multiple species to generate a disordered structure.
apply_transformation(structure)[source]

Applies the transformation to a structure. Depending on whether a transformation is one-to-many, there may be an option to return a ranked list of structures.

Parameters: structure – input structure return_ranked_list – Boolean stating whether or not multiple structures are returned. If return_ranked_list is a number, that number of structures is returned. depending on returned_ranked list, either a transformed structure or a list of dictionaries, where each dictionary is of the form {‘structure’ = …. , ‘other_arguments’} the key ‘transformation’ is reserved for the transformation that was actually applied to the structure. This transformation is parsed by the alchemy classes for generating a more specific transformation history. Any other information will be stored in the transformation_parameters dictionary in the transmuted structure class.
inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.

class TranslateSitesTransformation(indices_to_move, translation_vector, vector_in_frac_coords=True)[source]

This class translates a set of sites by a certain vector.

Parameters: indices_to_move – The indices of the sites to move translation_vector – Vector to move the sites. If a list of list or numpy array of shape, (len(indices_to_move), 3), is provided then each translation vector is applied to the corresponding site in the indices_to_move. vector_in_frac_coords – Set to True if the translation vector is in fractional coordinates, and False if it is in cartesian coordinations. Defaults to True.
apply_transformation(structure)[source]

Applies the transformation to a structure. Depending on whether a transformation is one-to-many, there may be an option to return a ranked list of structures.

Parameters: structure – input structure return_ranked_list – Boolean stating whether or not multiple structures are returned. If return_ranked_list is a number, that number of structures is returned. depending on returned_ranked list, either a transformed structure or a list of dictionaries, where each dictionary is of the form {‘structure’ = …. , ‘other_arguments’} the key ‘transformation’ is reserved for the transformation that was actually applied to the structure. This transformation is parsed by the alchemy classes for generating a more specific transformation history. Any other information will be stored in the transformation_parameters dictionary in the transmuted structure class.
as_dict()[source]

Json-serializable dict representation.

inverse

Returns the inverse transformation if available. Otherwise, should return None.

is_one_to_many

Determines if a Transformation is a one-to-many transformation. If a Transformation is a one-to-many transformation, the apply_transformation method should have a keyword arg “return_ranked_list” which allows for the transformed structures to be returned as a ranked list.