pymatgen.alchemy package

Submodules

pymatgen.alchemy.filters module

This module defines filters for Transmuter object.

class AbstractStructureFilter[source]

Bases: MSONable, ABC

AbstractStructureFilter that defines an API to perform testing of Structures. Structures that return True to a test are retained during transmutation while those that return False are removed.

abstract test(structure: Structure)[source]

Method to execute the test.

Parameters:

structure (Structure) – Input structure to test

Returns:

Structures that return true are kept in the Transmuter

object during filtering.

Return type:

bool

class ChargeBalanceFilter[source]

Bases: AbstractStructureFilter

This filter removes structures that are not charge balanced from the transmuter. This only works if the structure is oxidation state decorated, as structures with only elemental sites are automatically assumed to have net charge of 0.

No args required.

test(structure: Structure)[source]

Method to execute the test.

Parameters:

structure (Structure) – Input structure to test

Returns:

True if structure is neutral.

Return type:

bool

class ContainsSpecieFilter(species, strict_compare=False, AND=True, exclude=False)[source]

Bases: AbstractStructureFilter

Filter for structures containing certain elements or species. By default compares by atomic number.

Parameters:

• species ([Species/Element]) – list of species to look for

• AND – whether all species must be present to pass (or fail) filter.

• strict_compare – if true, compares objects by specie or element object if false, compares atomic number

• exclude – If true, returns false for any structures with the specie (excludes them from the Transmuter).

as_dict()[source]

Returns: MSONable dict.

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

Filter

test(structure: Structure)[source]

Method to execute the test.

Returns:

True if structure does not contain specified species.

Return type:

bool

class RemoveDuplicatesFilter(structure_matcher: dict | StructureMatcher | None = None, symprec: float | None = None)[source]

Bases: AbstractStructureFilter

This filter removes exact duplicate structures from the transmuter.

Remove duplicate structures based on the structure matcher and symmetry (if symprec is given).

Parameters:

• structure_matcher (dict | StructureMatcher, optional) – Provides a structure matcher to be used for structure comparison.

• symprec (float, optional) – The precision in the symmetry finder algorithm if None ( default value), no symmetry check is performed and only the structure matcher is used. A recommended value is 1e-5.

test(structure: Structure) → bool[source]

Parameters:

structure (Structure) – Input structure to test.

Returns:

True if structure is not in list.

Return type:

bool

class RemoveExistingFilter(existing_structures, structure_matcher=None, symprec=None)[source]

Bases: AbstractStructureFilter

This filter removes structures existing in a given list from the transmuter.

Remove existing structures based on the structure matcher and symmetry (if symprec is given).

Parameters:

• existing_structures – List of existing structures to compare with

• structure_matcher – Provides a structure matcher to be used for structure comparison.

• symprec – The precision in the symmetry finder algorithm if None ( default value), no symmetry check is performed and only the structure matcher is used. A recommended value is 1e-5.

as_dict()[source]

Returns: MSONable dict.

test(structure: Structure)[source]

Method to execute the test.

Parameters:

structure (Structure) – Input structure to test

Returns:

True if structure is not in existing list.

Return type:

bool

class SpecieProximityFilter(specie_and_min_dist_dict)[source]

Bases: AbstractStructureFilter

This filter removes structures that have certain species that are too close together.

Parameters:

specie_and_min_dist_dict (dict) – A species string to float mapping. For example, {“Na+”: 1} means that all Na+ ions must be at least 1 Angstrom away from each other. Multiple species criteria can be applied. Note that the testing is done based on the actual object . If you have a structure with Element, you must use {“Na”:1} instead to filter based on Element and not Species.

as_dict()[source]

Returns: MSONable dict.

classmethod from_dict(dct: dict) → Self[source]

Parameters:

dct (dict) – Dict representation.

Returns:

Filter

test(structure: Structure)[source]

Method to execute the test.

Parameters:

structure (Structure) – Input structure to test

Returns:

True if structure does not contain species within specified distances.

Return type:

bool

class SpeciesMaxDistFilter(sp1, sp2, max_dist)[source]

Bases: AbstractStructureFilter

