pymatgen.core package 

to_conventional(**kwargs) → Structure[source]

Get a conventional cell based on the current structure.

Parameters:: kwargs – Any keyword supported by pymatgen.symmetry.analyzer.SpacegroupAnalyzer such as symprec=0.01, angle_tolerance=5, international_monoclinic=True and keep_site_properties=False.
Returns:: with the requested cell type.
Return type:: Structure

to_primitive(**kwargs) → Structure[source]

Get a primitive cell based on the current structure.

Parameters:: kwargs – Any keyword supported by pymatgen.symmetry.analyzer.SpacegroupAnalyzer such as symprec=0.01, angle_tolerance=5, international_monoclinic=True and keep_site_properties=False.
Returns:: with the requested cell type.
Return type:: Structure

unset_charge() → None[source]: Reset the charge to None. E.g. to compute it dynamically based on oxidation states.

property volume: float[source]: The volume of the structure in Angstrom^3.

class Molecule(species: Sequence[SpeciesLike], coords: Sequence[ArrayLike], charge: float = 0.0, spin_multiplicity: int | None = None, validate_proximity: bool = False, site_properties: dict | None = None, labels: Sequence[str | None] | None = None, charge_spin_check: bool = True, properties: dict | None = None)[source]

Bases: IMolecule, MutableSequence

Mutable Molecule. It has all the methods in IMolecule, and allows a user to perform edits on the molecule.

Create a mutable Molecule.

Parameters:

