site_analysis.spherical_site

Spherical site representation for crystal structure analysis.

This module provides the SphericalSite class, which represents a site defined by a sphere with a specific centre position and radius. Spherical sites are the simplest site geometry, useful for quick analysis or when the exact shape of the site is less important than its location.

class SphericalSite(frac_coords: ndarray, rcut: float, label: str | None = None)

Bases: Site

A site defined by a spherical volume in real space.

Represents a spherical site centred at a position in fractional coordinates with a radius in Angstroms (not fractional coordinates).

SphericalSite determines whether atoms are inside the site volume by checking if the distance between the atom and the site centre is less than or equal to the site’s radius. This calculation considers periodic boundary conditions via minimum-image convention distances.

Unlike polyhedral sites, spherical sites have a fixed geometry independent of atom positions in the structure, making them suitable for applications where consistent site volumes are needed regardless of structural distortions.

frac_coords

Fractional coordinates of the sphere centre.

Type:

np.ndarray

rcut

Cutoff radius in Angstroms.

Type:

float

See also

Site: Parent class documenting inherited attributes

(index, label, contains_atoms, trajectory, points, transitions, average_occupation).

Note

SphericalSite objects are typically used with SphericalSiteCollection, which implements specific assignment logic for handling atoms in overlapping sites.

as_dict() → dict

Returns a dictionary representation of this SphericalSite.

Creates a JSON-serializable dictionary containing all the attributes needed to reconstruct this SphericalSite object.

Returns:

Dictionary containing the SphericalSite’s attributes, including

attributes from the parent Site class plus ‘frac_coords’ and ‘rcut’.

Return type:

dict

property centre: ndarray

Returns the fractional coordinates of the spherical site’s centre.

Returns:

Fractional coordinates of the site centre.

Return type:

np.ndarray

contains_atom(atom: Atom, *, lattice_matrix: ndarray | None = None) → bool

Test whether this spherical site contains a specific atom.

Parameters:

• atom – The atom to test.

• lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors. Required for distance calculations.

Returns:

True if the atom is contained within this site, False otherwise.

Raises:

ValueError – If lattice_matrix is not provided.

contains_point(x: ndarray, *, lattice_matrix: ndarray | None = None) → bool

Test if the point x is contained by this spherical site.

Parameters:

• x – Fractional coordinates to test.

• lattice_matrix – (3, 3) lattice matrix where rows are lattice vectors. Required for distance calculations.

Returns:

True if the point is within the cutoff radius, False otherwise.

Raises:

ValueError – If lattice_matrix is not provided.

classmethod from_dict(d: dict) → SphericalSite

Create a SphericalSite object from a dictionary representation.

This is the complementary method to as_dict(), allowing SphericalSite objects to be reconstructed from their dictionary representation.

Parameters:

d – Dictionary containing at minimum ‘frac_coords’ and ‘rcut’ keys. May also contain ‘label’ and other attributes from the parent Site class.

Returns:

A new SphericalSite instance with attributes set

according to the provided dictionary.

Return type:

SphericalSite