This filter removes structures that do have two particular species that are not nearest neighbors by a predefined max_dist. For instance, if you are analyzing Li battery materials, you would expect that each Li+ would be nearest neighbor to lower oxidation state transition metal for electrostatic reasons. This only works if the structure is oxidation state decorated, as structures with only elemental sites are automatically assumed to have net charge of 0.

Parameters:

• sp1 (Species) – First specie

• sp2 (Species) – Second specie

• max_dist (float) – Maximum distance between species.

test(structure: Structure)[source]

Method to execute the test.

Parameters:

structure (Structure) – Input structure to test

Returns:

True if structure does not contain the two species are distances

greater than max_dist.

Return type:

bool

pymatgen.alchemy.materials module

This module provides various representations of transformed structures. A TransformedStructure is a structure that has been modified by undergoing a series of transformations.

class TransformedStructure(structure: Structure, transformations: AbstractTransformation | Sequence[AbstractTransformation] | None = None, history: list[AbstractTransformation | dict[str, Any]] | None = None, other_parameters: dict[str, Any] | None = None)[source]

Bases: MSONable

Container object for new structures that include history of transformations.

Each transformed structure is made up of a sequence of structures with associated transformation history.

Initializes a transformed structure from a structure.

Parameters:

• structure (Structure) – Input structure

• transformations (list[Transformation]) – List of transformations to apply.

• history (list[Transformation]) – Previous history.

• other_parameters (dict) – Additional parameters to be added.

append_filter(structure_filter: AbstractStructureFilter) → None[source]

Adds a filter.

Parameters:

structure_filter (StructureFilter) – A filter implementing the AbstractStructureFilter API. Tells transmuter what structures to retain.

append_transformation(transformation, return_alternatives: bool = False, clear_redo: bool = True) → list[TransformedStructure] | None[source]

Appends a transformation to the TransformedStructure.

Parameters:

• transformation – Transformation to append

• return_alternatives – Whether to return alternative TransformedStructures for one-to-many transformations. return_alternatives can be a number, which stipulates the total number of structures to return.

• clear_redo – Boolean indicating whether to clear the redo list. By default, this is True, meaning any appends clears the history of undoing. However, when using append_transformation to do a redo, the redo list should not be cleared to allow multiple redos.

as_dict() → dict[str, Any][source]

Dict representation of the TransformedStructure.

extend_transformations(transformations: list[AbstractTransformation], return_alternatives: bool = False) → None[source]

Extends a sequence of transformations to the TransformedStructure.

Parameters:

• transformations – Sequence of Transformations

• return_alternatives – Whether to return alternative TransformedStructures for one-to-many transformations. return_alternatives can be a number, which stipulates the total number of structures to return.

classmethod from_cif_str(cif_string: str, transformations: list[AbstractTransformation] | None = None, primitive: bool = True, occupancy_tolerance: float = 1.0) → TransformedStructure[source]

Generates TransformedStructure from a cif string.

Parameters:

• cif_string (str) – Input cif string. Should contain only one structure. For CIFs containing multiple structures, please use CifTransmuter.

• transformations (list[Transformation]) – Sequence of transformations to be applied to the input structure.

• primitive (bool) – Option to set if the primitive cell should be extracted. Defaults to True. However, there are certain instances where you might want to use a non-primitive cell, e.g., if you are trying to generate all possible orderings of partial removals or order a disordered structure. Defaults to True.

• occupancy_tolerance (float) – If total occupancy of a site is between 1 and occupancy_tolerance, the occupancies will be scaled down to 1.

Returns:

TransformedStructure

classmethod from_dict(dct: dict) → TransformedStructure[source]

Creates a TransformedStructure from a dict.

classmethod from_poscar_str(poscar_string: str, transformations: list[AbstractTransformation] | None = None) → TransformedStructure[source]

Generates TransformedStructure from a poscar string.

Parameters:

• poscar_string (str) – Input POSCAR string.

• transformations (list[Transformation]) – Sequence of transformations to be applied to the input structure.

classmethod from_snl(snl: StructureNL) → TransformedStructure[source]

Create TransformedStructure from SNL.

Parameters:

snl (StructureNL) – Starting snl

Returns:

TransformedStructure

