Source code for httk.atomistic.models.species.record

"""Backend for an exact stored species record."""

from fractions import Fraction
from typing import Any, Self

from httk.atomistic.models.species.backend import SpeciesBackend
from httk.atomistic.storage.records import SpeciesRecord, _concentration_precision_from_record



[docs]
class RecordSpecies(SpeciesBackend):
    r"""Backend for a species stored in an exact record.

    :param obj: The stored species record.
    :param \**hints: Backend-selection hints.
    """

    _record: SpeciesRecord

    @classmethod
    def _backend_adopt(cls, obj: Any, **hints: Any) -> Self | None:
        r"""Adopt a species record.

        :param obj: The source object to adopt.
        :param \**hints: Backend-selection hints.
        :return: An initialized backend, or ``None`` when this backend declines ``obj``.
        """
        if hints and hints.get("kind", "record") != "record":
            return None
        if not isinstance(obj, SpeciesRecord):
            return None
        return cls(obj, **hints)

    def __init__(self, obj: SpeciesRecord, **hints: Any) -> None:
        self._record = obj

    @property

[docs]
    def name(self) -> str:
        """Return the species name.

        :return: The species name.
        """
        return self._record.name


    @property

[docs]
    def chemical_symbols(self) -> tuple[str, ...]:
        """Return the constituent symbols.

        :return: The chemical symbols.
        """
        return self._record.chemical_symbols


    @property

[docs]
    def concentration(self) -> tuple[Fraction, ...]:
        """Return the constituent concentrations.

        :return: The concentrations.
        """
        return self._record.concentration


    @property

[docs]
    def concentration_precision(self) -> tuple[Fraction | None, ...] | None:
        """Return the concentration precision metadata.

        :return: Per-constituent precision, or ``None`` when unavailable.
        """
        return _concentration_precision_from_record(self._record.concentration_precision)


    @property

[docs]
    def charges(self) -> tuple[Fraction | None, ...] | None:
        """Return the constituent charges.

        :return: The charges, or ``None`` when unstated.
        """
        return self._record.charges


    @property

[docs]
    def spins(self) -> tuple[Fraction | None, ...] | None:
        """Return the constituent spins.

        :return: The spins, or ``None`` when unstated.
        """
        return self._record.spins


    @property

[docs]
    def labels(self) -> tuple[str | None, ...] | None:
        """Return the constituent labels.

        :return: The labels, or ``None`` when unstated.
        """
        return self._record.labels


    @property

[docs]
    def mass(self) -> tuple[float, ...] | None:
        """Return the constituent masses.

        :return: The masses, or ``None`` when unstated.
        """
        return self._record.mass


    @property

[docs]
    def attached(self) -> tuple[str, ...] | None:
        """Return the attached constituent symbols.

        :return: The attached symbols, or ``None`` when unstated.
        """
        return self._record.attached


    @property

[docs]
    def nattached(self) -> tuple[int, ...] | None:
        """Return the attached counts.

        :return: The attached counts, or ``None`` when unstated.
        """
        return self._record.nattached


    @property

[docs]
    def original_name(self) -> str | None:
        """Return the original source name.

        :return: The original name, or ``None`` when unstated.
        """
        return self._record.original_name



[docs]
    def unwrap(self) -> SpeciesRecord:
        """Return the stored species record.

        :return: The source record.
        """
        return self._record