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.Specie, pymatgen.core.periodic_table.DummySpecie, Dict, pymatgen.core.composition.Composition], coords: Union[Tuple, List, numpy.ndarray], lattice: pymatgen.core.lattice.Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, properties: dict = None, skip_checks: bool = False)[source]

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 / specie specified either as a string

    symbols, e.g. “Li”, “Fe2+”, “P” or atomic numbers, e.g., 3, 56, or actual Element or Specie 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

Fractional a coordinate

as_dict(verbosity=0)[source]

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

Fractional b coordinate

property c

Fractional c coordinate

property coords

Cartesian coordinates

distance(other, jimage=None)[source]

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, jimage=None)[source]

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, jimage=None)[source]

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

Fractional coordinates

classmethod from_dict(d, lattice=None)[source]

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, tolerance=1e-08, check_lattice=True)[source]

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 associated with PeriodicSite

to_unit_cell(in_place=False)[source]

Move frac coords to within the unit cell cell.

property x

Cartesian x coordinate

property y

Cartesian y coordinate

property z

Cartesian z coordinate

class Site(species: Union[str, pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Specie, pymatgen.core.periodic_table.DummySpecie, Dict, pymatgen.core.composition.Composition], coords: Union[Tuple, List, numpy.ndarray], properties: dict = None, skip_checks: bool = False)[source]

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 / specie specified either as a string

    symbols, e.g. “Li”, “Fe2+”, “P” or atomic numbers, e.g., 3, 56, or actual Element or Specie 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()[source]

Json-serializable dict representation for Site.

distance(other)[source]

Get distance between two sites.

Parameters

other – Other site.

Returns

Distance (float)

distance_from_point(pt)[source]

Returns distance between the site and a point in space.

Parameters

pt – Cartesian coordinates of point.

Returns

Distance (float)

classmethod from_dict(d: dict)[source]

Create Site from dict representation

property is_ordered

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

position_atol = 1e-05
property specie

The Specie/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_and_occu instead.

Raises

AttributeError if Site is not ordered. –

property species

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

Type

return

property species_and_occu
property species_string

String representation of species on the site.

property x

Cartesian x coordinate

property y

Cartesian y coordinate

property z

Cartesian z coordinate