alchemy Package

alchemy Package

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

filters Module

This module defines filters for Transmuter object.

class AbstractStructureFilter

Bases: pymatgen.serializers.json_coders.MSONable

Abstract structure filter class.

classmethod from_dict(d)

test(structure)

Returns a boolean for any structure. Structures that return true are kept in the Transmuter object during filtering.

class ChargeBalanceFilter

Bases: pymatgen.alchemy.filters.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.

test(structure)

to_dict

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

Bases: pymatgen.alchemy.filters.AbstractStructureFilter

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

Args:

species:

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)

test(structure)

to_dict

class RemoveDuplicatesFilter(structure_matcher=<pymatgen.analysis.structure_matcher.StructureMatcher object at 0x1040eb6d0>, symprec=None)

Bases: pymatgen.alchemy.filters.AbstractStructureFilter

This filter removes exact duplicate structures from the transmuter.

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

Args:

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

test(structure)

to_dict

class SpecieProximityFilter(specie_and_min_dist_dict)

Bases: pymatgen.alchemy.filters.AbstractStructureFilter

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

Args:

specie_and_min_dist_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 Specie.

test(structure)

to_dict

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, transformations=None, history=None, other_parameters=None)

Bases: pymatgen.serializers.json_coders.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.

append_filter(structure_filter)

Adds a transformation parameter to the last transformation.

append_transformation(transformation, return_alternatives=False, clear_redo=True)

Appends a transformation to the TransformedStructure.

Args:

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.

extend_transformations(transformations)

Extends a sequence of transformations to the TransformedStructure.

Args:

transformations:

Sequence of Transformations

static from_cif_string(cif_string, transformations=None, primitive=True, occupancy_tolerance=1.0)

Generates TransformedStructure from a cif string.

Args:

cif_string:

Input cif string. Should contain only one structure. For cifs containing multiple structures, please use CifTransmuter.

transformations:

Sequence of transformations to be applied to the input structure.

primitive:

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.

occupancy_tolerance:

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

classmethod from_dict(d)

Creates a TransformedStructure from a dict.

static from_poscar_string(poscar_string, transformations=None)

Generates TransformedStructure from a poscar string.

Args:

poscar_string:

Input POSCAR string.

transformations:

Sequence of transformations to be applied to the input structure.

classmethod from_snl(snl)

Args:

snl:

Starting snl

copy_metadata:

update the authors, projects, references, and remarks in the last history node with the metadata at the root of the SNL object

copy_data:

copy the contents of snl.data into the last history node

get_vasp_input(vasp_input_set, generate_potcar=True)

Returns VASP input as a dict of vaspio objects.

Args:

vasp_input_set:

pymatgen.io.vaspio_set.VaspInputSet like object that creates vasp input files from structures

generate_potcar:

Set to False to generate a POTCAR.spec file instead of a POTCAR, which contains the POTCAR labels but not the actual POTCAR. Defaults to True.

redo_next_change()

Redo the last undone change in the TransformedStructure.

Raises:

IndexError if already at the latest change.

set_parameter(key, value)

structures

Returns a copy of all structures in the TransformedStructure. A structure is stored after every single transformation.

to_dict

Returns a dict representation of the TransformedStructure.

to_snl(authors, projects=None, references='', remarks=None, data=None, created_at=None)

undo_last_change()

Undo the last change in the TransformedStructure.

Raises:

IndexError if already at the oldest change.

was_modified

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, output_dir, create_directory=True)

Writes VASP input to an output_dir.

Args:

vasp_input_set:

pymatgen.io.vaspio_set.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.

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: pymatgen.alchemy.transmuters.StandardTransmuter

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

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

Args:

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.

static from_filenames(filenames, transformations=None, primitive=True, extend_collection=False)

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

Args:

filenames:

List of strings of the cif files

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.

class PoscarTransmuter(poscar_string, transformations=None, extend_collection=False)

Bases: pymatgen.alchemy.transmuters.StandardTransmuter

Generates a transmuter from a sequence of POSCARs.

Args:

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)

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

Args:

poscar_filenames:

List of POSCAR filenames

transformations:

New transformations to be applied to all structures.

extend_collection:

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

class StandardTransmuter(transformed_structures, transformations=None, extend_collection=0, ncores=None)

Bases: object

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

Args:

transformed_structures:

Input transformed 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.

ncores:

Number of cores to use for applying transformations. Uses multiprocessing.Pool

add_tags(tags)

Add tags for the structures generated by the transmuter.

Args:

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)

Appends a transformation to all TransformedStructures.

Args:

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:

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.

Returns:

List of booleans corresponding to initial transformed structures each boolean describes whether the transformation altered the structure

append_transformed_structures(tstructs_or_transmuter)

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

Args:

tstructs_or_transmuter:

A list of transformed structures or a transmuter.

apply_filter(structure_filter)

Applies a structure_filter to the list of TransformedStructures in the transmuter

extend_transformations(transformations)

Extends a sequence of transformations to the TransformedStructure.

Args:

transformations:

Sequence of Transformations

static from_structures(structures, transformations=None, extend_collection=0)

Alternative constructor from structures rather than TransformedStructures.

Args:

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

get_transformed_structures()

Returns all TransformedStructures.

Deprecated since version v2.1.0: Use transformed_structures attribute instead. Will be removed in next version.

redo_next_change()

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 to_dict output.

Args:

key:

The key for the parameter.

value:

The value for the parameter.

undo_last_change()

Undo the last transformation in the TransformedStructure.

Raises:

IndexError if already at the oldest change.

write_vasp_input(vasp_input_set, output_dir, create_directory=True, subfolder=None, include_cif=False)

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

Args:

vasp_input_set:

pymatgen.io.vaspio_set.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.

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:

Boolean indication whether to output a CIF as well. CIF files are generally better supported in visualization programs.

batch_write_vasp_input(transformed_structures, vasp_input_set, output_dir, create_directory=True, subfolder=None, include_cif=False)

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

Args:

transformed_structures:

Sequence of TransformedStructures.

vasp_input_set:

pymatgen.io.vaspio_set.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.

subfolder:

function to create subdirectory name from transformed_structure. eg. lambda x: x.other_parameters[“tags”][0] to use the first tag.

include_cif:

Boolean indication whether to output a CIF as well. CIF files are generally better supported in visualization programs.