transformations Package

transformations Package

The transformations package defines various transformations that can be applied on structures, i.e., converting one structure to another.

advanced_transformations Module

This module implements more advanced transformations.

class ChargeBalanceTransformation(charge_balance_sp)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This is a transformation that disorders a structure to make it charge balanced, given an oxidation state-decorated structure.

Args:

charge_balance_sp

specie to add or remove. Currently only removal is supported

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class EnumerateStructureTransformation(min_cell_size=1, max_cell_size=1, symm_prec=0.1, refine_structure=False)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

Order a disordered structure using enumlib. For complete orderings, this generally produces fewer structures that the OrderDisorderedStructure transformation, and at a much faster speed.

Args:

min_cell_size:

The minimum cell size wanted. Must be an int. Defaults to 1.

max_cell_size:

The maximum cell size wanted. Must be an int. Defaults to 1.

symm_prec:

Tolerance to use for symmetry.

refine_structure:

This parameter has the same meaning as in enumlib_caller. If you are starting from a structure that has been relaxed via some electronic structure code, it is usually much better to start with symmetry determination and then obtain a refined structure. The refined structure have cell parameters and atomic positions shifted to the expected symmetry positions, which makes it much less sensitive precision issues in enumlib. If you are already starting from an experimental cif, refinment should have already been done and it is not necessary. Defaults to False.

apply_transformation(structure, return_ranked_list=False)

Return either a single ordered structure or a sequence of all ordered structures.

Args:

structure:

Structure to order.

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 list of ordered structures is ranked by ewald energy / atom, if the input structure is an oxidation state decorated structure. Otherwise, it is ranked by number of sites, with smallest number of sites first.

inverse

is_one_to_many

to_dict

class MultipleSubstitutionTransformation(sp_to_replace, r_fraction, substitution_dict, charge_balance_species=None, order=True)

Bases: object

Performs multiple substitutions on a structure. For example, can do a fractional replacement of Ge in LiGePS with a list of species, creating one structure for each substitution. Ordering is done using a dummy element so only one ordering must be done per substitution oxidation state. Charge balancing of the structure is optionally performed.

Note

There are no checks to make sure that removal fractions are possible and rounding may occur. Currently charge balancing only works for removal of species.

Performs multiple fractional substitutions on a transmuter.

Args:

sp_to_replace

species to be replaced

r_fraction

fraction of that specie to replace

substitution_dict

dictionary of the format {2: [“Mg”, “Ti”, “V”, “As”, “Cr”, “Ta”, “N”, “Nb”], 3: [“Ru”, “Fe”, “Co”, “Ce”, “As”, “Cr”, “Ta”, “N”, “Nb”], 4: [“Ru”, “V”, “Cr”, “Ta”, “N”, “Nb”], 5: [“Ru”, “W”, “Mn”] } The number is the charge used for each of the list of elements (an element can be present in multiple lists)

charge_balance_species:

If specified, will balance the charge on the structure using that specie.

apply_transformation(structure, return_ranked_list=False)

inverse

is_one_to_many

to_dict

class SubstitutionPredictorTransformation(threshold=0.01, **kwargs)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation takes a structure and uses the structure prediction module to find likely site substitutions.

Args:

kwargs:

args for SubstitutionProbability class lambda_table, alpha

apply_transformation(structure, return_ranked_list=False)

inverse

is_one_to_many

to_dict

class SuperTransformation(transformations)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This is a transformation that is inherently one-to-many. It is constructed from a list of transformations and returns one structure for each transformation. The primary use for this class is extending a transmuter object.

Args:

transformations:

list of transformations to apply to a structure. One transformation is applied to each output structure.

apply_transformation(structure, return_ranked_list=False)

inverse

is_one_to_many

to_dict

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 InsertSitesTransformation(species, coords, coords_are_cartesian=False, validate_proximity=True)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation substitutes certain sites with certain species.

Args:

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:

Set to True if coords are given in cartesian coords. Defaults to False.

validate_proximity:

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)

inverse

is_one_to_many

to_dict

class PartialRemoveSitesTransformation(indices, fractions, algo=1)

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.

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.

Args:

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

ALGO_COMPLETE = 1

ALGO_ENUMERATE = 3

