pymatgen.transformations.site_transformations module¶

class
AddSitePropertyTransformation
(site_properties)[source]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
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 onetomany transformation. If a Transformation is a onetomany 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]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
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 onetomany, 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.
Returns: 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 onetomany transformation. If a Transformation is a onetomany 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]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
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 NPhard, 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 timeconsuming 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.
Returns: 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.

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 onetomany transformation. If a Transformation is a onetomany 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]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
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 onetomany, 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.
Returns: 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 onetomany transformation. If a Transformation is a onetomany 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]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
This transformation substitutes certain sites with certain species.
Parameters: indices_species_map – A dict containing the species mapping in intstring 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 onetomany, 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.
Returns: 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 onetomany transformation. If a Transformation is a onetomany 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]¶ Bases:
pymatgen.transformations.transformation_abc.AbstractTransformation
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 onetomany, 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.
Returns: 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 onetomany transformation. If a Transformation is a onetomany 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.