# pymatgen.core.structure module

This module provides classes used to define a non-periodic molecule and a periodic structure.

class IMolecule(species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition]], coords: Sequence[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]], charge: float = 0.0, spin_multiplicity: Optional[float] = None, validate_proximity: bool = False, site_properties: Optional[dict] = None)

  Bases: `pymatgen.core.structure.SiteCollection`, `monty.json.MSONable`

  Basic immutable Molecule object without periodicity. Essentially a sequence of sites. IMolecule is made to be immutable so that they can function as keys in a dict. For a mutable molecule, use the :class:Molecule.

  Molecule extends Sequence and Hashable, which means that in many cases, it can be used like any Python sequence. Iterating through a molecule is equivalent to going through the sites in sequence.

  Creates a 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.

  as_dict()

    Json-serializable dict representation of Molecule

  break_bond(ind1: int, ind2: int, tol: float = 0.2) → Tuple[Union[pymatgen.core.structure.IMolecule, pymatgen.core.structure.Molecule], ...]

    Returns two molecules based on breaking the bond between atoms at index ind1 and ind2.

    Parameters

      - ind1 (int) – Index of first site.

      - ind2 (int) – Index of second site.

      - tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is less than (1 + tol) * typical bond distances. Defaults to 0.2, i.e., 20% longer.

    Returns

      Two Molecule objects representing the two clusters formed from breaking the bond.

  property center_of_mass: float

    Center of mass of molecule.

  property charge: float

    Charge of molecule

  classmethod from_dict(d) → dict

    Reconstitute a Molecule object from a dict representation created using as_dict().

    Parameters

      d (dict) – dict representation of Molecule.

    Returns

      Molecule object

  classmethod from_file(filename)

    Reads a molecule from a file. Supported formats include xyz, gaussian input (gjf|g03|g09|com|inp), Gaussian output (.out|and pymatgen’s JSON serialized molecules. Using openbabel, many more extensions are supported but requires openbabel to be installed.

    Parameters

      filename (str) – The filename to read from.

    Returns

      Molecule

  classmethod from_sites(sites: Sequence[pymatgen.core.sites.Site], charge: float = 0, spin_multiplicity: Optional[float] = None, validate_proximity: bool = False) → Union[pymatgen.core.structure.IMolecule, pymatgen.core.structure.Molecule]

    Convenience constructor to make a Molecule from a list of sites.

    Parameters

      - sites ([Site]) – Sequence of Sites.

      - charge (int) – Charge of molecule. Defaults to 0.

      - spin_multiplicity (int) – Spin multicipity. Defaults to None, in which it is determined automatically.

      - validate_proximity (bool) – Whether to check that atoms are too close.

  classmethod from_str(input_string: str, fmt: str)

    Reads the molecule from a string.

    Parameters

      - input_string (str) – String to parse.

      - fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “xyz”, “gjf”, “g03”, “json”. If you have OpenBabel installed, any of the formats supported by OpenBabel. Non-case sensitive.

    Returns

      IMolecule or Molecule.

  get_boxed_structure(a: float, b: float, c: float, images: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]] = (1, 1, 1), random_rotation: bool = False, min_dist: float = 1.0, cls=None, offset: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None, no_cross: bool = False, reorder: bool = True) → Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]

    Creates a Structure from a Molecule by putting the Molecule in the center of a orthorhombic box. Useful for creating Structure for calculating molecules using periodic codes.

    Parameters

      - a (float) – a-lattice parameter.

      - b (float) – b-lattice parameter.

      - c (float) – c-lattice parameter.

      - images – No. of boxed images in each direction. Defaults to (1, 1, 1), meaning single molecule with 1 lattice parameter in each direction.

      - random_rotation (bool) – Whether to apply a random rotation to each molecule. This jumbles all the molecules so that they are not exact images of each other.

      - min_dist (float) – The minimum distance that atoms should be from each other. This is only used if random_rotation is True. The randomized rotations are searched such that no two atoms are less than min_dist from each other.

      - cls – The Structure class to instantiate (defaults to pymatgen structure)

      - offset – Translation to offset molecule from center of mass coords

      - no_cross – Whether to forbid molecule coords from extending beyond boundary of box.

      - reorder – Whether to reorder the sites to be in electronegativity order.

    Returns

      Structure containing molecule in a box.

  get_centered_molecule() → Union[pymatgen.core.structure.IMolecule, pymatgen.core.structure.Molecule]

    Returns a Molecule centered at the center of mass.

    Returns

      Molecule centered with center of mass at origin.

  get_covalent_bonds(tol: float = 0.2) → List[pymatgen.core.bonds.CovalentBond]

    Determines the covalent bonds in a molecule.

    Parameters

      tol (float) – The tol to determine bonds in a structure. See CovalentBond.is_bonded.

    Returns

      List of bonds

  get_distance(i: int, j: int) → float

    Get distance between site i and j.

    Parameters

      - i (int) – Index of first site

      - j (int) – Index of second site

    Returns

      Distance between the two sites.

  get_neighbors(site: pymatgen.core.sites.Site, r: float) → List[pymatgen.core.structure.Neighbor]

    Get all neighbors to a site within a sphere of radius r. Excludes the site itself.

    Parameters

      - site (Site) – Site at the center of the sphere.

      - r (float) – Radius of sphere.

    Returns

      [`pymatgen.core.structure.Neighbor`]

  get_neighbors_in_shell(origin: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], r: float, dr: float) → List[pymatgen.core.structure.Neighbor]

    Returns all sites in a shell centered on origin (coords) between radii r-dr and r+dr.

    Parameters

      - origin (3x1 array) – Cartesian coordinates of center of sphere.

      - r (float) – Inner radius of shell.

      - dr (float) – Width of shell.

    Returns

      [`pymatgen.core.structure.Neighbor`]

  get_sites_in_sphere(pt: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], r: float) → List[pymatgen.core.structure.Neighbor]

    Find all sites within a sphere from a point.

    Parameters

      - pt (3x1 array) – Cartesian coordinates of center of sphere

      - r (float) – Radius of sphere.

    Returns

      [`pymatgen.core.structure.Neighbor`]

  property nelectrons: float

    Number of electrons in the molecule.

  property sites: Tuple[pymatgen.core.sites.Site, ...]

    Returns a tuple of sites in the Molecule.

  property spin_multiplicity: float

    Spin multiplicity of molecule.

  to(fmt=None, filename=None)

    Outputs the molecule to a file or string.

    Parameters

      - fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “xyz”, “gjf”, “g03”, “json”. If you have OpenBabel installed, any of the formats supported by OpenBabel. Non-case sensitive.

      - filename (str) – If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output.

    Returns

      (str) if filename is None. None otherwise.