ALGO_FAST = 0

apply_transformation(structure, return_ranked_list=False)

Apply the transformation.

Args:

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.

best_first_ordering(structure, num_remove_dict)

complete_ordering(structure, num_remove_dict)

enumerate_ordering(structure)

fast_ordering(structure, num_remove_dict, num_to_return=1)

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

to_dict

class RemoveSitesTransformation(indices_to_remove)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

Remove certain sites in a structure.

Args:

indices_to_remove:

List of indices to remove. E.g., [0, 1, 2]

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class ReplaceSiteSpeciesTransformation(indices_species_map)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation substitutes certain sites with certain species.

Args:

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)

inverse

is_one_to_many

to_dict

class TranslateSitesTransformation(indices_to_move, translation_vector, vector_in_frac_coords=True)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

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

Args:

indices_to_move:

The indices of the sites to move

translation_vector:

Vector to move the sites.

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)

inverse

is_one_to_many

to_dict

standard_transformations Module

This module defines standard transformations which transforms a structure into another structure. Standard transformations operate in a structure-wide manner, rather than site-specific manner. All transformations should inherit the AbstractTransformation ABC.

class AutoOxiStateDecorationTransformation(symm_tol=0.1, max_radius=4, max_permutations=100000, distance_scale_factor=1.015)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation automatically decorates a structure with oxidation states using a bond valence approach.

Args:

symm_tol:

Symmetry tolerance used to determine which sites are symmetrically equivalent. Set to 0 to turn off symmetry.

max_radius:

Maximum radius in Angstrom used to find nearest neighbors.

max_permutations:

The maximum number of permutations of oxidation states to test.

distance_scale_factor:

A scale factor to be applied. This is useful for scaling distances, esp in the case of calculation-relaxed structures which may tend to under (GGA) or over bind (LDA). The default of 1.015 works for GGA. For experimental structure, set this to 1.

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class IdentityTransformation

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This is a demo transformation which does nothing, i.e. just returns a copy of the same structure.

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class OrderDisorderedStructureTransformation(algo=0, symmetrized_structures=False)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

Order a disordered structure. The disordered structure must be oxidation state decorated for ewald sum to be computed. No attempt is made to perform symmetry determination to reduce the number of combinations.

Hence, attempting to performing ordering on a large number of disordered sites may be extremely expensive. The time scales approximately with the number of possible combinations. The algorithm can currently compute approximately 5,000,000 permutations per minute.

Also, simple rounding of the occupancies are performed, with no attempt made to achieve a target composition. This is usually not a problem for most ordering problems, but there can be times where rounding errors may result in structures that do not have the desired composition. This second step will be implemented in the next iteration of the code.

If multiple fractions for a single species are found for different sites, these will be treated separately if the difference is above a threshold tolerance. currently this is .1

For example, if a fraction of .25 Li is on sites 0,1,2,3 and .5 on sites 4, 5, 6, 7 1 site from [0,1,2,3] will be filled and 2 sites from [4,5,6,7] will be filled, even though a lower energy combination might be found by putting all lithium in sites [4,5,6,7].

USE WITH CARE.

Args:

num_structures:

maximum number of structures to return

mev_cutoff:

maximum mev per atom above the minimum energy ordering for a structure to be returned

symmetrized_structures:

Boolean stating whether the input structures are instances of SymmetrizedStructure, and that their symmetry should be used for the grouping of sites.

ALGO_BEST_FIRST = 2

ALGO_COMPLETE = 1

ALGO_FAST = 0

apply_transformation(structure, return_ranked_list=False)

For this transformation, the apply_transformation method will return only the ordered structure with the lowest Ewald energy, to be consistent with the method signature of the other transformations. However, all structures are stored in the all_structures attribute in the transformation object for easy access.

Args:

structure:

Oxidation state decorated disordered structure to order

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

is_one_to_many

lowest_energy_structure

to_dict

class OxidationStateDecorationTransformation(oxidation_states)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation decorates a structure with oxidation states.

Args:

oxidation_states

Oxidation states supplied as a dict, e.g., {“Li”:1, “O”:-2}

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class OxidationStateRemovalTransformation

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation removes oxidation states from a structure

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class PartialRemoveSpecieTransformation(specie_to_remove, fraction_to_remove, algo=0)

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.

