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

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

A copy of the fractional coordinates of the site.

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

The lattice associated with the site.

to_unit_cell

Copy of PeriodicSite translated to the unit cell.

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.

coords

A copy of the cartesian coordinates of the site as a numpy array.

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
properties

Returns a view of properties as a dict.

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_and_occu

The species at the site, i.e., a Composition mapping type of element/species to occupancy.

species_string

String representation of species on the site.

x

Cartesian x coordinate

y

Cartesian y coordinate

z

Cartesian z coordinate