class IStructure(lattice: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]], pymatgen.core.lattice.Lattice], species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition]], coords: Sequence[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]], charge: Optional[float] = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: Optional[dict] = None)

  Bases: `pymatgen.core.structure.SiteCollection`, `monty.json.MSONable`

  Basic immutable Structure object with periodicity. Essentially a sequence of PeriodicSites having a common lattice. IStructure is made to be (somewhat) immutable so that they can function as keys in a dict. To make modifications, use the standard Structure object instead. Structure extends Sequence and Hashable, which means that in many cases, it can be used like any Python sequence. Iterating through a structure is equivalent to going through the sites in sequence.

  Create a periodic structure.

  Parameters

    - lattice (Lattice/3x3 array) – The lattice, either as a `pymatgen.core.lattice.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 ([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.

    - charge (int) – 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.

  as_dataframe()

    Returns a Pandas dataframe of the sites. Structure level attributes are stored in DataFrame.attrs. Example:

    Species a b c x y z magmom 0 (Si) 0.0 0.0 0.000000e+00 0.0 0.000000e+00 0.000000e+00 5 1 (Si) 0.0 0.0 1.000000e-07 0.0 -2.217138e-07 3.135509e-07 -5

  as_dict(verbosity=1, fmt=None, **kwargs)

    Dict representation of Structure.

    Parameters

      - verbosity (int) – Verbosity level. Default of 1 includes both direct and cartesian coordinates for all sites, lattice parameters, etc. Useful for reading and for insertion into a database. Set to 0 for an extremely lightweight version that only includes sufficient information to reconstruct the object.

      - fmt (str) – Specifies a format for the dict. Defaults to None, which is the default format used in pymatgen. Other options include “abivars”.

      - **kwargs – Allow passing of other kwargs needed for certain

      - formats –

      - e.g. –

      - "abivars". –

    Returns

      JSON serializable dict representation.

  property charge: float

    Overall charge of the structure

  copy(site_properties=None, sanitize=False)

    Convenience method to get a copy of the structure, with options to add site properties.

    Parameters

      - site_properties (dict) – Properties to add or override. The properties are specified in the same way as the constructor, i.e., as a dict of the form {property: [values]}. The properties should be in the order of the original structure if you are performing sanitization.

      - sanitize (bool) – If True, this method will return a sanitized structure. Sanitization performs a few things: (i) The sites are sorted by electronegativity, (ii) a LLL lattice reduction is carried out to obtain a relatively orthogonalized cell, (iii) all fractional coords for sites are mapped into the unit cell.

    Returns

      A copy of the Structure, with optionally new site_properties and optionally sanitized.

  property density: float

    Returns the density in units of g/cc

  property distance_matrix: numpy.ndarray

    Returns the distance matrix between all sites in the structure. For periodic structures, this should return the nearest image distance.

  property frac_coords

    Fractional coordinates as a Nx3 numpy array.

  classmethod from_dict(d, fmt=None)

    Reconstitute a Structure object from a dict representation of Structure created using as_dict().

    Parameters

      d (dict) – Dict representation of structure.

    Returns

      Structure object

  classmethod from_file(filename, primitive=False, sort=False, merge_tol=0.0)

    Reads a structure from a file. For example, anything ending in a “cif” is assumed to be a Crystallographic Information Format file. Supported formats include CIF, POSCAR/CONTCAR, CHGCAR, LOCPOT, vasprun.xml, CSSR, Netcdf and pymatgen’s JSON serialized structures.

    Parameters

      - filename (str) – The filename to read from.

      - primitive (bool) – Whether to convert to a primitive cell Only available for cifs. Defaults to False.

      - sort (bool) – Whether to sort sites. Default to False.

      - merge_tol (float) – If this is some positive number, sites that are within merge_tol from each other will be merged. Usually 0.01 should be enough to deal with common numerical issues.

    Returns

      Structure.

  classmethod from_magnetic_spacegroup(msg: Union[str, MagneticSpaceGroup], lattice: Union[List, numpy.ndarray, pymatgen.core.lattice.Lattice], species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, pymatgen.core.composition.Composition]], coords: Sequence[Sequence[float]], site_properties: Dict[str, Sequence], coords_are_cartesian: bool = False, tol: float = 1e-05) → Union[IStructure, Structure]

    Generate a structure using a magnetic spacegroup. Note that only symmetrically distinct species, coords and magmoms should be provided.] All equivalent sites are generated from the spacegroup operations.

    Parameters

      - msg (str/list/`pymatgen.symmetry.maggroups.MagneticSpaceGroup`) – The magnetic spacegroup. If a string, it will be interpreted as one of the notations supported by MagneticSymmetryGroup, e.g., “R-3’c” or “Fm’-3’m”. If a list of two ints, it will be interpreted as the number of the spacegroup in its Belov, Neronova and Smirnova (BNS) setting.

      - lattice (Lattice/3x3 array) – The lattice, either as a `pymatgen.core.lattice.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]. Note that no attempt is made to check that the lattice is compatible with the spacegroup specified. This may be introduced in a future version.

      - species ([Species]) –

        Sequence of species on each site. Can take in flexible input, including: i. 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.

      - 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. Unlike Structure.from_spacegroup(), this argument is mandatory, since magnetic moment information has to be included. Note that the direction of the supplied magnetic moment relative to the crystal is important, even if the resulting structure is used for collinear calculations.

      - coords_are_cartesian (bool) – Set to True if you are providing coordinates in cartesian coordinates. Defaults to False.

      - tol (float) – A fractional tolerance to deal with numerical precision issues in determining if orbits are the same.

  classmethod from_sites(sites: List[pymatgen.core.sites.PeriodicSite], charge: Optional[float] = None, validate_proximity: bool = False, to_unit_cell: bool = False) → Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]

    Convenience constructor to make a Structure from a list of sites.

    Parameters

      - sites – Sequence of PeriodicSites. Sites must have the same lattice.

      - charge – Charge of structure.

      - 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 translate sites into the unit cell.

    Returns

      (Structure) Note that missing properties are set as None.

  classmethod from_spacegroup(sg: str, lattice: Union[List, numpy.ndarray, pymatgen.core.lattice.Lattice], species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, pymatgen.core.composition.Composition]], coords: Sequence[Sequence[float]], site_properties: Optional[Dict[str, Sequence]] = None, coords_are_cartesian: bool = False, tol: float = 1e-05) → Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]

    Generate a structure using a spacegroup. Note that only symmetrically distinct species and coords should be provided. All equivalent sites are generated from the spacegroup operations.

    Parameters

      - sg (str/int) – The spacegroup. If a string, it will be interpreted as one of the notations supported by pymatgen.symmetry.groups.Spacegroup. E.g., “R-3c” or “Fm-3m”. If an int, it will be interpreted as an international number.

      - lattice (Lattice/3x3 array) – The lattice, either as a `pymatgen.core.lattice.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]. Note that no attempt is made to check that the lattice is compatible with the spacegroup specified. This may be introduced in a future version.

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

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

      - tol (float) – A fractional tolerance to deal with numerical precision issues in determining if orbits are the same.

  classmethod from_str(input_string: str, fmt: Literal['cif', 'poscar', 'cssr', 'json', 'yaml', 'xsf', 'mcsqs'], primitive=False, sort=False, merge_tol=0.0)

    Reads a structure from a string.

    Parameters

      - input_string (str) – String to parse.

      - fmt (str) – A file format specification. One of “cif”, “poscar”, “cssr”, “json”, “yaml”, “xsf”, “mcsqs”.

      - primitive (bool) – Whether to find a primitive cell. Defaults to False.

      - sort (bool) – Whether to sort the sites in accordance to the default ordering criteria, i.e., electronegativity.

      - merge_tol (float) – If this is some positive number, sites that are within merge_tol from each other will be merged. Usually 0.01 should be enough to deal with common numerical issues.

    Returns

      IStructure / Structure

  get_all_neighbors(r: float, include_index: bool = False, include_image: bool = False, sites: Optional[Sequence[pymatgen.core.sites.PeriodicSite]] = None, numerical_tol: float = 1e-08) → List[List[pymatgen.core.structure.PeriodicNeighbor]]

    Get neighbors for each atom in the unit cell, out to a distance r Returns a list of list of neighbors for each site in structure. Use this method if you are planning on looping over all sites in the crystal. If you only want neighbors for a particular site, use the method get_neighbors as it may not have to build such a large supercell However if you are looping over all sites in the crystal, this method is more efficient since it only performs one pass over a large enough supercell to contain all possible atoms out to a distance r. The return type is a [(site, dist) …] since most of the time, subsequent processing requires the distance.

    A note about periodic images: Before computing the neighbors, this operation translates all atoms to within the unit cell (having fractional coordinates within [0,1)). This means that the “image” of a site does not correspond to how much it has been translates from its current position, but which image of the unit cell it resides.

    Parameters

      - r (float) – Radius of sphere.

      - include_index (bool) – Deprecated. Now, the non-supercell site index is always included in the returned data.

      - include_image (bool) – Deprecated. Now the supercell image is always included in the returned data.

      - sites (list of Sites or None) – sites for getting all neighbors, default is None, which means neighbors will be obtained for all sites. This is useful in the situation where you are interested only in one subspecies type, and makes it a lot faster.

      - numerical_tol (float) – This is a numerical tolerance for distances. Sites which are < numerical_tol are determined to be conincident with the site. Sites which are r + numerical_tol away is deemed to be within r from the site. The default of 1e-8 should be ok in most instances.

    Returns

      [[`pymatgen.core.structure.PeriodicNeighbor`], ..]

  get_all_neighbors_old(**kwargs)
  get_all_neighbors_py(r: float, include_index: bool = False, include_image: bool = False, sites: Optional[Sequence[pymatgen.core.sites.PeriodicSite]] = None, numerical_tol: float = 1e-08) → List[List[pymatgen.core.structure.PeriodicNeighbor]]

    Get neighbors for each atom in the unit cell, out to a distance r Returns a list of list of neighbors for each site in structure. Use this method if you are planning on looping over all sites in the crystal. If you only want neighbors for a particular site, use the method get_neighbors as it may not have to build such a large supercell However if you are looping over all sites in the crystal, this method is more efficient since it only performs one pass over a large enough supercell to contain all possible atoms out to a distance r. The return type is a [(site, dist) …] since most of the time, subsequent processing requires the distance.

    A note about periodic images: Before computing the neighbors, this operation translates all atoms to within the unit cell (having fractional coordinates within [0,1)). This means that the “image” of a site does not correspond to how much it has been translates from its current position, but which image of the unit cell it resides.

    Parameters

      - r (float) – Radius of sphere.

      - include_index (bool) – Deprecated. Now, the non-supercell site index is always included in the returned data.

      - include_image (bool) – Deprecated. Now the supercell image is always included in the returned data.

      - sites (list of Sites or None) – sites for getting all neighbors, default is None, which means neighbors will be obtained for all sites. This is useful in the situation where you are interested only in one subspecies type, and makes it a lot faster.

      - numerical_tol (float) – This is a numerical tolerance for distances. Sites which are < numerical_tol are determined to be conincident with the site. Sites which are r + numerical_tol away is deemed to be within r from the site. The default of 1e-8 should be ok in most instances.

    Returns

      [[`pymatgen.core.structure.PeriodicNeighbor`],…]

  get_distance(i: int, j: int, jimage=None) → float

    Get distance between site i and j assuming periodic boundary conditions. If the index jimage of two sites atom j is not specified it selects the jimage nearest to the i atom and returns the distance and jimage indices in terms of lattice vector translations if the index jimage of atom j is specified it returns the distance between the i atom and the specified jimage atom.

    Parameters

      - i (int) – Index of first site

      - j (int) – Index of second site

      - jimage – Number of lattice translations in each lattice direction. Default is None for nearest image.

    Returns

      distance

  get_miller_index_from_site_indexes(site_ids, round_dp=4, verbose=True)

    Get the Miller index of a plane from a set of sites indexes.

    A minimum of 3 sites are required. If more than 3 sites are given the best plane that minimises the distance to all points will be calculated.

    Parameters

      - site_ids (list of int) – A list of site indexes to consider. A minimum of three site indexes are required. If more than three sites are provided, the best plane that minimises the distance to all sites will be calculated.

      - round_dp (int, optional) – The number of decimal places to round the miller index to.

      - verbose (bool, optional) – Whether to print warnings.

    Returns

      The Miller index.

    Return type

      (tuple)

  get_neighbor_list(r: float, sites: Optional[Sequence[pymatgen.core.sites.PeriodicSite]] = None, numerical_tol: float = 1e-08, exclude_self: bool = True) → Tuple[numpy.ndarray, ...]

    Get neighbor lists using numpy array representations without constructing Neighbor objects. If the cython extension is installed, this method will be orders of magnitude faster than get_all_neighbors_old and 2-3x faster than get_all_neighbors. The returned values are a tuple of numpy arrays (center_indices, points_indices, offset_vectors, distances). Atom center_indices[i] has neighbor atom points_indices[i] that is translated by offset_vectors[i] lattice vectors, and the distance is distances[i].

    Parameters

      - r (float) – Radius of sphere

      - sites (list of Sites or None) – sites for getting all neighbors, default is None, which means neighbors will be obtained for all sites. This is useful in the situation where you are interested only in one subspecies type, and makes it a lot faster.

      - numerical_tol (float) – This is a numerical tolerance for distances. Sites which are < numerical_tol are determined to be conincident with the site. Sites which are r + numerical_tol away is deemed to be within r from the site. The default of 1e-8 should be ok in most instances.

      - exclude_self (bool) – whether to exclude atom neighboring with itself within numerical tolerance distance, default to True

    Returns: (center_indices, points_indices, offset_vectors, distances)

  get_neighbors(site: pymatgen.core.sites.PeriodicSite, r: float, include_index: bool = False, include_image: bool = False) → List[pymatgen.core.structure.PeriodicNeighbor]

    Get all neighbors to a site within a sphere of radius r. Excludes the site itself.

    Parameters

      - site (Site) – Which is the center of the sphere.

      - r (float) – Radius of sphere.

      - include_index (bool) – Deprecated. Now, the non-supercell site index is always included in the returned data.

      - include_image (bool) – Deprecated. Now the supercell image is always included in the returned data.

    Returns

      [`pymatgen.core.structure.PeriodicNeighbor`]

  get_neighbors_in_shell(origin: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], r: float, dr: float, include_index: bool = False, include_image: bool = False) → List[pymatgen.core.structure.PeriodicNeighbor]

    Returns all sites in a shell centered on origin (coords) between radii r-dr and r+dr.

    Parameters

      - origin (3x1 array) – Cartesian coordinates of center of sphere.

      - r (float) – Inner radius of shell.

      - dr (float) – Width of shell.

      - include_index (bool) – Deprecated. Now, the non-supercell site index is always included in the returned data.

      - include_image (bool) – Deprecated. Now the supercell image is always included in the returned data.

    Returns

      [NearestNeighbor] where Nearest Neighbor is a named tuple containing (site, distance, index, image).

  get_neighbors_old(**kwargs)
  get_orderings(mode: Literal['enum', 'sqs'] = 'enum', **kwargs) → List[pymatgen.core.structure.Structure]

    Returns list of orderings for a disordered structure. If structure does not contain disorder, the default structure is returned.

    Parameters

      - mode ("enum" | "sqs") – Either “enum” or “sqs”. If enum, the enumlib will be used to return all distinct orderings. If sqs, mcsqs will be used to return an sqs structure.

      - kwargs – kwargs passed to either pymatgen.command_line..enumlib_caller.EnumlibAdaptor or pymatgen.command_line.mcsqs_caller.run_mcsqs. For run_mcsqs, a default cluster search of 2 cluster interactions with 1NN distance and 3 cluster interactions with 2NN distance is set.

    Returns

      List[Structure]

  get_primitive_structure(tolerance: float = 0.25, use_site_props: bool = False, constrain_latt: Optional[Union[List, Dict]] = None)

    This finds a smaller unit cell than the input. Sometimes it doesn”t find the smallest possible one, so this method is recursively called until it is unable to find a smaller cell.

    NOTE: if the tolerance is greater than 1/2 the minimum inter-site distance in the primitive cell, the algorithm will reject this lattice.

    Parameters

      - tolerance (float) – Tolerance for each coordinate of a particular site. For example, [0.1, 0, 0.1] in cartesian coordinates will be considered to be on the same coordinates as [0, 0, 0] for a tolerance of 0.25. Defaults to 0.25.

      - use_site_props (bool) – Whether to account for site properties in differntiating sites.

      - constrain_latt (list/dict) – List of lattice parameters we want to preserve, e.g. [“alpha”, “c”] or dict with the lattice parameter names as keys and values we want the parameters to be e.g. {“alpha”: 90, “c”: 2.5}.

    Returns

      The most primitive structure found.

  get_reduced_structure(reduction_algo: Literal['niggli', 'LLL'] = 'niggli') → Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]

    Get a reduced structure.

    Parameters

      reduction_algo ("niggli" | "LLL") – The lattice reduction algorithm to use. Defaults to “niggli”.

  get_sites_in_sphere(pt: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], r: float, include_index: bool = False, include_image: bool = False) → List[pymatgen.core.structure.PeriodicNeighbor]

    Find all sites within a sphere from the point, including a site (if any) sitting on the point itself. This includes sites in other periodic images.

    Algorithm:

    1. place sphere of radius r in crystal and determine minimum supercell (parallelpiped) which would contain a sphere of radius r. for this we need the projection of a_1 on a unit vector perpendicular to a_2 & a_3 (i.e. the unit vector in the direction b_1) to determine how many a_1”s it will take to contain the sphere.

       Nxmax = r * length_of_b_1 / (2 Pi)

    2. keep points falling within r.

    Parameters

      - pt (3x1 array) – cartesian coordinates of center of sphere.

      - r (float) – Radius of sphere.

      - include_index (bool) – Whether the non-supercell site index is included in the returned data

      - include_image (bool) – Whether to include the supercell image is included in the returned data

    Returns

      [`pymatgen.core.structure.PeriodicNeighbor`]

  get_sorted_structure(key: Optional[Callable] = None, reverse: bool = False) → Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]

    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.

    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_space_group_info(symprec=0.01, angle_tolerance=5.0) → Tuple[str, int]

    Convenience method to quickly get the spacegroup of a structure.

    Parameters

      - symprec (float) – Same definition as in SpacegroupAnalyzer. Defaults to 1e-2.

      - angle_tolerance (float) – Same definition as in SpacegroupAnalyzer. Defaults to 5 degrees.

    Returns

      spacegroup_symbol, international_number

  interpolate(end_structure: Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure], nimages: Union[int, Iterable] = 10, interpolate_lattices: bool = False, pbc: bool = True, autosort_tol: float = 0) → List[Union[pymatgen.core.structure.IStructure, pymatgen.core.structure.Structure]]

    Interpolate between this structure and end_structure. Useful for construction of NEB inputs.

    Parameters

      - end_structure (Structure) – structure to interpolate between this structure and end.

      - nimages (int,list) – No. of interpolation images or a list of interpolation images. Defaults to 10 images.

      - interpolate_lattices (bool) – Whether to interpolate the lattices. Interpolates the lengths and angles (rather than the matrix) so orientation may be affected.

      - pbc (bool) – Whether to use periodic boundary conditions to find the shortest path between endpoints.

      - autosort_tol (float) – A distance tolerance in angstrom in which to automatically sort end_structure to match to the closest points in this particular structure. This is usually what you want in a NEB calculation. 0 implies no sorting. Otherwise, a 0.5 value usually works pretty well.

    Returns

      List of interpolated structures. The starting and ending structures included as the first and last structures respectively. A total of (nimages + 1) structures are returned.

  property lattice: pymatgen.core.lattice.Lattice

    Lattice of the structure.

  matches(other, anonymous=False, **kwargs) → bool

    Check whether this structure is similar to another structure. Basically a convenience method to call structure matching.

    Parameters

      - other (IStructure/Structure) – Another structure.

      - **kwargs – Same **kwargs as in `pymatgen.analysis.structure_matcher.StructureMatcher`.

    Returns

      (bool) True is the structures are similar under some affine transformation.

  property sites: Tuple[pymatgen.core.sites.PeriodicSite, ...]

    Returns an iterator for the sites in the Structure.

  to(fmt: Optional[str] = None, filename=None, **kwargs) → Optional[str]

    Outputs the structure to a file or string.

    Parameters

      - fmt (str) – Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include “cif”, “poscar”, “cssr”, “json”. Non-case sensitive.

      - filename (str) – If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output.

      - **kwargs – Kwargs passthru to relevant methods. E.g., This allows the passing of parameters like symprec to the CifWriter.__init__ method for generation of symmetric cifs.

    Returns

      (str) if filename is None. None otherwise.

  property volume: float

    Returns the volume of the structure.

class Molecule(species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]], coords: Sequence[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]], charge: float = 0.0, spin_multiplicity: Optional[float] = None, validate_proximity: bool = False, site_properties: Optional[dict] = None)

  Bases: `pymatgen.core.structure.IMolecule`, `collections.abc.MutableSequence`

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

  Creates a MutableMolecule.

  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.

  append(species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition], coords: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], validate_proximity: bool = False, properties: Optional[dict] = None)

    Appends 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(symmop: pymatgen.core.operations.SymmOp)

    Apply a symmetry operation to the molecule.

    Parameters

      symmop (SymmOp) – Symmetry operation to apply.

  copy()

    Convenience method to get a copy of the molecule.

    Returns

      A copy of the Molecule.

  insert(i: int, species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition], coords: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], validate_proximity: bool = False, properties: Optional[dict] = None)

    Insert a site to the molecule.

    Parameters

      - i (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.

    Returns

      New molecule with inserted site.

  perturb(distance: float)

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

    Parameters

      distance (float) – Distance in angstroms by which to perturb each site.

  remove_sites(indices: Sequence[int])

    Delete sites with at indices.

    Parameters

      indices – Sequence of indices of sites to delete.

  remove_species(species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]])

    Remove all occurrences of a species from a molecule.

    Parameters

      species – Species to remove.

  rotate_sites(indices: Optional[Sequence[int]] = None, theta: float = 0.0, axis: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None, anchor: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None)

    Rotate specific sites by some angle around vector at anchor.

    Parameters

      - indices (list) – List of site indices on which to perform the translation.

      - theta (float) – Angle in radians

      - axis (3x1 array) – Rotation axis vector.

      - anchor (3x1 array) – Point of rotation.

  set_charge_and_spin(charge: float, spin_multiplicity: Optional[float] = None)

    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.

  substitute(index: int, func_group: Union[pymatgen.core.structure.IMolecule, pymatgen.core.structure.Molecule, str], bond_order: int = 1)

    Substitute atom at index with a functional group.

    Parameters

      - index (int) – Index of atom to substitute.

      - func_grp –

        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_grp 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.

  translate_sites(indices: Optional[Sequence[int]] = None, vector: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None)

    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.

class Neighbor(species: pymatgen.core.composition.Composition, coords: numpy.ndarray, properties: Optional[dict] = None, nn_distance: float = 0.0, index: int = 0)

  Bases: `pymatgen.core.sites.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.