Given that the solution to selecting the right removals is NP-hard, there are several algorithms provided with varying degrees of accuracy and speed. Please see pymatgen.transformations.site_transformations.PartialRemoveSitesTransformation.

Args:

specie_to_remove:

Specie to remove. Must have oxidation state E.g., “Li1+”

fraction_to_remove:

Fraction of specie to remove. E.g., 0.5

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

ALGO_COMPLETE = 1

ALGO_ENUMERATE = 3

ALGO_FAST = 0

apply_transformation(structure, return_ranked_list=False)

Apply the transformation.

Args:

structure:

input structure

return_ranked_list:

Boolean stating whether or not multiple structures are returned. If return_ranked_list is an int, 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

is_one_to_many

to_dict

class PerturbStructureTransformation(amplitude=0.01)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation perturbs a structure by a specified distance in random directions. Used for breaking symmetries.

Args:

amplitude:

Amplitude of perturbation in angstroms. All sites will be perturbed by exactly that amplitude in a random direction.

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class PrimitiveCellTransformation(tolerance=0.5)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This class finds the primitive cell of the input structure. It returns a structure that is not necessarily orthogonalized Author: Will Richards

Args:

tolerance:

Tolerance for each coordinate of a particular site. For example, [0.5, 0, 0.5] in cartesian coordinates will be considered to be on the same coordinates as [0, 0, 0] for a tolerance of 0.5. Defaults to 0.5.

apply_transformation(structure)

Returns most primitive cell for structure.

Args:

structure:

A structure

Returns:

The most primitive structure found. The returned structure is guaranteed to have len(new structure) <= len(structure).

inverse

is_one_to_many

to_dict

class RemoveSpeciesTransformation(species_to_remove)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

Remove all occurrences of some species from a structure.

Args:

species_to_remove:

List of species to remove. E.g., [“Li”, “Mn”]

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class RotationTransformation(axis, angle, angle_in_radians=False)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

The RotationTransformation applies a rotation to a structure.

Args:

axis:

Axis of rotation, e.g., [1, 0, 0]

angle:

Angle to rotate

angle_in_radians:

Set to True if angle is supplied in radians. Else degrees are assumed.

apply_transformation(structure)

inverse

is_one_to_many

to_dict

class SubstitutionTransformation(species_map)

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

This transformation substitutes species for one another.

Args:

species_map:

A dict containing the species mapping in string-string pairs. E.g., { “Li”:”Na”} or {“Fe2+”,”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)

inverse

is_one_to_many

to_dict

class SupercellTransformation(scaling_matrix=((1, 0, 0), (0, 1, 0), (0, 0, 1)))

Bases: pymatgen.transformations.transformation_abc.AbstractTransformation

The RotationTransformation applies a rotation to a structure.

Args:

scaling_matrix:

a matrix of transforming the lattice vectors. Defaults to the identity matrix. Has to be all integers. e.g., [[2,1,0],[0,3,0],[0,0,1]] generates a new structure with lattice vectors a” = 2a + b, b” = 3b, c” = c where a, b, and c are the lattice vectors of the original structure.

apply_transformation(structure)

static from_scaling_factors(scale_a=1, scale_b=1, scale_c=1)

Convenience method to get a SupercellTransformation from a simple series of three numbers for scaling each lattice vector. Equivalent to calling the normal with [[scale_a, 0, 0], [0, scale_b, 0], [0, 0, scale_c]]

Args:

scale_a:

Scaling factor for lattice direction a. Defaults to 1.

scale_b:

Scaling factor for lattice direction b. Defaults to 1.

scale_c:

Scaling factor for lattice direction c. Defaults to 1.

inverse

is_one_to_many

to_dict

transformation_abc Module

Defines an abstract base class contract for Transformation object.

class AbstractTransformation

Bases: pymatgen.serializers.json_coders.MSONable

Abstract transformation class.

apply_transformation(structure)

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.

Args:

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.

classmethod from_dict(d)

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.

use_multiprocessing

Indicates whether the transformation can be applied by a subprocessing pool. This should be overridden to return True for transformations that the transmuter can parallelize.