species – list of atomic species. Possible kinds of input include a list of dict of elements/species and occupancies, a List of elements/specie specified as actual Element/Species, Strings (“Fe”, “Fe2+”) or atomic numbers (1,56).
coords (3x1 array) – list of Cartesian coordinates of each species.
charge (float) – Charge for the molecule. Defaults to 0.
spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.
validate_proximity (bool) – Whether to check if there are sites that are less than 1 Ang apart. Defaults to False.
site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g. {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
labels (list[str]) – Labels associated with the sites as a list of strings, e.g. [‘Li1’, ‘Li2’]. Must have the same length as the species and fractional coords. Defaults to None for no labels.
charge_spin_check (bool) – Whether to check that the charge and spin multiplicity are compatible with each other. Defaults to True.
properties (dict) – dictionary containing properties associated with the whole molecule.

append(species: CompositionLike, coords: ArrayLike, validate_proximity: bool = False, properties: dict | None = None) → Self[source]

Append a site to the molecule.

Parameters:

species – Species of inserted site
coords – Coordinates of inserted site
validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to False.
properties (dict) – A dict of properties for the Site.

Returns:

New molecule with inserted site.

apply_operation(symm_op: SymmOp) → Self[source]

Apply a symmetry operation to the molecule.

Parameters:: symm_op (SymmOp) – Symmetry operation to apply.
Returns:: self after symmetry operation.
Return type:: Molecule

calculate(calculator: Literal['gfn2-xtb'] | Calculator = 'gfn2-xtb', verbose: bool = False) → Calculator[source]

Perform an ASE calculation.

Parameters:

calculator – An ASE Calculator or “gfn2-xtb”. Defaults to ‘gfn2-xtb’.
verbose (bool) – whether to print stdout. Defaults to False.

Returns:

ASE Calculator instance with a results attribute containing the output.

Return type:

Calculator

insert(idx: int, species: CompositionLike, coords: ArrayLike, validate_proximity: bool = False, properties: dict | None = None, label: str | None = None) → Self[source]

Insert a site to the molecule.

Parameters:

idx (int) – Index to insert site
species – species of inserted site
coords (3x1 array) – coordinates of inserted site
validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to True.
properties (dict) – Dict of properties for the Site.
label (str) – Label of inserted site

Returns:

New molecule with inserted site.

perturb(distance: float) → Self[source]

Perform a random perturbation of the sites in a structure to break symmetries.

Parameters:: distance (float) – Distance in angstroms by which to perturb each site.
Returns:: self with perturbed sites.
Return type:: Molecule

relax(calculator: str | Calculator = 'gfn2-xtb', optimizer: str | Optimizer = 'FIRE', steps: int = 500, fmax: float = 0.1, opt_kwargs: dict | None = None, return_trajectory: bool = False, verbose: bool = False) → Self | tuple[Self, TrajectoryObserver][source]

Perform a molecule relaxation using an ASE calculator.

Parameters:

calculator – An ASE Calculator or a string from the following options: “gfn2-xtb”. Defaults to ‘gfn2-xtb’.
optimizer (str) – name of the ASE optimizer class to use
steps (int) – max number of steps for relaxation. Defaults to 500.
fmax (float) – total force tolerance for relaxation convergence. Defaults to 0.1 eV/A.
opt_kwargs (dict) – kwargs for the ASE optimizer class.
return_trajectory (bool) – Whether to return the trajectory of relaxation. Defaults to False.
verbose (bool) – whether to print out relaxation steps. Defaults to False.

Returns:

Relaxed Molecule or if return_trajectory=True,: 2-tuple of Molecule and ASE TrajectoryObserver.

Return type:

Molecule | tuple[Molecule, Trajectory]

remove_sites(indices: Sequence[int]) → Self[source]

Delete sites with at indices.

Parameters:: indices – Sequence of indices of sites to delete.
Returns:: self with sites removed.
Return type:: Molecule

remove_species(species: Sequence[SpeciesLike]) → Self[source]

Remove all occurrences of a species from a molecule.

Parameters:: species – Species to remove.
Returns:: self with species removed.
Return type:: Molecule

rotate_sites(indices: Sequence[int] | None = None, theta: float = 0.0, axis: ArrayLike | None = None, anchor: ArrayLike | None = None) → Self[source]

Rotate specific sites by some angle around vector at anchor.

Parameters:

indices (list) – Site indices on which to perform the rotation.
theta (float) – Angle in radians.
axis (3x1 array) – Rotation axis vector.
anchor (3x1 array) – Point of rotation.

Returns:

self with rotated sites.

Return type:

set_charge_and_spin(charge: float, spin_multiplicity: int | None = None) → Self[source]

Set the charge and spin multiplicity.

Parameters:

charge (int) – Charge for the molecule. Defaults to 0.
spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.

Returns:

self with new charge and spin multiplicity set.

Return type:

substitute(index: int, func_group: IMolecule | Self | str, bond_order: int = 1) → Self[source]

Substitute atom at index with a functional group.

Parameters:

index (int) – Index of atom to substitute.
func_group –
Substituent molecule. There are two options:
1. Providing an actual molecule as the input. The first atom must be a DummySpecies X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_group should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
2. A string name. The molecule will be obtained from the relevant template in func_groups.json.
bond_order (int) – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.

Returns:

self after substitution.

Return type:

translate_sites(indices: Sequence[int] | None = None, vector: ArrayLike | None = None) → Self[source]

Translate specific sites by some vector, keeping the sites within the unit cell.

Parameters:

indices (list) – List of site indices on which to perform the translation.
vector (3x1 array) – Translation vector for sites.

Returns:

self with translated sites.

Return type:

class Neighbor(species: Composition, coords: NDArray, properties: dict | None = None, nn_distance: float = 0.0, index: int = 0, label: str | None = None)[source]

Bases: Site

Simple Site subclass to contain a neighboring atom that skips all the unnecessary checks for speed. Can be used as a fixed-length tuple of size 3 to retain backwards compatibility with past use cases.

(site, nn_distance, index).

In future, usage should be to call attributes, e.g. Neighbor.index, Neighbor.distance, etc.

Parameters:

species – Same as Site
coords – Same as Site, but must be fractional.
properties – Same as Site
nn_distance – Distance to some other Site.
index – Index within structure.
label – Label for the site. Defaults to None.

as_dict() → dict[source]: Note that method calls the super of Site, which is MSONable itself.

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

Get a Neighbor from a dict.

Parameters:: dct – MSONable dict format.
Returns:: Neighbor

class PeriodicNeighbor(species: Composition, coords: NDArray, lattice: Lattice, properties: dict | None = None, nn_distance: float = 0.0, index: int = 0, image: tuple = (0, 0, 0), label: str | None = None)[source]

Bases: PeriodicSite

Simple PeriodicSite subclass to contain a neighboring atom that skips all the unnecessary checks for speed. Can be used as a fixed-length tuple of size 4 to retain backwards compatibility with past use cases:

(site, distance, index, image).

Should access attributes in the future, e.g. PeriodicNeighbor.index, PeriodicNeighbor.distance, etc.

Parameters:

species (Composition) – Same as PeriodicSite
coords (np.ndarray) – Same as PeriodicSite, but must be fractional.
lattice (Lattice) – Same as PeriodicSite
properties (dict, optional) – Same as PeriodicSite. Defaults to None.
nn_distance (float, optional) – Distance to some other Site.. Defaults to 0.0.
index (int, optional) – Index within structure.. Defaults to 0.
image (tuple, optional) – PeriodicImage. Defaults to (0, 0, 0).
label (str, optional) – Label for the site. Defaults to None.

as_dict() → dict[source]: Note that method calls the super of Site, which is MSONable itself.

property coords: NDArray[source]: Cartesian coords.

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

Get a PeriodicNeighbor from a dict.

Parameters:: dct – MSONable dict format.
Returns:: PeriodicNeighbor

class SiteCollection[source]

Bases: Sequence, ABC

Basic SiteCollection. Essentially a sequence of Sites or PeriodicSites. This serves as a base class for Molecule (a collection of Site, i.e., no periodicity) and Structure (a collection of PeriodicSites, i.e., periodicity). Not meant to be instantiated directly.

Init a SiteCollection.

DISTANCE_TOLERANCE: ClassVar[float] = 0.5[source]

add_oxidation_state_by_element(oxidation_states: dict[str, float]) → Self[source]

Add oxidation states.

Parameters:: oxidation_states (dict) – Dict of oxidation states. e.g. {“Li”:1, “Fe”:2, “P”:5, “O”:-2}
Raises:: ValueError if oxidation states are not specified for all elements. –
Returns:: self with oxidation states.
Return type:: SiteCollection

add_oxidation_state_by_guess(**kwargs) → Self[source]

Decorates the structure with oxidation state, guessing using Composition.oxi_state_guesses(). If multiple guesses are found we take the first one.

Parameters:: **kwargs – parameters to pass into oxi_state_guesses()

add_oxidation_state_by_site(oxidation_states: list[float]) → Self[source]

Add oxidation states to a structure by site.

Parameters:: oxidation_states (list[float]) – List of oxidation states. E.g. [1, 1, 1, 1, 2, 2, 2, 2, 5, 5, 5, 5, -2, -2, -2, -2]
Raises:: ValueError if oxidation states are not specified for all sites. –
Returns:: self with oxidation states.
Return type:: SiteCollection

add_site_property(property_name: str, values: Sequence | np.ndarray) → Self[source]

Add a property to a site. Note: This is the preferred method for adding magnetic moments, selective dynamics, and related site-specific properties to a structure/molecule object.

Examples

structure.add_site_property(“magmom”, [1.0, 0.0]) structure.add_site_property(“selective_dynamics”, [[True, True, True], [False, False, False]])

Parameters:

property_name (str) – The name of the property to add.
values (list) – A sequence of values. Must be same length as number of sites.

Raises:

ValueError – if len(values) != number of sites.

Returns:

self with site property added.

Return type:

SiteCollection

add_spin_by_element(spins: dict[str, float]) → Self[source]

Add spin states to structure.

Parameters:: spins (dict) – Dict of spins associated with elements or species, e.g. {“Ni”:+5} or {“Ni2+”:5}

add_spin_by_site(spins: Sequence[float]) → Self[source]

Add spin states to structure by site.

Parameters:: spins (list) – e.g. [+5, -5, 0, 0]

property alphabetical_formula: str[source]: The formula as a string.

property atomic_numbers: tuple[int, ...][source]: Tuple of atomic numbers.

property cart_coords: ndarray[source]: An np.array of the Cartesian coordinates of sites in the structure.

property charge: float[source]: The net charge of the structure based on oxidation states. If Elements are found, a charge of 0 is assumed.

property chemical_system: str[source]: The chemical system of the structure.

property chemical_system_set: set[str][source]: The set of chemical systems in the structure. E.g. {“Al”, “Ga”, “In”, “N”} for a AlGaInN quaternary.

property composition: Composition[source]: The structure’s corresponding Composition object.

abstract copy() → Self[source]: Get a copy of itself. Concrete subclasses should implement this method.

property distance_matrix: ndarray[source]: The distance matrix between all sites in the structure. For periodic structures, this is overwritten to return the nearest image distance.

property elements: list[Element | Species | DummySpecies][source]: The elements in the structure as a list of Element objects.

extract_cluster(target_sites: list[Site], **kwargs) → list[Site][source]

Extract a cluster of atoms based on bond lengths.

Parameters:

target_sites (list[Site]) – Initial sites from which to nucleate cluster.
**kwargs – kwargs passed through to CovalentBond.is_bonded.

Returns:

list[Site/PeriodicSite] Cluster of atoms.

property formula: str[source]: The formula as a string.

from_ase_atoms(**kwargs) → Structure[source]

Convert ase.Atoms to pymatgen Structure.

Parameters:: kwargs – Passed to AseAtomsAdaptor.get_structure.
Returns:: Structure

abstract classmethod from_file(filename: str) → None[source]: Read in SiteCollection from a filename.

abstract classmethod from_str(input_string: str, fmt: Any) → None[source]: Read in SiteCollection from a string.

get_angle(i: int, j: int, k: int) → float[source]

Get angle specified by three sites.

Parameters:

i – 1st site index
j – 2nd site index
k – 3rd site index

Returns:

Angle in degrees.

get_dihedral(i: int, j: int, k: int, l: int) → float[source]

Get dihedral angle specified by four sites.

Parameters:

i (int) – 1st site index
j (int) – 2nd site index
k (int) – 3rd site index
l (int) – 4th site index

Returns:

Dihedral angle in degrees.

abstract get_distance(i: int, j: int) → float[source]

Get distance between sites at index i and j.

Parameters:

i – 1st site index
j – 2nd site index

Returns:

Distance between sites at index i and index j.

group_by_types() → Iterator[Site | PeriodicSite][source]: Iterate over species grouped by type.

indices_from_symbol(symbol: str) → tuple[int, ...][source]: Get a tuple with the sequential indices of the sites that contain an element with the given chemical symbol.

property is_ordered: bool[source]: Check if structure is ordered, meaning no partial occupancies in any of the sites.

is_valid(tol: float = 0.5) → bool[source]

True if SiteCollection does not contain atoms that are too close together. Note that the distance definition is based on type of SiteCollection. Cartesian distances are used for non-periodic Molecules, while PBC is taken into account for periodic structures.

Parameters:: tol (float) – Distance tolerance. Default is 0.5 Angstrom, which is fairly large.
Returns:: True if SiteCollection does not contain atoms that are too close together.
Return type:: bool

property labels: list[str | None][source]: Site labels as a list.

property n_elems: int[source]: Number of types of atoms.

property ntypesp: int[source]: Number of types of atoms.

property num_sites: int[source]: Number of sites.

property reduced_formula: str[source]: The reduced formula as a string.

relabel_sites(ignore_uniq: bool = False) → Self[source]

Relabel sites to ensure they are unique.

Site labels are updated in-place, and relabeled by suffixing _1, _2, …, _n for duplicates. Call Structure.copy().relabel_sites() to avoid modifying the original structure.

Parameters:: ignore_uniq (bool) – If True, do not relabel sites that already have unique labels. Defaults to False.
Returns:: self with relabeled sites.
Return type:: SiteCollection

remove_oxidation_states() → Self[source]: Removes oxidation states from a structure.

remove_site_property(property_name: str) → Self[source]

Removes a property to a site.

Parameters:: property_name (str) – The name of the property to remove.
Returns:: self with property removed.
Return type:: SiteCollection

remove_spin() → Self[source]: Remove spin states from structure.

replace_species(species_mapping: dict[SpeciesLike, SpeciesLike | dict[SpeciesLike, float]], in_place: bool = True) → Self[source]

Replace species.

Note that this resets the label of any affected site to species_string.

Parameters:

species_mapping (dict) – Species to swap. Species can be elements too. e.g. {Element(“Li”): Element(“Na”)} performs a Li for Na substitution. The second species can be a sp_and_occu dict. For example, a site with 0.5 Si that is passed the mapping {Element(‘Si’): {Element(‘Ge’): 0.75, Element(‘C’): 0.25} } will have .375 Ge and .125 C.
in_place (bool) – Whether to perform the substitution in place or modify a copy. Defaults to True.

Returns:

self or new SiteCollection (depending on in_place) with species replaced.

Return type:

SiteCollection

property site_properties: dict[str, Sequence][source]: The site properties as a dict of sequences. E.g. {“magmom”: (5, -5), “charge”: (-4, 4)}.

property sites: list[PeriodicSite] | tuple[PeriodicSite, ...][source]: The sites in the Structure.

property species: list[Element | Species][source]

Only works for ordered structures.

Raises:: AttributeError – If structure is disordered.
Returns:: species at each site of the structure.
Return type:: list[Species]

property species_and_occu: list[Composition][source]: List of species and occupancies at each site of the structure.

property symbol_set: tuple[str, ...][source]: Tuple with the set of chemical symbols. Note that len(symbol_set) == len(types_of_specie).

abstract to(filename: str = '', fmt: Literal['cif', 'poscar', 'cssr', 'json', 'yaml', 'yml', 'xsf', 'mcsqs', 'res', 'pwmat', 'aims', ''] = '') → str | None[source]: Generate string representations (cif, json, poscar, ….) of SiteCollections (e.g., molecules / structures). Should return str or None if written to a file.

to_ase_atoms(**kwargs) → Atoms[source]

Convert the structure/molecule to an ase.Atoms object.

Parameters:: kwargs – Passed to ase.Atoms init.
Returns:: ase.Atoms

to_file(filename: str = '', fmt: Literal['cif', 'poscar', 'cssr', 'json', 'yaml', 'yml', 'xsf', 'mcsqs', 'res', 'pwmat', 'aims', ''] = '') → str | None[source]: A more intuitive alias for .to().

property types_of_specie: tuple[Element | Species | DummySpecies, ...][source]: Specie -> Species rename, to maintain backwards compatibility.

property types_of_species: tuple[Element | Species | DummySpecies, ...][source]: Tuple of types of species.

class Structure(lattice: ArrayLike | Lattice, species: Sequence[CompositionLike], coords: Sequence[ArrayLike] | np.ndarray, charge: float | None = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: dict | None = None, labels: Sequence[str | None] | None = None, properties: dict | None = None)[source]

Bases: IStructure, MutableSequence

Mutable version of structure.

Create a periodic structure.

Parameters:

lattice – The lattice, either as a pymatgen.core.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. e.g. [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].
species –
List of species on each site. Can take in flexible input, including:
1. A sequence of element / species specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g. (3, 56, …) or actual Element or Species objects.
2. List of dict of elements/species and occupancies, e.g. [{“Fe” : 0.5, “Mn”:0.5}, …]. This allows the setup of disordered structures.
coords (Nx3 array) – list of fractional/cartesian coordinates of each species.
charge (float) – overall charge of the structure. Defaults to behavior in SiteCollection where total charge is the sum of the oxidation states.
validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
to_unit_cell (bool) – Whether to map all sites into the unit cell, i.e., fractional coords between 0 and 1. Defaults to False.
coords_are_cartesian (bool) – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.
site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g. {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
labels (list[str]) – Labels associated with the sites as a list of strings, e.g. [‘Li1’, ‘Li2’]. Must have the same length as the species and fractional coords. Defaults to None for no labels.
properties (dict) – Properties associated with the whole structure. Will be serialized when writing the structure to JSON or YAML but is lost when converting to other formats.

append(species: CompositionLike, coords: ArrayLike, coords_are_cartesian: bool = False, validate_proximity: bool = False, properties: dict | None = None) → Self[source]

Append a site to the structure.

Parameters:

species – Species of inserted site
coords (3x1 array) – Coordinates of inserted site
coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Defaults to False.
properties (dict) – Properties of the site.

Returns:

New structure with inserted site.

apply_operation(symm_op: SymmOp, fractional: bool = False) → Self[source]

Apply a symmetry operation to the structure in place and return the modified structure. The lattice is operated on by the rotation matrix only. Coords are operated in full and then transformed to the new lattice.

Parameters:

symm_op (SymmOp) – Symmetry operation to apply.
fractional (bool) – Whether the symmetry operation is applied in fractional space. Defaults to False, i.e., symmetry operation is applied in Cartesian coordinates.

Returns:

post-operation structure

Return type:

apply_strain(strain: ArrayLike, inplace: bool = True) → Self[source]

Apply a strain to the lattice.

Parameters:

strain (float or list) – Amount of strain to apply. Can be a float, or a sequence of 3 numbers. e.g. 0.01 means all lattice vectors are increased by 1%. This is equivalent to calling modify_lattice with a lattice with lattice parameters that are 1% larger.
inplace (bool) – True applies the strain in-place, False returns a Structure copy. Defaults to True.

Returns:

self if inplace=True else new structure with strain applied.

Return type:

calculate(calculator: str | Calculator = 'm3gnet', verbose: bool = False) → Calculator[source]

Perform an ASE calculation.

Parameters:

calculator – An ASE Calculator or a string from the following options: “m3gnet”. Defaults to ‘m3gnet’, i.e. the M3GNet universal potential.
verbose (bool) – whether to print stdout. Defaults to False.

Returns:

ASE Calculator instance with a results attribute containing the output.

Return type:

Calculator

classmethod from_prototype(prototype: str, species: Sequence, **kwargs) → Self[source]

Rapidly construct common prototype structures.

Parameters:

prototype – Name of prototype. e.g. cubic, rocksalt, perovksite etc.
species – List of species corresponding to symmetrically distinct sites.
**kwargs – Lattice parameters, e.g. a = 3.0, b = 4, c = 5. Only the required lattice parameters need to be specified. For example, if it is a cubic prototype, only a needs to be specified.

Returns:

with given prototype and species.

Return type:

insert(idx: int, species: CompositionLike, coords: ArrayLike, coords_are_cartesian: bool = False, validate_proximity: bool = False, properties: dict | None = None, label: str | None = None) → Self[source]

Insert a site to the structure.

Parameters:

idx (int) – Index to insert site
species (species-like) – Species of inserted site
coords (3x1 array) – Coordinates of inserted site
coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
validate_proximity (bool) – Whether to check if inserted site is too close to an existing site. Controlled by self.DISTANCE_TOLERANCE. Defaults to False.
properties (dict) – Properties associated with the site.
label (str) – Label associated with the site.

Returns:

New structure with inserted site.

property lattice: Lattice[source]: Lattice associated with structure.

make_supercell(scaling_matrix: ArrayLike, to_unit_cell: bool = True, in_place: bool = True) → Self[source]

Create a supercell.

Parameters:

scaling_matrix (ArrayLike) –
A scaling matrix for transforming the lattice vectors. Has to be all integers. Several options are possible:
1. A full 3x3 scaling matrix defining the linear combination the old lattice vectors. 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.
2. An sequence of three scaling factors. e.g. [2, 1, 1] specifies that the supercell should have dimensions 2a x b x c.
3. A number, which simply scales all lattice vectors by the same factor.
to_unit_cell (bool) – Whether or not to fold sites back into the unit cell if they have fractional coords > 1. Defaults to True.
in_place (bool) – Whether to perform the operation in-place or to return a new Structure object. Defaults to True.

Returns:

self if in_place is True else self.copy() after making supercell

Return type:

merge_sites(tol: float = 0.01, mode: Literal['sum', 'delete', 'average'] = 'sum') → Self[source]

Merges sites (by adding occupancies) within tolerance and removes: site properties in “sum/delete” modes.

Parameters:

tol (float) – Tolerance for distance to merge sites.
mode ("sum" | "delete" | "average") – Only first letter is considered at this moment. - “delete”: delete duplicate sites. - “sum”: sum the occupancies for the sites. - “average”: delete the site but average the properties if it’s numerical.

Returns:

Structure with merged sites.

Return type:

perturb(distance: float, min_distance: float | None = None, seed: int = 0) → Self[source]

Perform a random perturbation of the sites in a structure to break symmetries. Modifies the structure in place.

Parameters:

distance (float) – Distance in angstroms by which to perturb each site.
min_distance (None, int, or float) – if None, all displacements will be equal amplitude. If int or float, perturb each site a distance drawn from the uniform distribution between ‘min_distance’ and ‘distance’.
seed (int) – Seed for the random number generator. Defaults to 0.

Returns:

self with perturbed sites.

Return type:

relax(calculator: str | Calculator = 'm3gnet', relax_cell: bool = True, optimizer: str | Optimizer = 'FIRE', steps: int = 500, fmax: float = 0.1, stress_weight: float = 0.01, opt_kwargs: dict | None = None, return_trajectory: bool = False, verbose: bool = False) → Structure | tuple[Structure, TrajectoryObserver | Trajectory][source]

Perform a crystal structure relaxation using an ASE calculator.

Parameters:

calculator – An ASE Calculator or a string from the following options: “m3gnet”. Defaults to ‘m3gnet’, i.e. the M3GNet universal potential.
relax_cell (bool) – whether to relax the lattice cell. Defaults to True.
optimizer (str) – name of the ASE optimizer class to use
steps (int) – max number of steps for relaxation. Defaults to 500.
fmax (float) – total force tolerance for relaxation convergence. Here fmax is a sum of force and stress forces. Defaults to 0.1.
stress_weight (float) – the stress weight for relaxation with M3GNet. Defaults to 0.01.
opt_kwargs (dict) – kwargs for the ASE optimizer class.
return_trajectory (bool) – Whether to return the trajectory of relaxation. Defaults to False.
verbose (bool) – whether to print out relaxation steps. Defaults to False.

Returns:

Relaxed structure or if return_trajectory=True,: 2-tuple of Structure and matgl TrajectoryObserver.

Return type:

Structure | tuple[Structure, Trajectory]

remove_sites(indices: Sequence[int | None]) → Self[source]

Delete sites with at indices.

Parameters:: indices – Sequence of indices of sites to delete.
Returns:: self with sites removed.
Return type:: Structure

remove_species(species: Sequence[SpeciesLike]) → Self[source]

Remove all occurrences of several species from a structure.

Parameters:: species – Sequence of species to remove, e.g. [“Li”, “Na”].
Returns:: self with species removed.
Return type:: Structure

replace(idx: int, species: CompositionLike, coords: ArrayLike | None = None, coords_are_cartesian: bool = False, properties: dict | None = None, label: str | None = None) → Self[source]

Replace a single site. Takes either a species or a dict of species and occupations.

Parameters:

idx (int) – Index of the site in the sites list.
species (species-like) – Species of replacement site
coords (3x1 array) – Coordinates of replacement site. If None, the current coordinates are assumed.
coords_are_cartesian (bool) – Whether coordinates are cartesian. Defaults to False.
properties (dict) – Properties associated with the site.
label (str) – Label associated with the site.

Returns:

self with replaced site.

Return type:

rotate_sites(indices: list[int] | None = None, theta: float = 0.0, axis: ArrayLike | None = None, anchor: ArrayLike | None = None, to_unit_cell: bool = True) → Self[source]

Rotate specific sites by some angle around vector at anchor. Modifies the structure in place.

Parameters:

indices (list) – Site indices on which to perform the rotation.
theta (float) – Angle in radians.
axis (3x1 array) – Rotation axis vector.
anchor (3x1 array) – Point of rotation.
to_unit_cell (bool) – Whether new sites are transformed to unit cell

Returns:

self with rotated sites.

Return type:

scale_lattice(volume: float) → Self[source]

Perform scaling of the lattice vectors so that length proportions and angles are preserved.

Parameters:: volume (float) – New volume of the unit cell in A^3.
Returns:: self with scaled lattice.
Return type:: Structure

set_charge(new_charge: float = 0.0) → Self[source]

Set the overall structure charge.

Parameters:: new_charge (float) – new charge to set
Returns:: self with new charge set.
Return type:: Structure

sort(key: Callable | None = None, reverse: bool = False) → Self[source]

Sort a structure in place. The parameters have the same meaning as in list.sort(). By default, sites are sorted by the electronegativity of the species. The difference between this method and get_sorted_structure (which also works in IStructure) is that the latter returns a new Structure, while this modifies the original.

Parameters:

key – Specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None (compare the elements directly).
reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reversed.

Returns:

self sorted.

Return type:

substitute(index: int, func_group: IMolecule | Molecule | str, bond_order: int = 1) → Self[source]

Substitute atom at index with a functional group.

Parameters:

index (int) – Index of atom to substitute.
func_group –
Substituent molecule. There are two options:
1. Providing an actual Molecule as the input. The first atom must be a DummySpecies X, indicating the position of nearest neighbor. The second atom must be the next nearest atom. For example, for a methyl group substitution, func_group should be X-CH3, where X is the first site and C is the second site. What the code will do is to remove the index site, and connect the nearest neighbor to the C atom in CH3. The X-C bond indicates the directionality to connect the atoms.
2. A string name. The molecule will be obtained from the relevant template in func_groups.json.
bond_order (int) – A specified bond order to calculate the bond length between the attached functional group and the nearest neighbor site. Defaults to 1.

Returns:

self with functional group attached.

Return type:

translate_sites(indices: int | Sequence[int], vector: ArrayLike, frac_coords: bool = True, to_unit_cell: bool = True) → Self[source]

Translate specific sites by some vector, keeping the sites within the unit cell. Modifies the structure in place.

Parameters:

indices – Integer or List of site indices on which to perform the translation.
vector – Translation vector for sites.
frac_coords (bool) – Whether the vector corresponds to fractional or Cartesian coordinates.
to_unit_cell (bool) – Whether new sites are transformed to unit cell

Returns:

self with translated sites.

Return type:

exception StructureError[source]

Bases: Exception

Exception class for Structure. Raised when the structure has problems, e.g. atoms that are too close.

pymatgen.core.surface module

This module implements representation of Slab, SlabGenerator for generating Slabs, ReconstructionGenerator to generate reconstructed Slabs, and some related utility functions.

If you use this module, please consider citing the following work:

Tran, Z. Xu, B. Radhakrishnan, D. Winston, W. Sun, K. A. Persson,

S. P. Ong, “Surface Energies of Elemental Crystals”, Scientific Data, 2016, 3:160080, doi: 10.1038/sdata.2016.80.

Sun, W.; Ceder, G. Efficient creation and convergence of surface slabs, Surface Science, 2013, 617, 53-59, doi:10.1016/j.susc.2013.05.016.

class ReconstructionGenerator(initial_structure: Structure, min_slab_size: float, min_vacuum_size: float, reconstruction_name: str)[source]

Bases: object

Build a reconstructed Slab from a given initial Structure.

This class needs a pre-defined dictionary specifying the parameters needed such as the SlabGenerator parameters, transformation matrix, sites to remove/add and slab/vacuum sizes.

slabgen_params[source]

Parameters for the SlabGenerator.

Type:: dict

trans_matrix[source]

A 3x3 transformation matrix to generate the reconstructed slab. Only the a and b lattice vectors are actually changed while the c vector remains the same. This matrix is what the Wood’s notation is based on.

Type:: np.ndarray

reconstruction_json[source]

The full JSON or dictionary containing the instructions for building the slab.

Type:: dict

Generate reconstructed slabs from a set of instructions.

Parameters:

initial_structure (Structure) – Initial input structure. Note that to ensure that the Miller indices correspond to usual crystallographic definitions, you should supply a conventional unit cell structure.
min_slab_size (float) – Minimum Slab size in Angstrom.
min_vacuum_size (float) – Minimum vacuum layer size in Angstrom.
reconstruction_name (str) –
Name of the dict containing the build instructions. The dictionary can contain any item, however any instructions archived in pymatgen for public use need to contain the following keys and items to ensure compatibility with the ReconstructionGenerator:

”name” (str): A descriptive name for the reconstruction,
typically including the type of structure, the Miller index, the Wood’s notation and additional descriptors for the reconstruction. Example: “fcc_110_missing_row_1x2”

”description” (str): A detailed description of the
reconstruction, intended to assist future contributors in avoiding duplicate entries. Please read the description carefully before adding to prevent duplications.

”reference” (str): Optional reference to the source of
the reconstruction.

”spacegroup” (dict): A dictionary indicating the space group
of the reconstruction. e.g. {“symbol”: “Fm-3m”, “number”: 225}.

”miller_index” ([h, k, l]): Miller index of the reconstruction “Woods_notation” (str): For a reconstruction, the a and b

lattice may change to accommodate the symmetry. This notation indicates the change in the vectors relative to the primitive (p) or conventional (c) slab cell. E.g. p(2x1).

Reference: Wood, E. A. (1964). Vocabulary of surface crystallography. Journal of Applied Physics, 35(4), 1306-1312.

”transformation_matrix” (numpy array): A 3x3 matrix to
transform the slab. Only the a and b lattice vectors should change while the c vector remains the same.

”SlabGenerator_parameters” (dict): A dictionary containing
the parameters for the SlabGenerator, excluding the miller_index, min_slab_size and min_vac_size. As the Miller index is already specified and the min_slab_size and min_vac_size can be changed regardless of the reconstruction type. Having a consistent set of SlabGenerator parameters allows for the instructions to be reused.

”points_to_remove” (list[site]): A list of sites to
remove where the first two indices are fractional (in a and b) and the third index is in units of 1/d (in c), see the below “Notes” for details.

”points_to_add” (list[site]): A list of sites to add
where the first two indices are fractional (in a an b) and the third index is in units of 1/d (in c), see the below “Notes” for details.

”base_reconstruction” (dict, Optional): A dictionary specifying
an existing reconstruction model upon which the current reconstruction is built to avoid repetition. E.g. the alpha reconstruction of halites is based on the octopolar reconstruction but with the topmost atom removed. The dictionary for the alpha reconstruction would therefore contain the item “reconstruction_base”: “halite_111_octopolar_2x2”, and additional sites can be added by “points_to_add”.

Notes

For “points_to_remove” and “points_to_add”, the third index
for the c vector is specified in units of 1/d, where d represents the spacing between atoms along the hkl (the c vector), relative to the topmost site in the unreconstructed slab. For instance, a point of [0.5, 0.25, 1] corresponds to the 0.5 fractional coordinate of a, 0.25 fractional coordinate of b, and a distance of 1 atomic layer above the topmost site. Similarly, [0.5, 0.25, -0.5] corresponds to a point half an atomic layer below the topmost site, and [0.5, 0.25, 0] corresponds to a point at the same position along c as the topmost site. This approach is employed because while the primitive units of a and b remain constant, the user can vary the length of the c direction by adjusting the slab layer or the vacuum layer.
The dictionary should only provide “points_to_remove” and
“points_to_add” for the top surface. The ReconstructionGenerator will modify the bottom surface accordingly to return a symmetric Slab.

build_slabs() → list[Slab][source]

Build reconstructed Slabs by:

Obtaining the unreconstructed Slab using the specified parameters for the SlabGenerator.
Applying the appropriate lattice transformation to the a and b lattice vectors.
Remove and then add specified sites from both surfaces.

Returns:: The reconstructed slabs.
Return type:: list[Slab]

get_unreconstructed_slabs() → list[Slab][source]

Generate the unreconstructed (super) Slabs.

TODO (@DanielYang59): this should be a private method.

class Slab(lattice: Lattice | np.ndarray, species: Sequence[Any], coords: np.ndarray, miller_index: MillerIndex, oriented_unit_cell: Structure, shift: float, scale_factor: np.ndarray, reorient_lattice: bool = True, validate_proximity: bool = False, to_unit_cell: bool = False, reconstruction: str | None = None, coords_are_cartesian: bool = False, site_properties: dict | None = None, energy: float | None = None)[source]

Bases: Structure

Hold information for a Slab, with additional attributes pertaining to slabs, but the init method does not actually create a slab. Also has additional methods that returns other information about a Slab such as the surface area, normal, and atom adsorption.

Note that all Slabs have the surface normal oriented perpendicular to the a and b lattice vectors. This means the lattice vectors a and b are in the surface plane and the c vector is out of the surface plane (though not necessarily perpendicular to the surface).

A Structure object with additional information and methods pertaining to Slabs.

Parameters:

lattice (Lattice/3x3 array) – The lattice, either as a pymatgen.core.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. e.g. [[10,0,0], [20,10,0], [0,0,30]].
species ([Species]) –
Sequence of species on each site. Can take in flexible input, including:
1. A sequence of element / species specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g. (3, 56, …) or actual Element or Species objects.
2. List of dict of elements/species and occupancies, e.g. [{“Fe”: 0.5, “Mn”: 0.5}, …]. This allows the setup of disordered structures.
coords (Nx3 array) – list of fractional/cartesian coordinates of each species.
miller_index (MillerIndex) – Miller index of plane parallel to surface. Note that this is referenced to the input structure. If you need this to be based on the conventional cell, you should supply the conventional structure.
oriented_unit_cell (Structure) – The oriented_unit_cell from which this Slab is created (by scaling in the c-direction).
shift (float) – The NEGATIVE of shift in the c-direction applied to get the termination.
scale_factor (np.ndarray) – scale_factor Final computed scale factor that brings the parent cell to the surface cell.
reorient_lattice (bool) – reorients the lattice parameters such that the c direction is along the z axis.
validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.
reconstruction (str) – Type of reconstruction. Defaults to None if the slab is not reconstructed.
to_unit_cell (bool) – Translates fractional coordinates into the unit cell. Defaults to False.
coords_are_cartesian (bool) – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.
site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g. {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
energy (float) – A value for the energy.

Add adsorbate onto the Slab, along the c lattice vector.

Parameters:

indices (list[int]) – Indices of sites on which to put the adsorbate. Adsorbate will be placed relative to the center of these sites.
species (str | Element | Species) – The species to add.
distance (float) – between centers of the adsorbed atom and the given site in Angstroms, along the c lattice vector.
specie – Deprecated argument in #3691. Use ‘species’ instead.

Returns:

self with adsorbed atom.

Return type:

as_dict(**kwargs) → dict[source]: MSONable dict.

property center_of_mass: ndarray[source]: The center of mass of the Slab in fractional coordinates.

copy(site_properties: dict[str, Any] | None = None) → Self[source]

Get a copy of the Slab, with options to update site properties.

Parameters:: site_properties (dict) – Properties to update. The properties are specified in the same way as the constructor, i.e., as a dict of the form {property: [values]}.
Returns:: A copy of the Structure, with optionally new site_properties

property dipole: ndarray[source]

The dipole moment of the Slab in the direction of the surface normal.

Note that the Slab must be oxidation state decorated for this to work properly. Otherwise, the Slab will always have a dipole moment of 0.

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

Parameters:: dct – dict.
Returns:: Created from dict.
Return type:: Slab

get_orthogonal_c_slab() → Self[source]

Generate a Slab where the normal (c lattice vector) is forced to be orthogonal to the surface a and b lattice vectors.

Note that this breaks inherent symmetries in the slab.

It should be pointed out that orthogonality is not required to get good surface energies, but it can be useful in cases where the slabs are subsequently used for postprocessing of some kind, e.g. generating grain boundaries or interfaces.

get_sorted_structure(key=None, reverse: bool = False) → Self[source]

Get a sorted copy of the structure. The parameters have the same meaning as in list.sort. By default, sites are sorted by the electronegativity of the species. Note that Slab has to override this because of the different __init__ args.

Parameters:

key – Specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None (compare the elements directly).
reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reversed.

get_surface_sites(tag: bool = False) → dict[str, list][source]

Get the surface sites and their indices in a dictionary. Useful for analysis involving broken bonds and for finding adsorption sites.

The oriented unit cell of the slab will determine the coordination number of a typical site. We use VoronoiNN to determine the coordination number of sites. Due to the pathological error resulting from some surface sites in the VoronoiNN, we assume any site that has this error is a surface site as well. This will only work for single-element systems for now.

Parameters:

tag (bool) – Add attribute “is_surf_site” (bool) to all sites of the Slab. Defaults to False.

Returns:

A dictionary grouping sites on top and bottom of the slab together.: {“top”: [sites with indices], “bottom”: [sites with indices]}

get_symmetric_site(point: ArrayLike, cartesian: bool = False) → ArrayLike[source]

Use symmetry operations to find an equivalent site on the other side of the slab. Works mainly for slabs with Laue symmetry.

This is useful for retaining the non-polar and symmetric properties of a slab when creating adsorbed structures or symmetric reconstructions.

Parameters:

point (ArrayLike) – Fractional coordinate of the original site.
cartesian (bool) – Use Cartesian coordinates.

Returns:

Fractional coordinate. A site equivalent to the: original site, but on the other side of the slab

Return type:

ArrayLike

get_tasker2_slabs(tol: float = 0.01, same_species_only: bool = True) → list[Self][source]

Get a list of slabs that have been Tasker 2 corrected.

Parameters:

tol (float) – Fractional tolerance to determine if atoms are within same plane.
same_species_only (bool) – If True, only those are of the exact same species as the atom at the outermost surface are considered for moving. Otherwise, all atoms regardless of species within tol are considered for moving. Default is True (usually the desired behavior).

Returns:

Tasker 2 corrected slabs.

Return type:

list[Slab]

is_polar(tol_dipole_per_unit_area: float = 0.001) → bool[source]

Check if the Slab is polar by computing the normalized dipole per unit area. Normalized dipole per unit area is used as it is more reliable than using the absolute value, which varies with surface area.

Note that the Slab must be oxidation state decorated for this to work properly. Otherwise, the Slab will always have a dipole moment of 0.

Parameters:: tol_dipole_per_unit_area (float) – A tolerance above which the Slab is considered polar.

is_symmetric(symprec: float = 0.1) → bool[source]

Check if Slab is symmetric, i.e., contains inversion, mirror on (hkl) plane,: or screw axis (rotation and translation) about [hkl].

Parameters:: symprec (float) – Symmetry precision used for SpaceGroup analyzer.
Returns:: True if surfaces are symmetric.
Return type:: bool

property normal: ndarray[source]: The surface normal vector of the Slab, normalized to unit length.

property surface_area: float[source]: The surface area of the Slab.

Add a species at a selected site in a Slab. Will also add an equivalent site on the other side to maintain symmetry.

Parameters:

species (str | Element | Species) – The species to add.
point (ArrayLike) – The coordinate of the target site.
specie – Deprecated argument name in #3691. Use ‘species’ instead.
coords_are_cartesian (bool) – If the site is in Cartesian coordinates.

symmetrically_remove_atoms(indices: list[int]) → None[source]

Remove sites from a list of indices. Will also remove the equivalent site on the other side of the slab to maintain symmetry.

Parameters:: indices (list[int]) – The indices of the sites to remove.

TODO(@DanielYang59): 1. Reuse public method get_symmetric_site to get equi sites? 2. If not 1, get_equi_sites has multiple nested loops

class SlabGenerator(initial_structure: Structure, miller_index: MillerIndex, min_slab_size: float, min_vacuum_size: float, lll_reduce: bool = False, center_slab: bool = False, in_unit_planes: bool = False, primitive: bool = True, max_normal_search: int | None = None, reorient_lattice: bool = True)[source]

Bases: object

Generate different slabs using shift values determined by where a unique termination can be found, along with other criteria such as where a termination doesn’t break a polyhedral bond. The shift value then indicates where the slab layer will begin and terminate in the slab-vacuum system.

oriented_unit_cell[source]

An oriented unit cell of the parent structure.

Type:: Structure

parent[source]

Parent structure from which Slab was derived.

Type:: Structure

lll_reduce[source]

Whether the slabs will be orthogonalized.

Type:: bool

center_slab[source]

Whether the slabs will be centered in the slab-vacuum system.

Type:: bool

slab_scale_factor[source]

Scale factor that brings the parent cell to the surface cell.

Type:: float

miller_index[source]

Miller index of plane parallel to surface.

Type:: tuple

min_slab_size[source]

Minimum size of layers containing atoms, in angstroms.

Type:: float

min_vac_size[source]

Minimum vacuum layer size, in angstroms.

Type:: float

Calculate the slab scale factor and uses it to generate an oriented unit cell (OUC) of the initial structure. Also stores the initial information needed later on to generate a slab.

Parameters:

initial_structure (Structure) – Initial input structure. Note that to ensure that the Miller indices correspond to usual crystallographic definitions, you should supply a conventional unit cell structure.
miller_index ([h, k, l]) – Miller index of the plane parallel to the surface. Note that this is referenced to the input structure. If you need this to be based on the conventional cell, you should supply the conventional structure.
min_slab_size (float) – In Angstroms or number of hkl planes
min_vacuum_size (float) – In Angstroms or number of hkl planes
lll_reduce (bool) – Whether to perform an LLL reduction on the final structure.
center_slab (bool) – Whether to center the slab in the cell with equal vacuum spacing from the top and bottom.
in_unit_planes (bool) – Whether to set min_slab_size and min_vac_size in number of hkl planes or Angstrom (default). Setting in units of planes is useful to ensure some slabs to have a certain number of layers, e.g. for Cs(100), 10 Ang will result in a slab with only 2 layers, whereas Fe(100) will have more layers. The slab thickness will be in min_slab_size/math.ceil(self._proj_height/dhkl) multiples of oriented unit cells.
primitive (bool) – Whether to reduce generated slabs to primitive cell. Note this does NOT generate a slab from a primitive cell, it means that after slab generation, we attempt to reduce the generated slab to primitive cell.
max_normal_search (int) – If set to a positive integer, the code will search for a normal lattice vector that is as perpendicular to the surface as possible, by considering multiple linear combinations of lattice vectors up to this value. This has no bearing on surface energies, but may be useful as a preliminary step to generate slabs for absorption or other sizes. It may not be the smallest possible cell for simulation. Normality is not guaranteed, but the oriented cell will have the c vector as normal as possible to the surface. The max absolute Miller index is usually sufficient.
reorient_lattice (bool) – reorient the lattice such that the c direction is parallel to the third lattice vector

get_slab(shift: float = 0, tol: float = 0.1, energy: float | None = None) → Slab[source]

[Private method] Generate a slab based on a given termination: coordinate along the lattice c direction.

You should RARELY use this method directly.

Parameters:

shift (float) – The termination coordinate along the lattice c direction in fractional coordinates.
tol (float) – Tolerance to determine primitive cell.
energy (float) – The energy to assign to the slab.

Returns:

from a shifted oriented unit cell.

Return type:

get_slabs(bonds: dict[tuple[Species | Element, Species | Element], float] | None = None, ftol: float = 0.1, tol: float = 0.1, max_broken_bonds: int = 0, symmetrize: bool = False, repair: bool = False, ztol: float = 0, filter_out_sym_slabs: bool = True) → list[Slab][source]

Generate slabs with shift values calculated from the internal gen_possible_terminations func. If the user decide to avoid breaking any polyhedral bond (by setting bonds), any shift value that do so would be filtered out.

Parameters:

bonds (dict) – A {(species1, species2): max_bond_dist} dict. For example, PO4 groups may be defined as {(“P”, “O”): 3}.
tol (float) – Fractional tolerance for getting primitive cells and matching structures.
ftol (float) – Threshold for fcluster to check if two atoms are on the same plane. Default to 0.1 Angstrom in the direction of the surface normal.
max_broken_bonds (int) – Maximum number of allowable broken bonds for the slab. Use this to limit number of slabs. Defaults to 0, which means no bonds could be broken.
symmetrize (bool) – Whether to enforce the equivalency of slab surfaces.
repair (bool) – Whether to repair terminations with broken bonds (True) or just omit them (False). Default to False as repairing terminations can lead to many more possible slabs.
ztol (float) – Fractional tolerance for determine overlapping z-ranges, smaller ztol might result in more possible Slabs.
filter_out_sym_slabs (bool) – If True filter out identical slabs with different terminations.

Returns:

All possible Slabs of a particular surface,: sorted by the number of bonds broken.

Return type:

list[Slab]

move_to_other_side(init_slab: Slab, index_of_sites: list[int]) → Slab[source]

Move surface sites to the opposite surface of the Slab.

If a selected site resides on the top half of the Slab, it would be moved to the bottom side, and vice versa. The distance moved is equal to the thickness of the Slab.

Note

You should only use this method on sites close to the surface, otherwise it would end up deep inside the vacuum layer.

Parameters:

init_slab (Slab) – The Slab whose sites would be moved.
index_of_sites (list[int]) – Indices representing the sites to move.

Returns:

The Slab with selected sites moved.

Return type:

nonstoichiometric_symmetrized_slab(init_slab: Slab) → list[Slab][source]

Symmetrize the two surfaces of a Slab, but may break the stoichiometry.

How it works:

1. Check whether two surfaces of the slab are equivalent. If the point group of the slab has an inversion symmetry ( ie. belong to one of the Laue groups), then it’s assumed that the surfaces are equivalent.

2.If not symmetrical, sites at the bottom of the slab will be removed until the slab is symmetric, which may break the stoichiometry.

Parameters:: init_slab (Slab) – The initial Slab.
Returns:: The symmetrized Slabs.
Return type:: list[Slabs]

repair_broken_bonds(slab: Slab, bonds: dict[tuple[Species | Element, Species | Element], float]) → Slab[source]

Repair broken bonds (specified by the bonds parameter) due to slab cleaving, and repair them by moving undercoordinated atoms to the other surface.

How it works:: For example a P-O4 bond may have P and O(4-x) on one side of the surface, and Ox on the other side, this method would first move P (the reference atom) to the other side, find its missing nearest neighbours (Ox), and move P and Ox back together.

Parameters:

slab (Slab) – The Slab to repair.
bonds (dict) – A {(species1, species2): max_bond_dist} dict. For example, PO4 groups may be defined as {(“P”, “O”): 3}.

Returns:

The repaired Slab.

Return type: