# pymatgen.transformations.site_transformations module¶

This module defines site transformations which transforms a structure into another structure. Site transformations differ from standard transformations in that they operate in a site-specific manner. All transformations should inherit the AbstractTransformation ABC.

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.

Arg:
structure (Structure): A structurally similar structure in

regards to crystal and site positions.

Returns

Returns a copy of structure with sites properties added.

property inverse[source]

None

Type

Return

property is_one_to_many[source]

False

Type

Return

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]

Apply the transformation.

Arg:
structure (Structure): A structurally similar structure in

regards to crystal and site positions.

Returns

Returns a copy of structure with sites inserted.

property inverse[source]

None

Type

Return

property is_one_to_many[source]

False

Type

Return

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.

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.

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.

ALGO_BEST_FIRST = 2[source]
ALGO_COMPLETE = 1[source]
ALGO_ENUMERATE = 3[source]
ALGO_FAST = 0[source]
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.

property inverse[source]

None

Type

Return

property is_one_to_many[source]

True

Type

Return

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]

Apply the transformation.

Arg:
structure (Structure): A structurally similar structure in

regards to crystal and site positions.

Returns

Returns a copy of structure with sites removed.

property inverse[source]

None

Type

Return

property is_one_to_many[source]

False

Type

Return

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]

Apply the transformation.

Arg:
structure (Structure): A structurally similar structure in

regards to crystal and site positions.

Returns

Returns a copy of structure with sites replaced.

property inverse[source]

None

Type

Return

property is_one_to_many[source]

False

Type

Return

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]

Apply the transformation.

Arg:
structure (Structure): A structurally similar structure in

regards to crystal and site positions.

Returns

Returns a copy of structure with sites translated.

as_dict()[source]

Json-serializable dict representation.

property inverse[source]

Returns: TranslateSitesTranformation with the reverse translation.

property is_one_to_many[source]

False

Type

Return