pymatgen.core.sites module

class PeriodicSite(atoms_n_occu, coords, lattice, to_unit_cell=False, coords_are_cartesian=False, properties=None)[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
  • atoms_n_occu

    Species on the site. Can be:

    1. A sequence of element / specie specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g., (3, 56, …) or actual Element or Specie 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 (3x1 array or sequence) – Coordinates of site as fractional or cartesian coordinates.

  • lattice – Lattice associated with the site

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

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

  • properties (dict) – Properties associated with the PeriodicSite, e.g., {“magmom”:5}. Defaults to None.

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.

b

Fractional b coordinate

c

Fractional c coordinate

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)

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

lattice

Lattice associated with PeriodicSite

to_unit_cell(in_place=False)[source]

Move frac coords to within the unit cell cell.

x

Cartesian x coordinate

y

Cartesian y coordinate

z

Cartesian z coordinate

class Site(atoms_n_occu, coords, properties=None)[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.

Create a non-periodic site.

Parameters
  • atoms_n_occu

    Species on the site. Can be: i. A Composition 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.

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)[source]

Create Site from dict representation

is_ordered

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

position_atol = 1e-05
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.

species
species_and_occu
species_string

String representation of species on the site.

x

Cartesian x coordinate

y

Cartesian y coordinate

z

Cartesian z coordinate