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
is_one_to_many
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]
inverse
is_one_to_many
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 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.
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.

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
is_one_to_many
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]
inverse
is_one_to_many
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 int-string pairs. E.g., { 1:”Na”} or {2:”Mn2+”}. Multiple substitutions can be done. Overloaded to accept sp_and_occu dictionary. E.g. {“Si: {“Ge”:0.75, “C”:0.25} }, which substitutes a single species with multiple species to generate a disordered structure.
apply_transformation(structure)[source]
inverse
is_one_to_many
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]
as_dict()[source]

Json-serializable dict representation.

inverse
is_one_to_many