Structure

Bases: Structure

This class is a wraparound for Pymatgen's Structure class with additional properties and methods.

Source code in src/baderkit/toolkit/structure.py

class Structure(PymatgenStructure):
    """
    This class is a wraparound for Pymatgen's Structure class with additional
    properties and methods.
    """

    def __init__(
        self,
        lattice: Lattice,
        species: list[Species],
        frac_coords: list[NDArray],
        symmetry_kwargs: dict = {},
        **kwargs,
    ):
        # clean frac coords
        for coord in frac_coords:
            coord %= 1.0
        super().__init__(lattice, species, frac_coords, **kwargs)
        # add labels to sites. This is to add backwards compatability to the
        # relabel_sites method that doesn't exist in earlier versions of pymatgen
        for site in self:
            site.properties["label"] = site.specie.symbol

        # cache for symmetry data
        self._symmetry_kwargs = symmetry_kwargs
        self._symmetry_data = None
        self._last_symmetry_save = None
        self._spacegroup_analyzer = None

    def insert(  # type: ignore
        self,
        i: int,
        species: CompositionLike,
        coords: NDArray,
        coords_are_cartesian: bool = False,
        validate_proximity: bool = False,
        properties: dict | None = None,
    ):
        """
        Insert a site to the structure.

        This is a wraparound for the PyMatGen method adding a label if it is
        not specified.

        Args:
            i (int): Index to insert site
            species (species-like): Species of inserted site
            coords (3x1 array): Coordinates of inserted site
            coords_are_cartesian (bool): Whether coordinates are cartesian.
                Defaults to False.
            validate_proximity (bool): Whether to check if inserted site is
                too close to an existing site. Defaults to False.
            properties (dict): Properties associated with the site.

        Returns:
            New structure with inserted site.
        """
        if properties is None:
            properties = {}
        if properties.get("label", None) is None:
            properties["label"] = str(species)

        super().insert(
            i,
            species=species,
            coords=coords,
            coords_are_cartesian=coords_are_cartesian,
            validate_proximity=validate_proximity,
            properties=properties,
        )

    @property
    def labels(self) -> list[str]:
        """

        Returns
        -------
        list[str]
            The list of labels for each site

        """
        return [site.label for site in self]

    @labels.setter
    def labels(self, labels: list[str]):
        assert len(labels) == len(self), "Labels must be the same length structure."

    def get_cart_from_miller(self, h: int, k: int, l: int) -> NDArray[float]:
        """
        Gets the cartesian coordinates of the vector perpendicular to the provided
        miller indices

        Parameters
        ----------
        h : int
            First miller index.
        k : int
            Second miller index.
        l : int
            Third miller index.


        Returns
        -------
        NDArray[float]
            The cartesian coordinates of the vector perpendicular to the plane
            defined by the provided miller indices.

        """
        lattice = self.lattice
        # Get three points that define the plane from miller indices. For indices
        # of zero we can just take one of the other points and add 1 along the
        # lattice direction of interest to make a parallel line
        if h != 0:
            a1 = np.array([1 / h, 0, 0])
        else:
            a1 = None
        if k != 0:
            a2 = np.array([0, 1 / k, 0])
        else:
            a2 = None
        if l != 0:
            a3 = np.array([0, 0, 1 / l])
        else:
            a3 = None

        if a1 is None:
            if a2 is not None:
                a1 = a2.copy()
            else:
                a1 = a3.copy()
            a1[0] += 1

        if a2 is None:
            if a1 is not None:
                a2 = a1.copy()
            else:
                a2 = a3.copy()
            a2[1] += 1

        if a3 is None:
            if a1 is not None:
                a3 = a1.copy()
            else:
                a3 = a2.copy()
            a3[2] += 1

        # get real space coords from fractional coords
        a1_real = lattice.get_cartesian_coords(a1)
        a2_real = lattice.get_cartesian_coords(a2)
        a3_real = lattice.get_cartesian_coords(a3)

        vector1 = a2_real - a1_real
        vector2 = a3_real - a1_real
        normal_vector = np.cross(vector1, vector2)
        return normal_vector / np.linalg.norm(normal_vector)

    def relabel_sites(self, ignore_uniq: bool = False) -> Self:
        """
        This method is an exact copy of [Pymatgen's](https://github.com/materialsproject/pymatgen/blob/v2025.5.28/src/pymatgen/core/structure.py).
        It is not available in some older version of pymatgen so I've added it
        to increase the dependency range.

        Relabel sites to ensure they are unique.

        Site labels are updated in-place, and relabeled by suffixing _1, _2, ..., _n for duplicates.
        Call Structure.copy().relabel_sites() to avoid modifying the original structure.


        Parameters
        ----------
        ignore_uniq : bool, optional
            If True, do not relabel sites that already have unique labels.
            The default is False.

        Returns
        -------
        Self
            Structure: self with relabeled sites.

        """

        grouped = defaultdict(list)
        for site in self:
            grouped[site.label].append(site)

        for label, sites in grouped.items():
            if len(sites) == 0 or (len(sites) == 1 and ignore_uniq):
                continue

            for idx, site in enumerate(sites):
                site.label = f"{label}_{idx + 1}"

        return self

    @property
    def reduced_formula(self) -> str:
        """

        Returns
        -------
        str
            The reduced formula of the structure.

        """
        # NOTE: This property seems to only be available in some versions of
        # pymatgen, but its useful enough that I'm ensuring it always
        # exists here.

        return self.composition.reduced_formula

    @property
    def symmetry_kwargs(self) -> dict:
        """

        Returns
        -------
        dict
            The keyword arguments used in the SpaceGroupAnalyzer for finding
            symmetry data.

        """
        return self._symmetry_kwargs

    @symmetry_kwargs.setter
    def symmetry_kwargs(self, value: dict):
        # set kwargs and reset symmetry
        self._symmetry_kwargs = value
        self._symmetry_data = None

    @property
    def spacegroup_analyzer(self) -> SpacegroupAnalyzer:
        """

        Returns
        -------
        SpacegroupAnalyzer
            A spacegroup analyzer for this structure

        """
        if self._spacegroup_analyzer is None or self._last_symmetry_save != tuple(self):
            self._last_symmetry_save = tuple(self)
            self._spacegroup_analyzer = SpacegroupAnalyzer(self, **self.symmetry_kwargs)
        return self._spacegroup_analyzer

    @property
    def symmetry_data(self):
        """

        Returns
        -------
        TYPE
            The pymatgen symmetry dataset for the Structure object

        """
        if self._symmetry_data is None or self._last_symmetry_save != tuple(self):
            self._symmetry_data = self.spacegroup_analyzer.get_symmetry_dataset()
        return self._symmetry_data

    @property
    def equivalent_atoms(self) -> NDArray[int]:
        """

        Returns
        -------
        NDArray[int]
            The equivalent atoms in the Structure.

        """
        return self.symmetry_data.equivalent_atoms

    @staticmethod
    def merge_frac_coords(frac_coords):
        # avoid circular import
        from baderkit.global_numba.basic import merge_frac_coords

        frac_coords = np.asarray(frac_coords, dtype=np.float64)
        if len(frac_coords) == 0:
            return None
        elif frac_coords.ndim == 1:
            return frac_coords
        elif frac_coords.ndim == 2 and frac_coords.shape[2] == 3:
            return merge_frac_coords(frac_coords)
        else:
            raise Exception("Frac coords must have Nx3 shape")

    @property
    def site_symbols(self):
        return np.array([i.specie.symbol for i in self])

    @property
    def farthest_point(self) -> tuple[float, NDArray[float]]:
        """

        Returns
        -------
        tuple(float, NDArray[float]
            The maximum distance away from any atom in the system and the corresponding
            point. Note that generally this may be one point of several in systems
            with symmetry.

        """

        dist, point = largest_empty_sphere(self.lattice.matrix, self.frac_coords)
        return dist, point

    def to(self, filename: str | Path = "", fmt: str = "", **kwargs) -> str | None:
        """
        Outputs the structure to a file or string.

        Args:
            filename (str): If provided, output will be written to a file. If
                fmt is not specified, the format is determined from the
                filename. Defaults is None, i.e. string output.
            fmt (str): Format to output to. Defaults to JSON unless filename
                is provided. If fmt is specifies, it overrides whatever the
                filename is. Options include "cif", "poscar", "cssr", "json",
                "xsf", "mcsqs", "prismatic", "yaml", "fleur-inpgen".
                Non-case sensitive.
            **kwargs: Kwargs passthru to relevant methods. E.g., This allows
                the passing of parameters like symprec to the
                CifWriter.__init__ method for generation of symmetric cifs.

        Returns:
            (str) if filename is None. None otherwise.
        """

        # this is just a wrapper for the pymatgen method because some versions
        # do not allow for Path objects
        if filename:
            filename = Path(filename)
            filename = str(filename.resolve())
        return super().to(filename=filename, fmt=fmt, **kwargs)

    ###########################################################################
    # Plotting
    ###########################################################################
    def to_plotter(self, **kwargs):
        """

        Returns
        -------
        A GridPlotter object for visualization.
        """

        from baderkit.plotting import StructurePlotter

        return StructurePlotter(self, **kwargs)

