pymatgen.alchemy package — pymatgen 2025.6.14 documentation

# pymatgen.alchemy package

This package provides the modules for performing large scale transformations on a large number of structures.

## Submodules

## pymatgen.alchemy.filters module

This module defines filters for Transmuter object.

class AbstractStructureFilter

  Bases: `MSONable`, `ABC`

  Structures that return True when passed to the test() method are retained during transmutation. Those that return False are removed.

  abstractmethod test(structure: Structure | IStructure)

    Structures that return true are kept in the Transmuter object during filtering.

    Parameters:

      structure (Structure) – Input structure to test

    Returns:

      True if structure passes filter.

    Return type:

      bool

class ChargeBalanceFilter

  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)

    True if structure is neutral.

class ContainsSpecieFilter(species: SpeciesLike, strict_compare: bool = False, AND: bool = True, exclude: bool = False)

  Bases: `AbstractStructureFilter`

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

  Parameters:

    - species (list[SpeciesLike]) – 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() → dict

    Get MSONable dict.

  classmethod from_dict(dct: dict) → Self
    Parameters:

      dct (dict) – Dict representation.

    Returns:

      Filter

  test(structure: Structure | IStructure)

    True if structure does not contain specified species.

class RemoveDuplicatesFilter(structure_matcher: dict | StructureMatcher | None = None, symprec: float | None = None)

  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
    Parameters:

      structure (Structure) – Input structure to test.

    Returns:

      True if structure is not in list.

    Return type:

      bool

class RemoveExistingFilter(existing_structures: list[Structure], structure_matcher: dict | StructureMatcher | None = None, symprec: float | None = None)

  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[Structure]) – Existing structures to compare with.

    - structure_matcher (dict | StructureMatcher, optional) – Will be used for structure comparison.

    - symprec (float | None) – 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()

    Get MSONable dict.

  test(structure: Structure)

    True if structure is not in existing list.

class SpecieProximityFilter(specie_and_min_dist_dict)

  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()

    Get MSONable dict.

  classmethod from_dict(dct: dict) → Self
    Parameters:

      dct (dict) – Dict representation.

    Returns:

      SpecieProximityFilter

  test(structure: Structure)

    True if structure does not contain species within specified distances.

class SpeciesMaxDistFilter(sp1, sp2, max_dist)

  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)

    True if structure contains the two species but their distance is greater than max_dist.

## 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 | Mapping[str, Any]] | None = None, other_parameters: dict[str, Any] | None = None)

  Bases: `MSONable`

  Container for new structures that include history of transformations.

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

  Initialize a transformed structure from a structure.

  Parameters:

    - structure (Structure) – Input structure

    - transformations (list[Transformation]) – Transformations to apply.

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

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

  append_filter(structure_filter: AbstractStructureFilter) → None

    Add 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

    Append 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]

    Dict representation of the TransformedStructure.

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

    Extend 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) → Self

    Generate 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) → Self

    Create a TransformedStructure from a dict.

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

    Generate 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) → Self

    Create TransformedStructure from SNL.

    Parameters:

      snl (StructureNL) – Starting snl

    Returns:

      TransformedStructure

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

    Get 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

    Redo the last undone change in the TransformedStructure.

    Raises:

      IndexError – If already at the latest change.

  set_parameter(key: str, value: Any) → TransformedStructure

    Set a parameter.

    Parameters:

      - key (str) – The string key.

      - value (Any) – The value.

    Returns:

      TransformedStructure

  property structures: list[Structure]

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

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

    Generate a StructureNL from TransformedStructure.

    Parameters:

      - authors (List[str]) – 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

    Undo the last change in the TransformedStructure.

    Raises:

      IndexError – If already at the oldest change.

  property was_modified: bool

    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

    Write 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)

  Bases: `StandardTransmuter`

  Generate a Transmuter from a CIF string, possibly containing multiple structures.

  Generate 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) → Self

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

    Parameters:

      - filenames (list[str]) – The CIF file paths.

      - 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)

  Bases: `StandardTransmuter`

  Generate a transmuter from a sequence of POSCARs.

  Parameters:

    - poscar_string (list[str]) – 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.

  classmethod from_filenames(poscar_filenames, transformations=None, extend_collection=False) → StandardTransmuter

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

    Parameters:

      - poscar_filenames (list[str]) – The POSCAR file paths.

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

      - extend_collection – Same meaning as in __init__.

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

  Bases: `object`

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

  transformed_structures

    All transformed structures.

    Type:

      list[Structure]

  Initialize 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)

    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) → list[bool]

    Append 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:

      Each list item is True if the transformation altered the structure

        with the corresponding index.

    Return type:

      list[bool]

  append_transformed_structures(trafo_structs_or_transmuter)

    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: AbstractStructureFilter)

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

    Parameters:

      structure_filter – StructureFilter to apply.

  extend_transformations(transformations)

    Extend a sequence of transformations to the TransformedStructure.

    Parameters:

      transformations – Sequence of Transformations

  classmethod from_structures(structures, transformations=None, extend_collection=0) → Self

    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() → None

    Redo the last undone transformation in the TransformedStructure.

    Raises:

      IndexError if already at the latest change. –

  set_parameter(key, value)

    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() → None

    Undo the last transformation in the TransformedStructure.

    Raises:

      IndexError if already at the oldest change. –

  write_vasp_input(**kwargs)

    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)

  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) – Pass True to output a CIF as well. CIF files are generally better supported in visualization programs.

    - **kwargs – Any kwargs supported by vasp_input_set.