class PeriodicNeighbor(species: pymatgen.core.composition.Composition, coords: numpy.ndarray, lattice: pymatgen.core.lattice.Lattice, properties: Optional[dict] = None, nn_distance: float = 0.0, index: int = 0, image: tuple = (0, 0, 0))

  Bases: `pymatgen.core.sites.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).

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

  Parameters

    - species – Same as PeriodicSite

    - coords – Same as PeriodicSite, but must be fractional.

    - lattice – Same as PeriodicSite

    - properties – Same as PeriodicSite

    - nn_distance – Distance to some other Site.

    - index – Index within structure.

    - image – PeriodicImage

  property coords: numpy.ndarray

    Cartesian coords.

    Type

      return

class SiteCollection

  Bases: `collections.abc.Sequence`

  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.

  DISTANCE_TOLERANCE = 0.5
  add_oxidation_state_by_element(oxidation_states: Dict[str, float])

    Add oxidation states.

    Parameters

      oxidation_states (dict) – Dict of oxidation states. E.g., {“Li”:1, “Fe”:2, “P”:5, “O”:-2}

  add_oxidation_state_by_guess(**kwargs)

    Decorates the structure with oxidation state, guessing using Composition.oxi_state_guesses()

    Parameters

      **kwargs – parameters to pass into oxi_state_guesses()

  add_oxidation_state_by_site(oxidation_states: List[float])

    Add oxidation states to a structure by site.

    Parameters

      oxidation_states (list) – List of oxidation states. E.g., [1, 1, 1, 1, 2, 2, 2, 2, 5, 5, 5, 5, -2, -2, -2, -2]

  add_site_property(property_name: str, values: List)

    Adds a property to a site.

    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.

  add_spin_by_element(spins: Dict[str, float])

    Add spin states to a structure.

    Parameters

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

  add_spin_by_site(spins: List[float])

    Add spin states to a structure by site.

    Parameters

      spins (list) – List of spins E.g., [+5, -5, 0, 0]

  property atomic_numbers: Tuple[int]

    List of atomic numbers.

  property cart_coords

    Returns a np.array of the cartesian coordinates of sites in the structure.

  property charge: float

    Returns the net charge of the structure based on oxidation states. If Elements are found, a charge of 0 is assumed.

  property composition: pymatgen.core.composition.Composition

    (Composition) Returns the composition

  property distance_matrix: numpy.ndarray

    Returns the distance matrix between all sites in the structure. For periodic structures, this is overwritten to return the nearest image distance.

  extract_cluster(target_sites: List[pymatgen.core.sites.Site], **kwargs)

    Extracts a cluster of atoms based on bond lengths

    Parameters

      - target_sites ([Site]) – List of initial sites to nucleate cluster.

      - **kwargs – kwargs passed through to CovalentBond.is_bonded.

    Returns

      [Site/PeriodicSite] Cluster of atoms.

  property formula: str

    (str) Returns the formula.

  abstract classmethod from_file(filename: str)

    Reads in SiteCollection from a filename.

  abstract classmethod from_str(input_string: str, fmt: Any)

    Reads in SiteCollection from a string.

  get_angle(i: int, j: int, k: int) → float

    Returns angle specified by three sites.

    Parameters

      - i – Index of first site.

      - j – Index of second site.

      - k – Index of third site.

    Returns

      Angle in degrees.

  get_dihedral(i: int, j: int, k: int, l: int) → float

    Returns dihedral angle specified by four sites.

    Parameters

      - i – Index of first site

      - j – Index of second site

      - k – Index of third site

      - l – Index of fourth site

    Returns

      Dihedral angle in degrees.

  abstract get_distance(i: int, j: int) → float

    Returns distance between sites at index i and j.

    Parameters

      - i – Index of first site

      - j – Index of second site

    Returns

      Distance between sites at index i and index j.

  group_by_types() → Iterator[Union[pymatgen.core.sites.Site, pymatgen.core.sites.PeriodicSite]]

    Iterate over species grouped by type

  indices_from_symbol(symbol: str) → Tuple[int, ...]

    Returns a tuple with the sequential indices of the sites that contain an element with the given chemical symbol.

  property is_ordered: bool

    Checks if structure is ordered, meaning no partial occupancies in any of the sites.

  is_valid(tol: float = 0.5) → bool

    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.5A.

    Returns

      (bool) True if SiteCollection does not contain atoms that are too close together.

  property ntypesp: int

    Number of types of atoms.

  property num_sites: int

    Number of sites.

  remove_oxidation_states()

    Removes oxidation states from a structure.

  remove_site_property(property_name: str)

    Removes a property to a site.

    Parameters

      property_name (str) – The name of the property to remove.

  remove_spin()

    Removes spin states from a structure.

  replace_species(species_mapping: Dict[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies], Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]]) → None

    Swap species. Note that this method modifies the structure in place.

    Parameters

      species_mapping (dict) – dict of 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.

  property site_properties: Dict[str, List]

    Returns the site properties as a dict of sequences. E.g., {“magmom”: (5,-5), “charge”: (-4,4)}.

  abstract property sites

    Returns a tuple of sites.

  property species: List[pymatgen.core.composition.Composition]

    Only works for ordered structures. Disordered structures will raise an AttributeError.

    Returns

      ([Species]) List of species at each site of the structure.

  property species_and_occu: List[pymatgen.core.composition.Composition]

    List of species and occupancies at each site of the structure.

  property symbol_set: Tuple[str]

    Tuple with the set of chemical symbols. Note that len(symbol_set) == len(types_of_specie)

  abstract to(fmt: Optional[str] = None, filename: Optional[str] = None)

    Generates well-known string representations of SiteCollections (e.g., molecules / structures). Should return a string type or write to a file.

  property types_of_specie: Tuple[Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]]

    Specie->Species rename. Maintained for backwards compatibility.

  property types_of_species: Tuple[Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]]

    List of types of specie.

class Structure(lattice: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]], pymatgen.core.lattice.Lattice], species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition]], coords: Sequence[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]], charge: Optional[float] = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: Optional[dict] = None)

  Bases: `pymatgen.core.structure.IStructure`, `collections.abc.MutableSequence`

  Mutable version of structure.

  Create a periodic structure.

  Parameters

    - lattice – The lattice, either as a pymatgen.core.lattice.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 (int) – 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.

  append(species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition], coords: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], coords_are_cartesian: bool = False, validate_proximity: bool = False, properties: Optional[dict] = None)

    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(symmop: pymatgen.core.operations.SymmOp, fractional: bool = False)

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

    Parameters

      - symmop (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.

  apply_strain(strain: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]])

    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.

  insert(i: int, species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition], coords: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], coords_are_cartesian: bool = False, validate_proximity: bool = False, properties: Optional[dict] = None)

    Insert a site to the structure.

    Parameters

      - i (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. Defaults to False.

      - properties (dict) – Properties associated with the site.

    Returns

      New structure with inserted site.

  property lattice: pymatgen.core.lattice.Lattice

    Lattice assciated with structure.

    Type

      return

  make_supercell(scaling_matrix: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], to_unit_cell: bool = True)

    Create a supercell.

    Parameters

      - scaling_matrix –

        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 – Whether or not to fall back sites into the unit cell

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

    Merges sites (adding occupancies) within tol of each other. Removes site properties.

    Parameters

      - tol (float) – Tolerance for distance to merge sites.

      - mode ('sum' | 'delete' | 'average') – “delete” means duplicate sites are deleted. “sum” means the occupancies are summed for the sites. “average” means that the site is deleted but the properties are averaged Only first letter is considered.

  perturb(distance: float, min_distance: Optional[float] = None)

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

    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’.

  remove_sites(indices: Sequence[int])

    Delete sites with at indices.

    Parameters

      indices – Sequence of indices of sites to delete.

  remove_species(species: Sequence[Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]])

    Remove all occurrences of several species from a structure.

    Parameters

      species – Sequence of species to remove, e.g., [“Li”, “Na”].

  replace(i: int, species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies, dict, pymatgen.core.composition.Composition], coords: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None, coords_are_cartesian: bool = False, properties: Optional[dict] = None)

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

    Parameters

      - i (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.

  rotate_sites(indices: Optional[List[int]] = None, theta: float = 0.0, axis: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None, anchor: Optional[Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]]] = None, to_unit_cell: bool = True)

    Rotate specific sites by some angle around vector at anchor.

    Parameters

      - indices (list) – List of site indices on which to perform the translation.

      - 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

  scale_lattice(volume: float)

    Performs a 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.

  set_charge(new_charge: float = 0.0)

    Sets the overall structure charge

    Parameters

      new_charge (float) – new charge to set

  sort(key: Optional[Callable] = None, reverse: bool = False)

    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 just sorts the Structure in place.

    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.

  substitute(index: int, func_group: Union[pymatgen.core.structure.IMolecule, pymatgen.core.structure.Molecule, str], bond_order: int = 1)

    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_grp 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.

  translate_sites(indices: Union[int, Sequence[int]], vector: Union[Sequence[Sequence[Sequence[Sequence[Sequence[Any]]]]], numpy.typing._array_like._SupportsArray[numpy.dtype], Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]], Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]], Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]], Sequence[Sequence[Sequence[Sequence[numpy.typing._array_like._SupportsArray[numpy.dtype]]]]], bool, int, float, complex, str, bytes, Sequence[Union[bool, int, float, complex, str, bytes]], Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]], Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]], Sequence[Sequence[Sequence[Sequence[Union[bool, int, float, complex, str, bytes]]]]]], frac_coords: bool = True, to_unit_cell: bool = True)

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

    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

exception StructureError

  Bases: `Exception`

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