get_vasp_input(vasp_input_set: type[~pymatgen.io.vasp.sets.VaspInputSet] = <class 'pymatgen.io.vasp.sets.MPRelaxSet'>, **kwargs) → dict[str, Any][source]

Returns VASP input as a dict of VASP objects.

Parameters:

• vasp_input_set (VaspInputSet) – input set to create VASP input files from structures

• **kwargs – All keyword args supported by the VASP input set.

redo_next_change() → None[source]

Redo the last undone change in the TransformedStructure.

Raises:

IndexError – If already at the latest change.

set_parameter(key: str, value: Any) → TransformedStructure[source]

Sets a parameter.

Parameters:

• key (str) – The string key.

• value (Any) – The value.

Returns:

TransformedStructure

property structures: list[Structure][source]

Copy of all structures in the TransformedStructure. A structure is stored after every single transformation.

to_snl(authors: list[str], **kwargs) → StructureNL[source]

Generate a StructureNL from TransformedStructure.

Parameters:

• authors (List[str]) – List of authors contributing to the generated StructureNL.

• **kwargs (Any) – All kwargs supported by StructureNL.

Returns:

The generated StructureNL object.

Return type:

StructureNL

undo_last_change() → None[source]

Undo the last change in the TransformedStructure.

Raises:

IndexError – If already at the oldest change.

property was_modified: bool[source]

Boolean describing whether the last transformation on the structure made any alterations to it one example of when this would return false is in the case of performing a substitution transformation on the structure when the specie to replace isn’t in the structure.

write_vasp_input(vasp_input_set: type[~pymatgen.io.vasp.sets.VaspInputSet] = <class 'pymatgen.io.vasp.sets.MPRelaxSet'>, output_dir: str = '.', create_directory: bool = True, **kwargs) → None[source]

Writes VASP input to an output_dir.

Parameters:

• vasp_input_set – pymatgen.io.vasp.sets.VaspInputSet like object that creates vasp input files from structures.

• output_dir – Directory to output files

• create_directory – Create the directory if not present. Defaults to True.

• **kwargs – All keyword args supported by the VASP input set.

pymatgen.alchemy.transmuters module

This module implements various transmuter classes. Transmuters are essentially classes that generate TransformedStructures from various data sources. They enable the high-throughput generation of new structures and input files.

It also includes the helper function, batch_write_vasp_input to generate an entire directory of vasp input files for running.

class CifTransmuter(cif_string, transformations=None, primitive=True, extend_collection=False)[source]

Bases: StandardTransmuter

Generates a Transmuter from a cif string, possibly containing multiple structures.

Generates a Transmuter from a cif string, possibly containing multiple structures.

Parameters:

• cif_string – A string containing a cif or a series of CIFs

• transformations – New transformations to be applied to all structures

• primitive – Whether to generate the primitive cell from the cif.

• extend_collection – Whether to use more than one output structure from one-to-many transformations. extend_collection can be a number, which determines the maximum branching for each transformation.

classmethod from_filenames(filenames, transformations=None, primitive=True, extend_collection=False)[source]

Generates a TransformedStructureCollection from a cif, possibly containing multiple structures.

Parameters:

• filenames – List of strings of the cif files

• transformations – New transformations to be applied to all structures

• primitive – Same meaning as in __init__.

• extend_collection – Same meaning as in __init__.

class PoscarTransmuter(poscar_string, transformations=None, extend_collection=False)[source]

Bases: StandardTransmuter

Generates a transmuter from a sequence of POSCARs.

Parameters:

• poscar_string – List of POSCAR strings

• transformations – New transformations to be applied to all structures.

• extend_collection – Whether to use more than one output structure from one-to-many transformations.

static from_filenames(poscar_filenames, transformations=None, extend_collection=False)[source]

Convenient constructor to generates a POSCAR transmuter from a list of POSCAR filenames.

Parameters:

• poscar_filenames – List of POSCAR filenames

• transformations – New transformations to be applied to all structures.

• extend_collection – Same meaning as in __init__.

class StandardTransmuter(transformed_structures, transformations=None, extend_collection: int = 0, ncores: int | None = None)[source]

Bases: object

An example of a Transmuter object, which performs a sequence of transformations on many structures to generate TransformedStructures.