equivalent_atoms property

Returns:

Type	Description
NDArray[int]	The equivalent atoms in the Structure.

farthest_point property

Returns:

Type	Description
tuple(float, NDArray[float]	The maximum distance away from any atom in the system and the corresponding point. Note that generally this may be one point of several in systems with symmetry.

labels property writable

Returns:

Type	Description
list[str]	The list of labels for each site

reduced_formula property

Returns:

Type	Description
str	The reduced formula of the structure.

spacegroup_analyzer property

Returns:

Type	Description
SpacegroupAnalyzer	A spacegroup analyzer for this structure

symmetry_data property

Returns:

Type	Description
TYPE	The pymatgen symmetry dataset for the Structure object

symmetry_kwargs property writable

Returns:

Type	Description
dict	The keyword arguments used in the SpaceGroupAnalyzer for finding symmetry data.

get_cart_from_miller(h, k, l)

Gets the cartesian coordinates of the vector perpendicular to the provided miller indices

Parameters:

Name	Type	Description	Default
h	int	First miller index.	required
k	int	Second miller index.	required
l	int	Third miller index.	required

Returns:

Type	Description
NDArray[float]	The cartesian coordinates of the vector perpendicular to the plane defined by the provided miller indices.

Source code in src/baderkit/toolkit/structure.py

def get_cart_from_miller(self, h: int, k: int, l: int) -> NDArray[float]:
    """
    Gets the cartesian coordinates of the vector perpendicular to the provided
    miller indices

    Parameters
    ----------
    h : int
        First miller index.
    k : int
        Second miller index.
    l : int
        Third miller index.


    Returns
    -------
    NDArray[float]
        The cartesian coordinates of the vector perpendicular to the plane
        defined by the provided miller indices.

    """
    lattice = self.lattice
    # Get three points that define the plane from miller indices. For indices
    # of zero we can just take one of the other points and add 1 along the
    # lattice direction of interest to make a parallel line
    if h != 0:
        a1 = np.array([1 / h, 0, 0])
    else:
        a1 = None
    if k != 0:
        a2 = np.array([0, 1 / k, 0])
    else:
        a2 = None
    if l != 0:
        a3 = np.array([0, 0, 1 / l])
    else:
        a3 = None

    if a1 is None:
        if a2 is not None:
            a1 = a2.copy()
        else:
            a1 = a3.copy()
        a1[0] += 1

    if a2 is None:
        if a1 is not None:
            a2 = a1.copy()
        else:
            a2 = a3.copy()
        a2[1] += 1

    if a3 is None:
        if a1 is not None:
            a3 = a1.copy()
        else:
            a3 = a2.copy()
        a3[2] += 1

    # get real space coords from fractional coords
    a1_real = lattice.get_cartesian_coords(a1)
    a2_real = lattice.get_cartesian_coords(a2)
    a3_real = lattice.get_cartesian_coords(a3)

    vector1 = a2_real - a1_real
    vector2 = a3_real - a1_real
    normal_vector = np.cross(vector1, vector2)
    return normal_vector / np.linalg.norm(normal_vector)

insert(i, species, coords, coords_are_cartesian=False, validate_proximity=False, properties=None)

Insert a site to the structure.

This is a wraparound for the PyMatGen method adding a label if it is not specified.

Args: i (int): Index to insert site species (species-like): Species of inserted site coords (3x1 array): Coordinates of inserted site coords_are_cartesian (bool): Whether coordinates are cartesian. Defaults to False. validate_proximity (bool): Whether to check if inserted site is too close to an existing site. Defaults to False. properties (dict): Properties associated with the site.

Returns: New structure with inserted site.

Source code in src/baderkit/toolkit/structure.py

def insert(  # type: ignore
    self,
    i: int,
    species: CompositionLike,
    coords: NDArray,
    coords_are_cartesian: bool = False,
    validate_proximity: bool = False,
    properties: dict | None = None,
):
    """
    Insert a site to the structure.

    This is a wraparound for the PyMatGen method adding a label if it is
    not specified.

    Args:
        i (int): Index to insert site
        species (species-like): Species of inserted site
        coords (3x1 array): Coordinates of inserted site
        coords_are_cartesian (bool): Whether coordinates are cartesian.
            Defaults to False.
        validate_proximity (bool): Whether to check if inserted site is
            too close to an existing site. Defaults to False.
        properties (dict): Properties associated with the site.

    Returns:
        New structure with inserted site.
    """
    if properties is None:
        properties = {}
    if properties.get("label", None) is None:
        properties["label"] = str(species)

    super().insert(
        i,
        species=species,
        coords=coords,
        coords_are_cartesian=coords_are_cartesian,
        validate_proximity=validate_proximity,
        properties=properties,
    )

relabel_sites(ignore_uniq=False)

This method is an exact copy of Pymatgen's. It is not available in some older version of pymatgen so I've added it to increase the dependency range.

Relabel sites to ensure they are unique.

Site labels are updated in-place, and relabeled by suffixing _1, _2, ..., _n for duplicates. Call Structure.copy().relabel_sites() to avoid modifying the original structure.

Parameters:

Name	Type	Description	Default
ignore_uniq	bool	If True, do not relabel sites that already have unique labels. The default is False.	False

Returns:

Type	Description
Self	Structure: self with relabeled sites.

Source code in src/baderkit/toolkit/structure.py

def relabel_sites(self, ignore_uniq: bool = False) -> Self:
    """
    This method is an exact copy of [Pymatgen's](https://github.com/materialsproject/pymatgen/blob/v2025.5.28/src/pymatgen/core/structure.py).
    It is not available in some older version of pymatgen so I've added it
    to increase the dependency range.

    Relabel sites to ensure they are unique.

    Site labels are updated in-place, and relabeled by suffixing _1, _2, ..., _n for duplicates.
    Call Structure.copy().relabel_sites() to avoid modifying the original structure.


    Parameters
    ----------
    ignore_uniq : bool, optional
        If True, do not relabel sites that already have unique labels.
        The default is False.

    Returns
    -------
    Self
        Structure: self with relabeled sites.

    """

    grouped = defaultdict(list)
    for site in self:
        grouped[site.label].append(site)

    for label, sites in grouped.items():
        if len(sites) == 0 or (len(sites) == 1 and ignore_uniq):
            continue

        for idx, site in enumerate(sites):
            site.label = f"{label}_{idx + 1}"

    return self

to(filename='', fmt='', **kwargs)

Outputs the structure to a file or string.

Args: filename (str): If provided, output will be written to a file. If fmt is not specified, the format is determined from the filename. Defaults is None, i.e. string output. fmt (str): Format to output to. Defaults to JSON unless filename is provided. If fmt is specifies, it overrides whatever the filename is. Options include "cif", "poscar", "cssr", "json", "xsf", "mcsqs", "prismatic", "yaml", "fleur-inpgen". Non-case sensitive. **kwargs: Kwargs passthru to relevant methods. E.g., This allows the passing of parameters like symprec to the CifWriter.init method for generation of symmetric cifs.

Returns: (str) if filename is None. None otherwise.

Source code in src/baderkit/toolkit/structure.py

def to(self, filename: str | Path = "", fmt: str = "", **kwargs) -> str | None:
    """
    Outputs the structure to a file or string.

    Args:
        filename (str): If provided, output will be written to a file. If
            fmt is not specified, the format is determined from the
            filename. Defaults is None, i.e. string output.
        fmt (str): Format to output to. Defaults to JSON unless filename
            is provided. If fmt is specifies, it overrides whatever the
            filename is. Options include "cif", "poscar", "cssr", "json",
            "xsf", "mcsqs", "prismatic", "yaml", "fleur-inpgen".
            Non-case sensitive.
        **kwargs: Kwargs passthru to relevant methods. E.g., This allows
            the passing of parameters like symprec to the
            CifWriter.__init__ method for generation of symmetric cifs.

    Returns:
        (str) if filename is None. None otherwise.
    """

    # this is just a wrapper for the pymatgen method because some versions
    # do not allow for Path objects
    if filename:
        filename = Path(filename)
        filename = str(filename.resolve())
    return super().to(filename=filename, fmt=fmt, **kwargs)

to_plotter(**kwargs)

Returns:

Type	Description
A GridPlotter object for visualization.

Source code in src/baderkit/toolkit/structure.py

def to_plotter(self, **kwargs):
    """

    Returns
    -------
    A GridPlotter object for visualization.
    """

    from baderkit.plotting import StructurePlotter

    return StructurePlotter(self, **kwargs)