pymatgen.core.sites module

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

class PeriodicSite(species: SpeciesLike | CompositionLike, coords: ArrayLike, lattice: Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, properties: dict | None = None, skip_checks: bool = False)

Bases: Site, 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: ndarray

Cartesian coordinates

distance(other: PeriodicSite, jimage: ArrayLike | None = 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: PeriodicSite, jimage: ArrayLike | None = None) → tuple[float, np.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: ArrayLike, jimage: ArrayLike | None = None) → tuple[float, np.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: ndarray

Fractional coordinates

classmethod from_dict(d, lattice=None) → 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: 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: Lattice

Lattice associated with PeriodicSite

to_unit_cell(in_place=False) → PeriodicSite | None

Move frac coords to within the unit cell.

property x: float

Cartesian x coordinate

property y: float

Cartesian y coordinate

property z: float

Cartesian z coordinate

class Site(species: SpeciesLike | CompositionLike, coords: ArrayLike, properties: dict | None = None, skip_checks: bool = False)

Bases: Hashable, 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

Return type:

float

distance_from_point(pt) → float

Returns distance between the site and a point in space.

Parameters:

pt – Cartesian coordinates of point.

Returns:

distance

Return type:

float

classmethod from_dict(d: dict) → 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: Element | Species | 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: Composition

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

Type:

return

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