transformed_structures[source]

List of all transformed structures.

Type:

list[Structure]

Initializes a transmuter from an initial list of pymatgen.alchemy.materials.TransformedStructure.

Parameters:

• transformed_structures ([TransformedStructure]) – Input transformed structures

• transformations ([Transformations]) – New transformations to be applied to all structures.

• extend_collection (int) – Whether to use more than one output structure from one-to-many transformations. extend_collection can be an int, which determines the maximum branching for each transformation.

• ncores (int) – Number of cores to use for applying transformations. Uses multiprocessing.Pool. Default is None, which implies serial.

add_tags(tags)[source]

Add tags for the structures generated by the transmuter.

Parameters:

tags – A sequence of tags. Note that this should be a sequence of strings, e.g., [“My awesome structures”, “Project X”].

append_transformation(transformation, extend_collection=False, clear_redo=True)[source]

Appends a transformation to all TransformedStructures.

Parameters:

• transformation – Transformation to append

• extend_collection – Whether to use more than one output structure from one-to-many transformations. extend_collection can be a number, which determines the maximum branching for each transformation.

• clear_redo (bool) – Whether to clear the redo list. By default, this is True, meaning any appends clears the history of undoing. However, when using append_transformation to do a redo, the redo list should not be cleared to allow multiple redos.

Returns:

corresponding to initial transformed structures each boolean

describes whether the transformation altered the structure

Return type:

list[bool]

append_transformed_structures(trafo_structs_or_transmuter)[source]

Method is overloaded to accept either a list of transformed structures or transmuter, it which case it appends the second transmuter”s structures.

Parameters:

trafo_structs_or_transmuter – A list of transformed structures or a transmuter.

apply_filter(structure_filter)[source]

Applies a structure_filter to the list of TransformedStructures in the transmuter.

Parameters:

structure_filter – StructureFilter to apply.

extend_transformations(transformations)[source]

Extends a sequence of transformations to the TransformedStructure.

Parameters:

transformations – Sequence of Transformations

classmethod from_structures(structures, transformations=None, extend_collection=0)[source]

Alternative constructor from structures rather than TransformedStructures.

Parameters:

• structures – Sequence of structures

• transformations – New transformations to be applied to all structures

• extend_collection – Whether to use more than one output structure from one-to-many transformations. extend_collection can be a number, which determines the maximum branching for each transformation.

Returns:

StandardTransmuter

redo_next_change()[source]

Redo the last undone transformation in the TransformedStructure.

Raises:

IndexError if already at the latest change. –

set_parameter(key, value)[source]

Add parameters to the transmuter. Additional parameters are stored in the as_dict() output.

Parameters:

• key – The key for the parameter.

• value – The value for the parameter.

undo_last_change()[source]

Undo the last transformation in the TransformedStructure.

Raises:

IndexError if already at the oldest change. –

write_vasp_input(**kwargs)[source]

Batch write vasp input for a sequence of transformed structures to output_dir, following the format output_dir/{formula}_{number}.

Parameters:

kwargs – All kwargs supported by batch_write_vasp_input.

batch_write_vasp_input(transformed_structures: Sequence[TransformedStructure], vasp_input_set: type[VaspInputSet] = <class 'pymatgen.io.vasp.sets.MPRelaxSet'>, output_dir: str = '.', create_directory: bool = True, subfolder: Callable[[TransformedStructure], str] | None = None, include_cif: bool = False, **kwargs)[source]

Batch write vasp input for a sequence of transformed structures to output_dir, following the format output_dir/{group}/{formula}_{number}.

Parameters:

• transformed_structures – Sequence of TransformedStructures.

• vasp_input_set – pymatgen.io.vasp.sets.VaspInputSet to creates vasp input files from structures.

• output_dir – Directory to output files

• create_directory (bool) – Create the directory if not present. Defaults to True.

• subfolder – Function to create subdirectory name from transformed_structure. e.g., lambda x: x.other_parameters[“tags”][0] to use the first tag.

• include_cif (bool) – Boolean indication whether to output a CIF as well. CIF files are generally better supported in visualization programs.

• **kwargs – Any kwargs supported by vasp_input_set.