pymatgen.core.sites module¶
This module defines classes representing nonperiodic and periodic sites.

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:
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.
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.

property
a
¶ Fractional a coordinate

as_dict
(verbosity=0)[source]¶ Jsonserializable 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 alattice 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 alattice 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 alattice 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=1e08, 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

property
x
¶ Cartesian x coordinate

property
y
¶ Cartesian y coordinate

property
z
¶ Cartesian z coordinate

class
Site
(atoms_n_occu, coords, properties=None)[source]¶ Bases:
collections.abc.Hashable
,monty.json.MSONable
A generalized nonperiodic 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 nonperiodic site.
 Parameters
atoms_n_occu –
Species on the site. Can be: i. A Compositiontype 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.

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)

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

position_atol
= 1e05¶

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