# pymatgen.core.sites module

This module defines classes representing non-periodic and periodic sites.

class PeriodicSite(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]]]]]], lattice: pymatgen.core.lattice.Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, properties: Optional[dict] = None, skip_checks: bool = False)

  Bases: `pymatgen.core.sites.Site`, `monty.json.MSONable`

  Extension of generic Site object to periodic systems. PeriodicSite includes a lattice system.

  Create a periodic site.

  Parameters

    - species –

      Species on the site. Can be: i. A Composition-type object (preferred) ii. An element / species specified either as a string

      > symbols, e.g. “Li”, “Fe2+”, “P” or atomic numbers, e.g., 3, 56, or actual Element or Species objects.

      iii.Dict of elements/species and occupancies, e.g.,

        {“Fe” : 0.5, “Mn”:0.5}. This allows the setup of disordered structures.

    - coords – Cartesian coordinates of site.

    - lattice – Lattice associated with the site.

    - to_unit_cell – Translates fractional coordinate to the basic unit cell, i.e. all fractional coordinates satisfy 0 <= a < 1. Defaults to False.

    - coords_are_cartesian – Set to True if you are providing cartesian coordinates. Defaults to False.

    - properties – Properties associated with the site as a dict, e.g. {“magmom”: 5}. Defaults to None.

    - skip_checks – Whether to ignore all the usual checks and just create the site. Use this if the PeriodicSite is created in a controlled manner and speed is desired.

  property a: float

    Fractional a coordinate

  as_dict(verbosity: int = 0) → dict

    Json-serializable dict representation of PeriodicSite.

    Parameters

      verbosity (int) – Verbosity level. Default of 0 only includes the matrix representation. Set to 1 for more details such as cartesian coordinates, etc.

  property b: float

    Fractional b coordinate

  property c: float

    Fractional c coordinate

  property coords: numpy.ndarray

    Cartesian coordinates

  distance(other: pymatgen.core.sites.PeriodicSite, jimage: 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)

    Get distance between two sites assuming periodic boundary conditions.

    Parameters

      - other (PeriodicSite) – Other site to get distance from.

      - jimage (3x1 array) – Specific periodic image in terms of lattice translations, e.g., [1,0,0] implies to take periodic image that is one a-lattice vector away. If jimage is None, the image that is nearest to the site is found.

    Returns

      Distance between the two sites

    Return type

      distance (float)

  distance_and_image(other: pymatgen.core.sites.PeriodicSite, jimage: 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) → Tuple[float, numpy.ndarray]

    Gets distance and instance between two sites assuming periodic boundary conditions. If the index jimage of two sites atom j is not specified it selects the j image 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 ith atom and the specified jimage atom, the given jimage is also returned.

    Parameters

      - other (PeriodicSite) – Other site to get distance from.

      - jimage (3x1 array) – Specific periodic image in terms of lattice translations, e.g., [1,0,0] implies to take periodic image that is one a-lattice vector away. If jimage is None, the image that is nearest to the site is found.

    Returns

      distance and periodic lattice translations of the other site for which the distance applies.

    Return type

      (distance, jimage)

  distance_and_image_from_frac_coords(fcoords: 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]]]]]], jimage: 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) → Tuple[float, numpy.ndarray]

    Gets distance between site and a fractional coordinate assuming periodic boundary conditions. If the index jimage of two sites atom j is not specified it selects the j image 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, the given jimage is also returned.

    Parameters

      - fcoords (3x1 array) – fcoords to get distance from.

      - jimage (3x1 array) – Specific periodic image in terms of lattice translations, e.g., [1,0,0] implies to take periodic image that is one a-lattice vector away. If jimage is None, the image that is nearest to the site is found.

    Returns

      distance and periodic lattice translations of the other site for which the distance applies.

    Return type

      (distance, jimage)

  property frac_coords: numpy.ndarray

    Fractional coordinates

  classmethod from_dict(d, lattice=None) → pymatgen.core.sites.PeriodicSite

    Create PeriodicSite from dict representation.

    Parameters

      - d (dict) – dict representation of PeriodicSite

      - lattice – Optional lattice to override lattice specified in d. Useful for ensuring all sites in a structure share the same lattice.

    Returns

      PeriodicSite

  is_periodic_image(other: pymatgen.core.sites.PeriodicSite, tolerance: float = 1e-08, check_lattice: bool = True) → bool

    Returns True if sites are periodic images of each other.

    Parameters

      - other (PeriodicSite) – Other site

      - tolerance (float) – Tolerance to compare fractional coordinates

      - check_lattice (bool) – Whether to check if the two sites have the same lattice.

    Returns

      True if sites are periodic images of each other.

    Return type

      bool

  property lattice: pymatgen.core.lattice.Lattice

    Lattice associated with PeriodicSite

  to_unit_cell(in_place=False) → Optional[pymatgen.core.sites.PeriodicSite]

    Move frac coords to within the unit cell cell.

  property x: float

    Cartesian x coordinate

  property y: float

    Cartesian y coordinate

  property z: float

    Cartesian z coordinate

class Site(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]]]]]], properties: Optional[dict] = None, skip_checks: bool = False)

  Bases: `collections.abc.Hashable`, `monty.json.MSONable`

  A generalized non-periodic site. This is essentially a composition at a point in space, with some optional properties associated with it. A Composition is used to represent the atoms and occupancy, which allows for disordered site representation. Coords are given in standard cartesian coordinates.

  Creates a non-periodic Site.

  Parameters

    - species –

      Species on the site. Can be: i. A Composition-type object (preferred) ii. An element / species specified either as a string

      > symbols, e.g. “Li”, “Fe2+”, “P” or atomic numbers, e.g., 3, 56, or actual Element or Species objects.

      iii.Dict of elements/species and occupancies, e.g.,

        {“Fe” : 0.5, “Mn”:0.5}. This allows the setup of disordered structures.

    - coords – Cartesian coordinates of site.

    - properties – Properties associated with the site as a dict, e.g. {“magmom”: 5}. Defaults to None.

    - skip_checks – Whether to ignore all the usual checks and just create the site. Use this if the Site is created in a controlled manner and speed is desired.

  as_dict() → dict

    Json-serializable dict representation for Site.

  distance(other) → float

    Get distance between two sites.

    Parameters

      other – Other site.

    Returns

      Distance (float)

  distance_from_point(pt) → float

    Returns distance between the site and a point in space.

    Parameters

      pt – Cartesian coordinates of point.

    Returns

      Distance (float)

  classmethod from_dict(d: dict) → pymatgen.core.sites.Site

    Create Site from dict representation

  property is_ordered: bool

    True if site is an ordered site, i.e., with a single species with occupancy 1.

  position_atol = 1e-05
  property specie: Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]

    The Species/Element at the site. Only works for ordered sites. Otherwise an AttributeError is raised. Use this property sparingly. Robust design should make use of the property species instead. Note that the singular of species is also species. So the choice of this variable name is governed by programmatic concerns as opposed to grammar.

    Raises

      AttributeError if Site is not ordered. –

  property species: pymatgen.core.composition.Composition

    The species on the site as a composition, e.g., Fe0.5Mn0.5.

    Type

      return

  property species_and_occu
  property species_string: str

    String representation of species on the site.

  property x: float

    Cartesian x coordinate

  property y: float

    Cartesian y coordinate

  property z: float

    Cartesian z coordinate