httk.atomistic ============== .. py:module:: httk.atomistic .. autoapi-nested-parse:: Provide crystal structure representations for httk v2. Provides the UnitcellStructure domain and its component families (Cell, Sites, Species), each following the httk-core view/backend pattern. A UnitcellStructure holds a ``cell``, a ``sites``, a tuple of ``species``, and a ``species_at_sites``; each component has a class representation and a primitive representation convertible through views. Crystal symmetry is modelled exactly over the rationals: :class:`Spacegroup` carries a space-group *setting* with its symmetry operations and Wyckoff table, and :class:`SettingTransform` relates any setting to the International Tables standard one, so a structure in an arbitrary non-standard setting can be represented without loss. The underlying tables ship in :mod:`httk.atomistic.data`. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/autoapi/httk/atomistic/cif_structures/index /reference/autoapi/httk/atomistic/cli/index /reference/autoapi/httk/atomistic/composition/index /reference/autoapi/httk/atomistic/data/index /reference/autoapi/httk/atomistic/elements/index /reference/autoapi/httk/atomistic/entries/index /reference/autoapi/httk/atomistic/integrations/index /reference/autoapi/httk/atomistic/io/index /reference/autoapi/httk/atomistic/mcif_structures/index /reference/autoapi/httk/atomistic/models/index /reference/autoapi/httk/atomistic/reduction/index /reference/autoapi/httk/atomistic/storage/index /reference/autoapi/httk/atomistic/supercell/index /reference/autoapi/httk/atomistic/symmetry/index /reference/autoapi/httk/atomistic/wavefunction/index Attributes ---------- .. autoapisummary:: httk.atomistic.CellLike httk.atomistic.SitesLike httk.atomistic.SiteMomentsLike httk.atomistic.SpeciesLike httk.atomistic.StructureLike httk.atomistic.TrajectoryLike httk.atomistic.ChemicalFormulaLike httk.atomistic.AnonymousFormula httk.atomistic.AnonymousFormulaView httk.atomistic.StructuretypeLike httk.atomistic.AnonymousStructure httk.atomistic.AnonymousStructureView httk.atomistic.AnonymousStructureLike httk.atomistic.ProtostructureLike httk.atomistic.PrototypeLike httk.atomistic.DEFAULT_TOLERANCE Classes ------- .. autoapisummary:: httk.atomistic.Cell httk.atomistic.CellParams httk.atomistic.CellParamsView httk.atomistic.CellView httk.atomistic.Sites httk.atomistic.SitesView httk.atomistic.CartesianSiteMoments httk.atomistic.CartesianSiteMomentsView httk.atomistic.CollinearSiteMoments httk.atomistic.CrystalAxisSiteMoments httk.atomistic.CrystalAxisSiteMomentsView httk.atomistic.PlainSpeciesView httk.atomistic.Species httk.atomistic.SpeciesView httk.atomistic.ASEAtoms httk.atomistic.ASEAtomsProtocol httk.atomistic.PymatgenStructure httk.atomistic.PymatgenStructureProtocol httk.atomistic.VASPStructure httk.atomistic.VASPTrajectory httk.atomistic.ASUStructure httk.atomistic.FundamentalDomainStructure httk.atomistic.WyckoffSite httk.atomistic.ASUStructureView httk.atomistic.DatastreamStructure httk.atomistic.ModulatedStructure httk.atomistic.NumericUnitcellStructureView httk.atomistic.OptimadeStructure httk.atomistic.PlainStructureView httk.atomistic.StructureSymmetry httk.atomistic.SymopsStructure httk.atomistic.UnitcellStructure httk.atomistic.UnitcellStructureView httk.atomistic.JsonlTrajectory httk.atomistic.PlainTrajectory httk.atomistic.Trajectory httk.atomistic.TrajectoryView httk.atomistic.PlaneWaveFunctions httk.atomistic.StructureEntry httk.atomistic.StructureEntryProvider httk.atomistic.TrajectoryEntry httk.atomistic.TrajectoryEntryProvider httk.atomistic.ASUStructureRecord httk.atomistic.FundamentalDomainTemplateRecord httk.atomistic.FundamentalDomainStructureRecord httk.atomistic.ProtostructureRecord httk.atomistic.PrototypeRecord httk.atomistic.UnitcellStructureRecord httk.atomistic.ObservableSummaryRecord httk.atomistic.TrajectoryRecord httk.atomistic.WyckoffOccupationRecord httk.atomistic.Formulatype httk.atomistic.FormulatypeView httk.atomistic.Composition httk.atomistic.CompositionView httk.atomistic.ChemicalFormula httk.atomistic.ChemicalFormulaView httk.atomistic.Structuretype httk.atomistic.StructuretypeView httk.atomistic.ASUTemplate httk.atomistic.FundamentalDomainTemplate httk.atomistic.FundamentalDomainTemplateView httk.atomistic.ProtostructureLabel httk.atomistic.WyckoffOccupation httk.atomistic.Protostructure httk.atomistic.ProtostructureView httk.atomistic.PrototypeLabel httk.atomistic.PrototypeOccupation httk.atomistic.Prototype httk.atomistic.PrototypeView httk.atomistic.AffineOperation httk.atomistic.SettingTransform httk.atomistic.Spacegroup httk.atomistic.PrimitiveCellResult httk.atomistic.ConventionalCellResult httk.atomistic.SubgroupRepresentationResult httk.atomistic.LiftResult httk.atomistic.StructurePath httk.atomistic.WyckoffPosition httk.atomistic.Assembly httk.atomistic.ChemicalComposition httk.atomistic.SupercellResult httk.atomistic.NiggliReducedStructureResult httk.atomistic.NiggliReductionResult Functions --------- .. autoapisummary:: httk.atomistic.same_crystal httk.atomistic.save_vesta httk.atomistic.wavefunction_overlap httk.atomistic.validate_structure_record httk.atomistic.find_magnetic_symmetry httk.atomistic.recognize_asu httk.atomistic.structure_tolerance httk.atomistic.wyckoff_letter_map httk.atomistic.primitive_cell httk.atomistic.conventional_cell httk.atomistic.maximal_subgroups httk.atomistic.minimal_supergroups httk.atomistic.subgroup_closure httk.atomistic.subgroup_representation httk.atomistic.supergroup_closure httk.atomistic.canonical_asu httk.atomistic.backward_lift httk.atomistic.canonicalize httk.atomistic.highest_symmetry httk.atomistic.lift_candidates httk.atomistic.normalize_chirality httk.atomistic.rerepresent httk.atomistic.canonicalize_full httk.atomistic.interpolate_structures httk.atomistic.list_representations httk.atomistic.represent_like httk.atomistic.structure_delta httk.atomistic.wyckoff_positions httk.atomistic.asu_structure_from_cif httk.atomistic.asu_structures_from_cif httk.atomistic.cif_setting httk.atomistic.atomic_number httk.atomistic.symbol_of httk.atomistic.build_supercell httk.atomistic.cubic_supercell httk.atomistic.orthogonal_supercell httk.atomistic.is_niggli_reduced httk.atomistic.niggli_reduce httk.atomistic.niggli_reduced Package Contents ---------------- .. py:class:: Cell(basis, scale = 1, precision = None, periodicity = None) Bases: :py:obj:`httk.atomistic.models.cell.backend.CellBackend` A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held **exactly**. The lattice vectors are the rows of ``basis``. Internally a Cell factors that basis into a positive :class:`~httk.core.SurdScalar` ``scale`` times an ``unscaled_basis`` (a :class:`~httk.core.SurdVector` of shape ``(3, 3)``), with ``basis == scale * unscaled_basis``. The split lets an overall length factor be carried symbolically: a hexagonal cell of lattice parameter ``a`` and ratio ``c/a`` is the exact ``unscaled`` rows ``(1, 0, 0)``, ``(-1/2, sqrt(3)/2, 0)``, ``(0, 0, c/a)`` scaled by ``a`` — so the ``sqrt(3)`` stays exact regardless of ``a``. A cell built from an absolute basis simply has ``scale == 1``. Numbers embed exactly: rationals (and rational-valued floats) stay rational, and a :class:`~httk.core.SurdVector` basis keeps its radicals. Derived quantities retain exact forms where the underlying operation stays in the supported exact fields, including the usual metric-rational crystallographic case: ``lengths`` use :meth:`~httk.core.SurdVector.sqrt_of` for rational squared row lengths when the rational radicand is a perfect square or stays below the deterministic small-radicand threshold, ``angles`` (degrees) use the exact reverse-Niven :meth:`~httk.core.SurdScalar.acos_degrees` where possible, ``volume`` comes from the exact determinant, and ``metric`` is the exact Gram matrix, which may itself contain surds. For larger rational or irrational squared lengths, ``lengths``/``angles`` fall back to a deterministic rational approximation (documented per accessor). Exact accessors return vector objects — render them with ``.to_floats()`` (nested plain-float lists, numpy-free), ``float(...)`` on scalars, :meth:`numeric` (true numpy arrays), or a view of your choice. A cell also records its :attr:`periodicity`, which defaults to periodic in all three directions. Where it is not, the basis stops being purely a lattice and becomes partly a *coordinate frame*: see :attr:`periodicity` for what that means and :attr:`periodic_measure` for the quantity that replaces :attr:`volume`. :param basis: The three cell vectors, one per row. :param scale: The positive factor separated from ``basis``. :param precision: The absolute precision carried from the source, if known. :param periodicity: Flags identifying which basis rows are lattice translations. .. py:property:: scale :type: httk.core.SurdScalar The overall (strictly positive) length factor. :return: The factor applied to ``unscaled_basis``. .. py:property:: unscaled_basis :type: httk.core.SurdVector The 3x3 cell vectors before applying ``scale``. :return: The unscaled lattice vectors. .. py:property:: basis :type: httk.core.SurdVector The 3x3 lattice vectors ``scale * unscaled_basis``. :return: The scaled lattice vectors. .. py:property:: precision :type: fractions.Fraction | None How precisely this basis was stated, as an absolute length, or ``None`` if unknown. In the same units as the basis itself, so for ordinary crystallographic data it is an ångström. Derived from the source's written digits and any stated uncertainty — a CIF cell edge of ``5.6402(3)`` is precise to ``3e-4``, not to the ``1e-4`` its four decimals alone would suggest. ``None`` means unknown, which is not the same as exact. It is what a cell built by hand or from a bare matrix reports. :return: The absolute precision, or ``None`` when it is unknown. .. py:property:: periodicity :type: tuple[bool, bool, bool] Which of the three basis rows is a genuine lattice translation. ``(True, True, True)`` — the default, and what every ordinary crystal is. A slab is ``(True, True, False)``, a nanowire has one ``True``, and an isolated molecule is ``(False, False, False)``. A row flagged ``False`` is **not** a lattice vector. It is only a frame: it says what a fractional coordinate means along that direction, and nothing more. Coordinates there are unbounded — freely below 0 or above 1 — and are never wrapped into ``[0, 1)``. There is no vacuum and no padding involved, so making that row a unit vector simply means the coordinate along it *is* a length in the basis's units. This is the same notion, in the same order, as OPTIMADE's ``dimension_types``. :return: Flags identifying the periodic basis rows. .. py:property:: nperiodic_dimensions :type: int How many of the three directions are periodic. :return: The number of periodic directions. .. py:method:: numeric() Return a plain-numpy presentation of this cell. :return: The numpy-backed presentation. :raises ImportError: If numpy is unavailable. .. py:method:: metric() Return the exact, potentially surd-valued Gram matrix ``matrix * matrix^T``. :return: The Gram matrix of the cell vectors. .. py:property:: lengths :type: tuple[httk.core.SurdScalar, ...] The lengths of the three cell vectors (the scaled row norms). Exact via :meth:`~httk.core.SurdVector.sqrt_of` when the row's squared length is a perfect-square rational or a rational with numerator times denominator at most ``10**18``. Larger rational radicands and irrational squared lengths use a deterministic rational approximation at ``_FALLBACK_PREC``. :return: The three cell-vector lengths. .. py:property:: angles :type: tuple[fractions.Fraction, ...] The cell angles ``(alpha, beta, gamma)`` in degrees, as exact ``Fraction`` values. Following the crystallographic convention, ``alpha`` is the angle between rows ``b`` and ``c``, ``beta`` between ``a`` and ``c``, and ``gamma`` between ``a`` and ``b``. Angles are scale-independent, so they are computed from the unscaled basis. The cosine is formed exactly in the surd field and reversed through the Niven table (:meth:`~httk.core.SurdScalar.acos_degrees`) for an exact answer; a non-Niven angle falls back to a deterministic :func:`~httk.core.exactmath.acos` at ``_FALLBACK_PREC``. :return: ``(alpha, beta, gamma)`` in degrees. .. py:property:: volume :type: httk.core.SurdScalar The cell volume, the exact absolute determinant of ``basis``. Defined only for a fully periodic cell, and raises :class:`ValueError` otherwise. For anything less, the determinant mixes real lattice vectors with frame vectors, so it is not a volume: it changes when a frame vector is rescaled, even though nothing about the material did. Any density or packing fraction derived from it would inherit that. See :attr:`periodic_measure` for the quantity that *is* defined. :return: The absolute determinant of the basis. :raises ValueError: If the cell is not periodic in all three directions. .. py:property:: periodic_measure :type: httk.core.SurdScalar The size of the repeating unit, whatever its dimension. A volume for a crystal, an area for a slab, a length for a nanowire. For a fully non-periodic cell there is no repeating unit and this is the empty product, ``1``, which is dimensionless rather than a length of any kind. Exact in the crystallographic case. The 3D case is the determinant and needs no square root at all; the 2D and 1D cases take the same square root that :attr:`lengths` does, so they are exact whenever the squared measure is a rational with a small radicand and fall back to a deterministic rational approximation otherwise. :return: The measure of the periodic sublattice. .. py:type:: CellLike :canonical: httk.atomistic.models.cell.backend.CellBackend | httk.atomistic.models.cell.view_base.CellViewBase | httk.atomistic.models.cell.cell.Cell | httk.core.VectorLike .. py:class:: CellParams(obj, **hints) Bases: :py:obj:`httk.atomistic.models.cell.backend.CellBackend` Backend for a cell backed by cell parameters ``(a, b, c, alpha, beta, gamma)``. The native representation is a flat length-6 vector-like of the cell-vector lengths ``a``/``b``/``c`` and the angles ``alpha``/``beta``/``gamma`` in degrees, stored as exact :class:`~fractions.Fraction` values (parsed via :func:`~httk.core.exactmath.any_to_fraction`). The exact ``basis`` is derived lazily and cached using the standard crystallographic orientation convention (first cell vector along x, second in the xy-plane); for the common Niven angles it is exact (radicals intact). Since parameters carry no separate length factor, ``scale`` is the exact ``1`` and ``unscaled_basis == basis``. Parameters carry neither orientation nor periodicity, so a cell → parameters → cell round-trip reproduces lengths and angles, and reproduces volume only for a fully periodic source. Reconstruction uses the fully periodic default and therefore discards any non-3D periodicity as well as the original orientation. ``unwrap`` returns the original raw object. :param obj: The six cell parameters in crystallographic order. :param \**hints: Backend-selection hints. .. py:property:: basis :type: httk.core.SurdVector Return the basis derived from the stored parameters. :return: The standard-orientation cell vectors. .. py:property:: scale :type: httk.core.SurdScalar Return the unit scale factor. :return: The factor applied to ``unscaled_basis``. .. py:property:: unscaled_basis :type: httk.core.SurdVector Return the parameter-derived basis before scaling. :return: The cell vectors. .. py:property:: precision :type: fractions.Fraction | None Return the source precision supplied with these cell parameters. :return: The absolute length precision, or ``None`` when unstated. .. py:property:: lengths :type: tuple[httk.core.SurdScalar, ...] Return the natively stored cell-vector lengths. :return: The exact stored ``a``, ``b``, and ``c`` lengths. .. py:property:: angles :type: tuple[fractions.Fraction, ...] Return the natively stored cell angles in degrees. :return: The exact stored ``alpha``, ``beta``, and ``gamma`` angles. .. py:property:: params :type: tuple[fractions.Fraction, ...] The stored ``(a, b, c, alpha, beta, gamma)`` in degrees. :return: The exact cell parameters. .. py:method:: unwrap() Return the original parameter object. :return: The raw parameter representation. .. py:class:: CellParamsView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.cell.view_base.CellViewBase`, :py:obj:`tuple` A view presenting an underlying cell backend as cell parameters. This view is a genuine flat 6-tuple ``(a, b, c, alpha, beta, gamma)`` with the angles in degrees, built eagerly and immutable, with the elements also available as the named properties ``a``/``b``/``c``/``alpha``/``beta``/``gamma``. Parameters carry no orientation, so converting a cell to parameters is lossy: reconstructing a cell from this view reproduces the lengths and angles, and reproduces volume only for a fully periodic source. The reconstruction inherits the fully periodic default, so this view discards the source periodicity as well as the original cell-vector orientation. :param obj: The cell-like object to present. :param \**hints: Backend-selection hints. .. py:property:: a :type: float The length of the first cell vector. :return: The first vector length. .. py:property:: b :type: float The length of the second cell vector. :return: The second vector length. .. py:property:: c :type: float The length of the third cell vector. :return: The third vector length. .. py:property:: alpha :type: float The angle between the second and third cell vectors, in degrees. :return: The alpha angle. .. py:property:: beta :type: float The angle between the first and third cell vectors, in degrees. :return: The beta angle. .. py:property:: gamma :type: float The angle between the first and second cell vectors, in degrees. :return: The gamma angle. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the presented parameters as a plain tuple. :return: The six cell parameters. .. py:class:: CellView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.cell.view_base.CellViewBase`, :py:obj:`httk.atomistic.models.cell.cell.Cell` A view presenting an underlying cell backend as a ``Cell``. This view is a genuine ``Cell``, so it can be passed anywhere a Cell is accepted. Its state is built lazily on first access from the backend. :param obj: The cell-like object to present. :param \**hints: Backend-selection hints. .. py:property:: lengths :type: tuple[httk.core.SurdScalar, ...] Present the backend's native cell-vector lengths without re-deriving them. :return: The three exact or backend-native cell-vector lengths. .. py:property:: angles :type: tuple[fractions.Fraction, ...] Present the backend's native crystallographic angles without re-deriving them. :return: The three cell angles in degrees. .. py:method:: basis_floats() Present the backend's native float basis when it has one, else the validated exact basis as floats. :return: The three lattice vectors as float rows. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return this presentation as a standalone cell. The original backend remains available through :meth:`unwrap`. For a parameter backend with a non-special angle, the standalone basis uses that backend's documented deterministic rational approximation. :return: The standalone basis representation. .. py:type:: SitesLike :canonical: httk.atomistic.models.sites.backend.SitesBackend | httk.atomistic.models.sites.view_base.SitesViewBase | httk.atomistic.models.sites.sites.Sites | httk.core.VectorLike .. py:class:: Sites(reduced_coords, precision = None) Bases: :py:obj:`httk.atomistic.models.sites.backend.SitesBackend` The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held **exactly**. Reduced (fractional) coordinates are the symmetry-native frame: point-group operations are integer matrices and translations are rationals, so no radicals ever appear. They are therefore stored as an exact rational :class:`~httk.core.FracVector` of shape ``(N, 3)``. A Sites object is iterable and indexable over its length-3 coordinate rows (each a ``FracVector``), with ``len`` giving the number of sites. Inputs embed exactly: rationals (and rational-valued floats), rational strings, and numpy arrays all land on their exact rational value. An irrational :class:`~httk.core.SurdVector` input is rejected; the exact Cartesian frame — where radicals belong — is obtained instead via :meth:`~httk.atomistic.UnitcellStructure.cartesian_sites`. :param reduced_coords: The reduced coordinates, one site per row. :param precision: The fractional precision carried from the source, if known. .. py:property:: reduced_coords :type: httk.core.FracVector The Nx3 reduced site coordinates as an exact ``FracVector`` (one site per row). .. py:property:: precision :type: fractions.Fraction | None How precisely these coordinates were stated, in fractional units, or ``None``. Fractional and therefore dimensionless: reduced coordinates are fractions of a cell edge, and a ``Sites`` carries no cell to convert with. Use :meth:`~httk.atomistic.UnitcellStructure.cartesian_precision` for the corresponding length, which is the number an interatomic tolerance or an spglib ``symprec`` actually wants. It is the *coarsest* precision among the coordinates, since a structure is only as precisely stated as its least precisely stated number. ``None`` means unknown. :return: The fractional precision, or ``None`` when unknown. .. py:method:: numeric() Return a plain-numpy presentation of these sites. :return: The numpy-backed presentation. :raises ImportError: If numpy is unavailable. .. py:class:: SitesView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.sites.view_base.SitesViewBase`, :py:obj:`httk.atomistic.models.sites.sites.Sites` A view presenting an underlying sites backend as a ``Sites`` object. This view is a genuine ``Sites``, so it can be passed anywhere a Sites is accepted. Its state is built lazily on first access from the backend. :param obj: The sites-like object to present. :param \**hints: Backend-selection hints. .. py:method:: reduced_coords_floats() Present the backend's native float coordinates, else the validated exact ones. :return: The reduced coordinates as float rows. .. py:property:: num_sites :type: int Return the number of coordinate rows without forcing the exact fill when unfilled. :return: The number of sites. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return this presentation as standalone exact sites. :return: The exact sites representation. .. py:class:: CartesianSiteMoments(moments, precision = None) Bases: :py:obj:`httk.atomistic.models.moments.backend.SiteMomentsBackend` Per-site Cartesian magnetic moments, exactly held in Bohr magnetons. .. py:attribute:: kind :value: 'cartesian' .. py:property:: cartesian_moments :type: httk.core.SurdVector The exact Nx3 Cartesian moments, one row per site. .. py:property:: precision :type: fractions.Fraction | None How precisely the moments were stated, in Bohr magnetons, or ``None``. Concrete rather than abstract, so a backend with no source of precision inherits ``None`` instead of breaking. .. py:class:: CartesianSiteMomentsView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.moments.view_base.SiteMomentsViewBase`, :py:obj:`httk.atomistic.models.moments.cartesian.CartesianSiteMoments` A lazy Cartesian site-moments presentation of any site-moments backend. .. py:method:: unview() Return the view's presented representation as a plain, non-View instance. Concrete views that mimic a value type override this to shed the httk wrapper; the result may alias the view's storage (no copy is promised). The default raises ``TypeError``, which is the correct behavior for views that only adapt an interface and have no faithful standalone value. :return: The presented value as a plain, non-View instance. :raises TypeError: If this interface-only view has no standalone plain value. .. py:class:: CollinearSiteMoments(moments, precision = None) Bases: :py:obj:`httk.atomistic.models.moments.backend.SiteMomentsBackend` Signed per-site scalar moments with no assigned Cartesian axis. .. py:attribute:: kind :value: 'collinear' .. py:property:: collinear_moments :type: httk.core.FracVector The exact signed scalar moment for each site. .. py:property:: cartesian_moments :type: httk.core.SurdVector .. py:property:: precision :type: fractions.Fraction | None How precisely the moments were stated, in Bohr magnetons, or ``None``. Concrete rather than abstract, so a backend with no source of precision inherits ``None`` instead of breaking. .. py:class:: CrystalAxisSiteMoments(moments, cell, precision = None) Bases: :py:obj:`httk.atomistic.models.moments.backend.SiteMomentsBackend` Moments along the unit lattice axes ``â``, ``b̂``, ``ĉ``, in Bohr magnetons. .. py:attribute:: kind :value: 'crystalaxis' .. py:property:: crystalaxis_moments :type: httk.core.SurdVector The exact Nx3 moments along the cell's unit lattice axes. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell The cell defining the crystal-axis frame. .. py:property:: cartesian_moments :type: httk.core.SurdVector The exact Cartesian moments, using rows ``moments * U``. .. py:property:: precision :type: fractions.Fraction | None How precisely the moments were stated, in Bohr magnetons, or ``None``. Concrete rather than abstract, so a backend with no source of precision inherits ``None`` instead of breaking. .. py:class:: CrystalAxisSiteMomentsView(obj, *, cell = None, **hints) Bases: :py:obj:`httk.atomistic.models.moments.view_base.SiteMomentsViewBase`, :py:obj:`httk.atomistic.models.moments.crystalaxis.CrystalAxisSiteMoments` A lazy crystal-axis site-moments presentation with an eagerly checked frame hint. .. py:method:: unview() Return the view's presented representation as a plain, non-View instance. Concrete views that mimic a value type override this to shed the httk wrapper; the result may alias the view's storage (no copy is promised). The default raises ``TypeError``, which is the correct behavior for views that only adapt an interface and have no faithful standalone value. :return: The presented value as a plain, non-View instance. :raises TypeError: If this interface-only view has no standalone plain value. .. py:type:: SiteMomentsLike :canonical: httk.atomistic.models.moments.backend.SiteMomentsBackend | httk.atomistic.models.moments.view_base.SiteMomentsViewBase .. py:type:: SpeciesLike :canonical: httk.atomistic.models.species.backend.SpeciesBackend | httk.atomistic.models.species.view_base.SpeciesViewBase | httk.atomistic.models.species.species.Species | dict[str, Any] | str | int .. py:class:: PlainSpeciesView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.species.view_base.SpeciesViewBase`, :py:obj:`dict` A view presenting an underlying species backend as an OPTIMADE species dict. This view is a genuine ``dict`` carrying the OPTIMADE ``species`` fields (optional fields that are ``None`` are omitted; list-valued fields are plain lists). Unlike the immutable-subclass views, a dict is mutable, so this view is a detached copy: mutating it does not affect the underlying backend. :param obj: The species-like object to present. :param \**hints: Backend-selection hints. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the presented species as a plain mapping. :return: The detached presentation mapping. .. py:class:: Species(name, chemical_symbols, concentration, mass = None, original_name = None, attached = None, nattached = None, concentration_precision = None, charges = None, spins = None, labels = None) Bases: :py:obj:`httk.atomistic.models.species.backend.SpeciesBackend` A chemical species occupying one or more sites, mirroring the OPTIMADE ``species`` object. A species has a ``name`` (unique within a structure; it need not be a chemical symbol), a list of ``chemical_symbols`` composing it, and a matching list of non-negative ``concentration`` values. Concentrations on represented sites must lie in ``[0, 1]``; an unrepresented species may instead carry an aggregate implicit-atom count. Each chemical symbol is an element symbol, or one of the pseudo-symbols ``"X"`` (unknown) or ``"vacancy"``. The optional ``mass``, ``attached``, ``nattached``, and ``original_name`` fields carry the remaining OPTIMADE species information; ``attached`` and ``nattached`` must be given together and share their length. ``charges``, ``spins``, and ``labels`` are optional aligned decorations. An all-``None`` decoration is canonicalized to ``None``. Repeated chemical symbols are accepted only when the complete decoration distinguishes them. :param name: The species name. :param chemical_symbols: The constituent chemical symbols. :param concentration: The constituent occupancies. :param mass: The constituent masses, if stated. :param original_name: The source name, if stated. :param attached: The attached constituent symbols, if stated. :param nattached: The counts corresponding to ``attached``, if stated. :param concentration_precision: The precision of each occupancy, if stated. :param charges: The charge decoration, if stated. :param spins: The spin decoration, if stated. :param labels: The label decoration, if stated. .. py:attribute:: name :type: str :value: '' .. py:attribute:: chemical_symbols :type: tuple[str, ...] :value: () .. py:attribute:: concentration :type: tuple[fractions.Fraction, ...] :value: () .. py:attribute:: mass :type: tuple[float, ...] | None :value: None .. py:attribute:: original_name :type: str | None :value: None .. py:attribute:: attached :type: tuple[str, ...] | None :value: None .. py:attribute:: nattached :type: tuple[int, ...] | None :value: None .. py:attribute:: concentration_precision :type: tuple[fractions.Fraction | None, ...] | None :value: None .. py:attribute:: charges :type: tuple[fractions.Fraction | None, ...] | None :value: None Assigned charge numbers for the constituents, or ``None`` if unstated. A ``None`` element means the charge of that constituent is unstated; whole- ``None`` means no constituent charges are stated. Values use elementary-charge units, for example a formal oxidation state. :return: The constituent charges, or ``None`` when unstated. .. py:attribute:: spins :type: tuple[fractions.Fraction | None, ...] | None :value: None Idealized signed spins assigned to the constituents, or ``None`` if unstated. A ``None`` element means the spin of that constituent is unstated; whole-``None`` means no constituent spins are stated. This is distinct from a calculated site magnetic moment. :return: The constituent spins, or ``None`` when unstated. .. py:attribute:: labels :type: tuple[str | None, ...] | None :value: None Free-form per-constituent labels, or ``None`` if unstated. A ``None`` element means that constituent has no stated label; whole-``None`` means no constituent labels are stated. :return: The constituent labels, or ``None`` when unstated. .. py:property:: normalized :type: bool Whether the stated concentration interval contains one. :return: Whether the concentrations are normalized within their precision. .. py:property:: normalization_status :type: str Report the concentration normalization status. :return: ``exact``, ``within_precision``, or ``outside_precision``. .. py:property:: normalization_diagnostic :type: Any Return a structured normalization diagnostic when needed. :return: The diagnostic, or ``None`` when the concentrations are normalized. .. py:property:: is_single_element :type: bool Whether this species is a single, unattached, real chemical element. True only for a species composed of exactly one element symbol (not ``"X"`` or ``"vacancy"``) with no attached particles. Such species are the ones that can be represented as a bare atomic number in the primitive representation. :return: Whether this is a single real element. .. py:method:: without_charges() Return an EXPLICIT lossy projection that drops declared oxidation states. The other species fields, including spins and labels, are preserved. A species without declared charges is returned by identity. :return: A charge-free species, or this species when already charge-free. .. py:method:: from_object(obj, **hints) :classmethod: Return a Species from an existing Species, bare symbol or atomic number, or OPTIMADE species dict. A bare element symbol, ``"X"``, or ``"vacancy"`` denotes a fully occupied single-symbol species. A bare atomic number denotes the corresponding element. :param obj: An existing species, symbol, atomic number, or species mapping. :param \**hints: Backend-selection hints. :return: The canonical species. :raises ValueError: If an atomic number is boolean or the input is invalid. .. py:class:: SpeciesView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.species.view_base.SpeciesViewBase`, :py:obj:`httk.atomistic.models.species.species.Species` A view presenting an underlying species backend as a ``Species``. This view is a genuine frozen ``Species``, so it can be passed anywhere a Species is accepted. Its fields are built eagerly from the backend on construction, with full ``Species`` validation applied at that point. :param obj: The species-like object to present. :param \**hints: Backend-selection hints. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return this presentation as standalone species. :return: The exact species representation. .. py:class:: ASEAtoms(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Import ASE ``Atoms`` and compatible duck-typed objects. Conversion is eager because reading the four methods and normalizing their values is real work. The original object remains available through :meth:`unwrap`. Initial magnetic moments become site moments and nonzero initial charges become charged single-element species. All-zero ASE defaults remain unstated. :param obj: An ASE ``Atoms`` object or compatible duck-typed object. :param \**hints: Backend-selection hints. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the exact cell converted from native cell rows. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Return the exact reduced coordinates converted from native positions. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return distinct single-element species in first-appearance order. .. py:property:: species_at_sites :type: tuple[str, ...] Return the species name occupying each site. .. py:property:: site_moments :type: Any Return per-site moments, or ``None`` for absent and all-zero ASE defaults. .. py:method:: unwrap() Return the original ``Atoms``-like object. .. py:class:: ASEAtomsProtocol Bases: :py:obj:`Protocol` Describe the minimal method surface needed to read ASE ``Atoms``. This is a runtime-checkable, duck-typed protocol. ASE is not required: any object providing these four methods qualifies for :class:`ASEAtoms`. .. py:method:: get_cell() Return the cell vectors as rows. :return: The native cell rows. .. py:method:: get_scaled_positions() Return the reduced positions. :return: One reduced coordinate row per site. .. py:method:: get_atomic_numbers() Return one atomic number per site. :return: The atomic numbers. .. py:method:: get_pbc() Return one periodicity flag per cell row. :return: The periodicity flags. .. py:class:: PymatgenStructure(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Import a pymatgen-compatible structure eagerly. Pymatgen ``properties``, site labels, and site properties other than ``magmom`` are intentionally discarded because they have no exact httk structure-family counterpart. Pymatgen ``DummySpecies`` values with the default zero oxidation state are imported with an unstated charge because pymatgen cannot distinguish that default from an explicitly supplied zero; nonzero dummy oxidation states remain exact charges. Partial occupancy and its exact ``Fraction`` values are retained. An occupancy shortfall becomes an explicit vacancy constituent, which views omit when exporting to pymatgen. The original object remains available through :meth:`unwrap`. :param obj: A pymatgen ``Structure`` object or compatible duck-typed object. :param \**hints: Backend-selection hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'pymatgen' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the converted cell and periodicity. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Return the converted reduced coordinates. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the imported distinct species and occupancies. .. py:property:: species_at_sites :type: tuple[str, ...] Return the imported species name at each site. .. py:property:: site_moments :type: Any Return imported collinear or Cartesian site moments, if present. .. py:property:: charge :type: fractions.Fraction | None Return the exact structure charge, or ``None`` when unstated. .. py:method:: unwrap() Return the original pymatgen-compatible object. .. py:class:: PymatgenStructureProtocol Bases: :py:obj:`Protocol` The three native attributes that identify a pymatgen structure. ``lattice`` supplies the cell and periodicity, ``frac_coords`` supplies the reduced coordinates, and ``species_and_occu`` supplies one per-site composition mapping. This small surface is disjoint from ASE ``Atoms`` and httk structure objects while allowing pymatgen-compatible duck-typed inputs without importing pymatgen. .. py:attribute:: lattice :type: Any .. py:attribute:: frac_coords :type: Any .. py:attribute:: species_and_occu :type: Any .. py:class:: VASPStructure(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Load a VASP POSCAR structure lazily. This backend is explicitly constructed because a generic structure source should not silently claim every POSCAR path. It is not registered in ``backend_classes``. Constructing it from a view whose unwrapped value is already a ``VASPStructure`` returns that backend by identity. The payload's ``raw`` channel preserves the source representation for byte-exact saving. :param obj: A POSCAR path, neutral payload, or serializer-supported source. :param \**hints: Backend-selection hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'vasp' .. py:property:: payload :type: collections.abc.Mapping[str, Any] Return the original, loaded, or synthesized neutral POSCAR payload. .. py:property:: comment :type: Any Return the POSCAR comment, if present. .. py:property:: selective_dynamics :type: Any Return selective-dynamics flags, if present. .. py:method:: resolve() Build and memoize the canonical structure from the POSCAR payload. :return: The resolved unit-cell structure. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the resolved cell. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Return the resolved reduced coordinates. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the resolved distinct species. .. py:property:: species_at_sites :type: tuple[str, ...] Return the resolved species name at each site. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Return resolved site moments, or ``None``. .. py:property:: charge :type: Any Return the resolved structure charge, if present. .. py:method:: unwrap() Return the original POSCAR source. .. py:class:: VASPTrajectory(source, **hints) Bases: :py:obj:`httk.atomistic.models.trajectory.backend.TrajectoryBackend` Read VASP OUTCAR and/or XDATCAR data lazily. XDATCAR supplies geometry when present. OUTCAR observables use the per-frame ``energy_sigma0``, parsed as a float, plus temperature and ``stress_gpa_voigt()``. One bounded pass caches those three scalar/6-tuple sequences; frame geometry is never cached. XDATCAR geometry is preferred when both files are available. Cartesian coordinates are reduced exactly against the frame cell. A mismatch between OUTCAR and XDATCAR frame counts raises an error. :param source: A VASP trajectory path, directory, payload, or VASP-outputs-like object. :param \**hints: Backend-selection hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'vasp' .. py:property:: nframes :type: int Return the validated number of frames. .. py:property:: species :type: tuple[Any, ...] Return the composition inferred from POSCAR, XDATCAR, or OUTCAR. .. py:property:: species_at_sites :type: tuple[str, ...] Return the species name at each site. .. py:property:: reference_frames :type: None Return ``None`` because VASP frames are not bounded references. .. py:method:: frame(i) Read one VASP frame by index. :param i: Frame index; negative indexes count from the end. :return: The requested unit-cell structure. :raises IndexError: If the frame index is out of range. :raises ValueError: If the source has no complete frame geometry. .. py:method:: frames() Stream VASP frame geometry without caching full frames. :yields: Unit-cell structures in source order. .. py:property:: observable_names :type: tuple[str, ...] Return available OUTCAR observable names. .. py:method:: observable(name) Return one OUTCAR observable in frame order. :param name: Observable name. :return: The observable values. :raises KeyError: If the observable is unavailable. .. py:method:: unwrap() Return the original VASP trajectory source. .. py:property:: source_locator :type: str | None Return the source path, if one is available. .. py:class:: ASUStructure(cell, spacegroup, wyckoff_sites, species, transform = None, coordinate_precision = None, *, molecular = False, assemblies = None, chemical_composition = None, chemical_formula_descriptive = None, chemical_formula_hill = None, optimization_type = None, immutable_id = None, last_modified = None, charge = None, _validated_proof = None) Bases: :py:obj:`FundamentalDomainStructure` Assert that a fundamental domain is a true asymmetric unit. .. py:property:: site_coordinate_span :type: str Expose the asymmetric-unit coordinate span. .. py:class:: FundamentalDomainStructure(cell, spacegroup, wyckoff_sites, species, transform = None, coordinate_precision = None, *, molecular = False, assemblies = None, chemical_composition = None, chemical_formula_descriptive = None, chemical_formula_hill = None, optimization_type = None, immutable_id = None, last_modified = None, charge = None, _validated_proof = None) Bases: :py:obj:`httk.atomistic.models.structure.semantics.StructureSemanticsMixin`, :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Represent a crystal structure by one exact site per symmetry orbit. Holds the cell in the structure's own setting, the space-group setting that names its Wyckoff data, an optional transform from that setting to the structure's own, one :class:`WyckoffSite` per symmetry-distinct site, and the species they name. On first expansion, a site whose orbit contributes no new points raises ``ValueError`` because it duplicates an earlier site's orbit. :param cell: The cell in the structure's own setting. :param spacegroup: The setting that names the stored Wyckoff data. :param wyckoff_sites: The symmetry-distinct site definitions. :param species: The species referenced by the site definitions. :param transform: The change of basis from the stored setting to the structure's setting. :param coordinate_precision: The precision recorded for the reduced coordinates. :param molecular: Whether the structure describes molecular entities. :param assemblies: Optional correlations among domain sites. :param chemical_composition: Optional chemical composition metadata. :param chemical_formula_descriptive: Optional descriptive chemical formula. :param chemical_formula_hill: Optional Hill chemical formula. :param optimization_type: Optional optimization provenance. :param immutable_id: Optional immutable source identifier. :param last_modified: Optional source modification timestamp. :param charge: An explicitly assigned charge for the expanded cell content; it is not derived from the species. :param _validated_proof: Internal proof that the supplied CIF expansion already validates the representatives. .. py:attribute:: kind :type: ClassVar[str] :value: 'asu' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Expose the cell in the structure's own setting. .. py:property:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup Expose the setting that names the stored Wyckoff data. .. py:property:: transform :type: httk.atomistic.symmetry.setting_transform.SettingTransform Expose the transform from the stored setting to the structure's setting. .. py:property:: transform_from_standard :type: httk.atomistic.symmetry.setting_transform.SettingTransform Return the exact transform from the IT standard setting to this structure. .. py:property:: wyckoff_sites :type: tuple[WyckoffSite, ...] Expose the symmetry-distinct sites. .. py:property:: domain_sites :type: tuple[WyckoffSite, ...] Expose the directly stored fundamental-domain sites. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Expose the species referenced by the sites. .. py:property:: coordinate_precision :type: fractions.Fraction | None Expose the recorded precision of the reduced coordinates. Fractional, and expressed in **this structure's own setting** — the frame the data arrived in — so it needs no transforming on the way to the expanded sites. Recording it here is what lets an asymmetric unit say how good the data behind it was, rather than leaving that to be guessed again downstream. It is provenance, never an operating parameter: expansion remains exact and uses no tolerance at all. :return: The fractional precision, or ``None`` when it is unknown. .. py:property:: asu :type: FundamentalDomainStructure Expose this structure as its own fundamental domain. .. py:property:: periodicity :type: tuple[bool, bool, bool] Expose the cell's periodic directions. .. py:property:: molecular :type: bool Expose whether molecular semantics are enabled. .. py:property:: domain_species_at_sites :type: tuple[str, ...] Expose species names for the directly represented domain sites. .. py:method:: cartesian_sites() Compute the exact Cartesian positions of the represented sites. :return: The Cartesian representative positions in the exact surd representation. .. py:property:: fractional_site_positions :type: list[list[float]] Expose representative positions as floating-point coordinates. .. py:property:: nsites :type: int Expose the number of directly represented sites. .. py:property:: site_coordinate_span :type: str Expose the fundamental-domain coordinate span. .. py:property:: space_group_it_number :type: int Expose the space group's International Tables number. .. py:property:: space_group_symbol_hall :type: str | None Expose the Hall symbol for the active setting. .. py:property:: space_group_symbol_hermann_mauguin :type: str | None Expose the Hermann–Mauguin symbol for the active setting. .. py:property:: space_group_symbol_hermann_mauguin_extended :type: str | None Expose the extended Hermann–Mauguin symbol for the active setting. .. py:property:: space_group_symmetry_operations_xyz :type: tuple[str, ...] Expose the active setting's symmetry operations in ``xyz`` notation. .. py:property:: wyckoff_positions :type: tuple[str, ...] | None Expose Wyckoff positions in the active setting. .. py:property:: is_standard_setting :type: bool Expose whether the structure uses its space group's standard setting. .. py:method:: setting() The tabulated setting this structure is written in, or ``None`` if untabulated. A structure in an arbitrary setting is perfectly representable but has no tabulated name; that is the point of storing the transform rather than a setting label. A transform looked up from the tables remembers which setting it came from, but one that was constructed directly does not, so an equal transform is also matched against the group's tabulated settings. An identity transform means the stored tabulated setting is already the structure's own setting. :return: The matching tabulated setting, or ``None`` when untabulated. .. py:method:: expand_sites() Every site of the unit cell, as exact reduced coordinates in this structure's setting. The orbit of each asymmetric-unit site is generated directly from its stored setting's table, wrapped into ``[0, 1)``, and deduplicated by exact equality. Only an untabulated setting uses the stored transform. Deduplication then also handles a transform that shrinks the cell; the opposite case, a transform onto a larger cell, is covered by :meth:`~httk.atomistic.SettingTransform.lattice_cosets`. :return: All unit-cell sites in the structure's exact setting. .. py:method:: expand_species_at_sites() Expose the species names produced by :meth:`expand_sites`. :return: Species names in expanded site order. .. py:method:: expand_site_moments() Expand one exact moment for every represented site. :return: Expanded site moments, or ``None`` when moments are unstated. .. py:method:: multiplicities() How many cell sites each asymmetric-unit site generates, in order. Usually the Wyckoff position's tabulated multiplicity, but not always: a setting transform that changes the cell volume changes the count too, by a factor of three for the rhombohedral-axes settings. :return: The number of expanded sites generated by each domain site. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Expose representative or expanded sites according to the semantics. .. py:property:: species_at_sites :type: tuple[str, ...] Expose representative or expanded species names according to the semantics. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose representative or expanded site moments. .. py:property:: charge :type: fractions.Fraction | None Expose the explicitly assigned exact charge of the expanded cell. :return: The assigned charge, or ``None`` when it is unstated. .. py:property:: assemblies :type: tuple[httk.atomistic.composition.Assembly, ...] | None Expose correlations among the domain sites. .. py:class:: WyckoffSite Represent one symmetry-distinct site. ``wyckoff`` is a bare letter (``"e"``, not ``"4e"``) naming a position of the structure's stored setting, and ``free_params`` holds one exact value per degree of freedom of that position — none at all for a fixed position such as an inversion centre. ``species`` names one of the owning structure's species. Moment data uses verbatim-copy semantics: every expanded orbit image carries the same moment. This is physically meaningful only when the site symmetry preserves that moment; magnetic structures that break it must be represented as a unit cell (or via ``SymopsStructure``, coming later). Partial occupancy needs nothing special here: it lives in the referenced :class:`~httk.atomistic.Species`, which already carries a composition. :param wyckoff: The Wyckoff letter in the structure's stored setting. :param free_params: The free values for the Wyckoff position. :param species: The name of the owning structure's species. :param representative: An optional retained representative coordinate. :param moment: An optional moment assigned to the site. .. py:attribute:: wyckoff :type: str .. py:attribute:: free_params :type: httk.core.FracVector .. py:attribute:: species :type: str .. py:attribute:: representative :type: httk.core.FracVector | None :value: None .. py:attribute:: moment :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None :value: None .. py:property:: free_count :type: int How many free parameters this site carries. .. py:class:: ASUStructureView(obj, *, setting = None, standard = None, transform = None, tolerance = None, immutable_id = _METADATA_UNSET, last_modified = _METADATA_UNSET, **hints) Bases: :py:obj:`httk.atomistic.models.structure.view.StructureView`, :py:obj:`httk.atomistic.models.structure.asu.ASUStructure` Present an underlying structure backend as a lazy :class:`~httk.atomistic.ASUStructure`. Resolver-backed and non-native sources are retained without recognition until the first asymmetric-unit access. The view then publishes the complete validated ASU state on itself, so its inherited API remains the genuine ASUStructure interface. Pickling retains the source backend and view options; once resolved, it also retains the validated derived ASU state while preserving that backend as the source returned by :meth:`unwrap`. :param obj: The structure backend or source to recognize and present. :param setting: The source structure's tabulated space-group setting. :param standard: The IT-standard space group for an untabulated setting. :param transform: The standard-to-source setting transform. :param tolerance: The Cartesian recognition tolerance. :param immutable_id: The optional immutable source identifier override. :param last_modified: The optional source modification timestamp override. :param \**hints: Backend-selection and reader hints. .. py:method:: resolve() Resolve and return the complete standalone asymmetric unit. .. py:method:: unwrap() Return the original source without resolving it. .. py:method:: unview() Return the resolved standalone asymmetric-unit structure. .. py:property:: sites :type: Any Expose the representative sites retained by the asymmetric-unit view. .. py:property:: species_at_sites :type: tuple[str, ...] Expose species names for the representative sites retained by the view. .. py:property:: assemblies :type: Any Expose correlations among the retained domain sites. .. py:property:: asu :type: httk.atomistic.models.structure.asu.FundamentalDomainStructure Expose this view as its own resolved fundamental domain. .. py:function:: same_crystal(first, second) Compare two structures as crystallographic descriptions. True when they have the same cell and the same *multiset* of occupied sites, comparing each site by its species and its reduced coordinate wrapped into ``[0, 1)``. Site order is ignored, and so is which lattice translate of a site was written down. The explicitly assigned cell charge and the site moments also participate in the comparison. Recorded coordinate, basis, and moment precision do not, nor do other semantic metadata such as formulas, assemblies, or source identifiers. The comparison is exact, not approximate: reduced coordinates are exact rationals and cell bases are exact, so two structures that differ by any amount at all compare unequal. There is deliberately no tolerance parameter — a tolerant comparison belongs with the recognition step that snaps a measured structure onto an idealised one, not here. Periodicity takes part in two ways. Cells must agree on it, so a slab is never the same crystal as the bulk with the same lattice vectors. And only the periodic directions are wrapped, since along the others there is no lattice translate to be indifferent about — an atom at ``1.05`` really is somewhere else than one at ``0.05``. The comparison stays exact in the frame as written: two descriptions of the same slab that differ in their non-periodic frame vector compare unequal, because reconciling them would need an origin convention this function deliberately does not have. Accepts anything structure-like on either side, so a :class:`~httk.atomistic.UnitcellStructure` may be compared directly against an :class:`~httk.atomistic.ASUStructure` without expanding it by hand. :param first: The first structure-like value. :param second: The second structure-like value. :return: Whether the structures describe the same crystal. .. py:class:: DatastreamStructure(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Represent a structure source parsed only when its data is first accessed. Requests are intentionally reader-only: an OPTIMADE-shaped Request is declined so its headers are never lost by replacing it with ``fetch(url)``. Open streams are one-shot sources; a failed parse is not cached, but consumed data cannot be replayed. Network URL strings require core network consent; wrapping a URL in :class:`~httk.core.DatastreamURL` supplies that consent explicitly. :param obj: A path, URL, stream, request, or core datastream source. :param \*\*hints: Backend-selection and reader-name hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'datastream' .. py:method:: resolve() Resolve and return the memoized native structure. :return: The parsed native structure. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Expose the source structure's cell. :return: The resolved cell. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Expose the source structure's sites. :return: The resolved sites. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Expose the source structure's species. :return: The resolved distinct species. .. py:property:: species_at_sites :type: tuple[str, ...] Expose the species occupying each resolved site. :return: Site species names in site order. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose optional moments from the resolved structure. :return: Site moments, or ``None`` when they are unstated. .. py:property:: charge :type: Any Expose the resolved structure's assigned charge. :return: The assigned charge, or ``None`` when it is unstated. .. py:method:: unwrap() Return the original lazy source. :return: The path, URL, request, or stream supplied at construction. .. py:type:: StructureLike :canonical: httk.atomistic.models.structure.backend.StructureBackend | httk.atomistic.models.structure.view.StructureView | httk.atomistic.models.structure.unitcell.UnitcellStructure | httk.atomistic.storage.records.UnitcellStructureRecord | httk.atomistic.storage.records.FundamentalDomainStructureRecord | httk.atomistic.storage.records.ASUStructureRecord | httk.atomistic.models.structure.asu.FundamentalDomainStructure | httk.core.optimade.OptimadeResource | str | os.PathLike[str] | httk.core.DatastreamURL | urllib.request.Request | io.IOBase | httk.core.datastream.TextstreamBackend | httk.core.datastream.TextstreamView | httk.core.datastream.BytestreamBackend | httk.core.datastream.BytestreamView | httk.atomistic.integrations.ase.models.ASEAtomsProtocol | httk.atomistic.integrations.pymatgen.models.PymatgenStructureProtocol | tuple[httk.core.VectorLike, httk.core.VectorLike, Any] | list[Any] .. py:class:: ModulatedStructure(payload) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Retain raw mCIF data that standard structure classes cannot represent. Future magnetic-structure support may interpret the modulation. Standard structure properties raise :class:`ValueError`; the immutable source mapping remains available through :attr:`payload`. :param payload: The raw mCIF data to retain. .. py:attribute:: kind :type: ClassVar[str] :value: 'modulated-mcif' .. py:property:: payload :type: collections.abc.Mapping[str, Any] Expose the immutable raw mCIF payload. :return: The source mapping. .. py:property:: mod_dim :type: Any Expose the incommensurate modulation dimension when supplied. :return: The raw ``mod_dim`` value, or ``None`` when absent. .. py:property:: structural_q :type: Any Expose the structural modulation vector when supplied. :return: The raw ``structural_q`` value, or ``None`` when absent. .. py:property:: magnetic_q :type: Any Expose the magnetic modulation vector when supplied. :return: The raw ``magnetic_q`` value, or ``None`` when absent. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Reject projection to a standard cell. :raises ValueError: Always, because modulation is not representable here. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Reject projection to standard sites. :raises ValueError: Always, because modulation is not representable here. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Reject projection to standard species. :raises ValueError: Always, because modulation is not representable here. .. py:property:: species_at_sites :type: tuple[str, ...] Reject projection to standard site species. :raises ValueError: Always, because modulation is not representable here. .. py:property:: site_moments :type: Any Reject projection to standard site moments. :raises ValueError: Always, because modulation is not representable here. .. py:class:: NumericUnitcellStructureView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.semantics.StructureSemanticsMixin`, :py:obj:`httk.atomistic.models.structure.view.StructureView` A plain-numpy presentation of a :class:`~httk.atomistic.UnitcellStructure`. Where a ``UnitcellStructure`` holds its geometry exactly (a surd ``cell`` basis, rational reduced coordinates, and an exact Cartesian frame), this view mirrors that interface but returns plain numpy numbers: its :attr:`cell` is a :class:`~httk.atomistic.models.cell.numeric.NumericCell`, its :attr:`sites` a :class:`~httk.atomistic.models.sites.numeric.NumericSites`, and :meth:`cartesian_sites` a ``float64`` numpy array. The ``species``/``species_at_sites`` are passed through unchanged. It is for callers who do not need exact arithmetic and just want numpy arrays. The presentation is numpy-backed, so constructing it **requires numpy** (the ``httk-atomistic[numpy]`` extra) and raises :class:`ImportError` eagerly when it is unavailable. The exact object is always one hop away via :attr:`exact`. This is a view, not a ``UnitcellStructure`` subclass. Its exact ``UnitcellStructure`` is built lazily on first access to exact geometry. :param obj: The structure backend or source to present. :param \*\*hints: Backend-selection hints passed to structure coercion. .. py:property:: cell :type: httk.atomistic.models.cell.numeric.NumericCell The cell as a :class:`~httk.atomistic.models.cell.numeric.NumericCell`. .. py:property:: sites :type: httk.atomistic.models.sites.numeric.NumericSites The sites as a :class:`~httk.atomistic.models.sites.numeric.NumericSites`. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] The distinct species, passed through unchanged. .. py:property:: species_at_sites :type: tuple[str, ...] The species name occupying each site, passed through unchanged. .. py:property:: charge :type: float | None Expose the explicitly assigned charge as a floating-point value. .. py:property:: site_moments :type: httk.core.NumericVector | None Expose Cartesian site moments as numeric values. .. py:property:: assemblies :type: tuple[httk.atomistic.composition.Assembly, ...] | None Expose site correlations. .. py:method:: cartesian_sites() The Cartesian site positions as an ``(N, 3)`` ``float64`` numpy array. .. py:property:: periodicity :type: tuple[bool, bool, bool] Expose the cell's periodic directions. .. py:property:: nperiodic_dimensions :type: int Expose the number of periodic directions. .. py:property:: site_coordinate_span :type: str Expose the presented structure's coordinate span. .. py:property:: lattice_vectors :type: list[list[float]] Expose the cell vectors as numeric coordinates. .. py:property:: fractional_site_positions :type: list[list[float]] Expose reduced site positions as numeric coordinates. .. py:property:: cartesian_site_positions :type: list[list[float]] Expose Cartesian site positions as numeric coordinates. .. py:property:: exact :type: httk.atomistic.models.structure.unitcell.UnitcellStructure The exact :class:`~httk.atomistic.UnitcellStructure` this view presents. .. py:method:: unwrap() Return the raw object wrapped by the backend. .. py:method:: unview() Reject conversion to a standalone plain numeric value. :return: Never; this view has no standalone plain value. :raises TypeError: Always, because this view has no standalone plain value. .. py:class:: OptimadeStructure(obj = None, **hints) Bases: :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Represent an OPTIMADE structure resource as a lazy structure backend. Construction merely retains the resource. The canonical structure quartet is decoded one component at a time, so an incomplete remote resource is still storable, inspectable, and round-trippable. OPTIMADE dictionaries are presented through exact local values and converted to floats only at presentation boundaries. Species dictionaries may retain the ``_httk_charges``, ``_httk_spins``, and ``_httk_labels`` extensions. :param obj: The OPTIMADE resource to retain. :param \*\*hints: Backend-selection hints, including optional ``resource`` or ``kind``. .. py:attribute:: resource :type: httk.core.optimade.OptimadeResource .. py:attribute:: kind :type: ClassVar[str] :value: 'optimade' .. py:attribute:: entry_type_definition_id :type: ClassVar[str] :value: 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/structures' .. py:method:: unwrap() Return the exact authoritative source resource by identity. :return: The original OPTIMADE resource. .. py:property:: raw :type: collections.abc.Mapping[str, object] Expose the immutable JSON API resource envelope. :return: The decoded resource envelope, including source spelling and extensions. .. py:property:: composition :type: httk.atomistic.models.formula.composition.Composition Project the source-backed composition, retaining implicit or source-only ratios. :return: The projected composition. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If source composition fields are inconsistent. .. py:property:: formula :type: str Present the reduced formula as an eager ``str`` formula view. :return: The reduced formula as a :class:`~httk.atomistic.models.formula.formula_view.ChemicalFormulaView`. :raises ValueError: If the composition is incomplete or empty. .. py:property:: id :type: str Expose the JSON API resource identifier without inferring it from a remote label. :return: The resource identifier. .. py:property:: type :type: str Expose the JSON API resource type identifier without inferring it from a remote label. :return: The resource type. .. py:property:: immutable_id :type: str | None Expose the portable immutable source identifier. :return: The identifier, or ``None`` when absent. .. py:property:: last_modified :type: datetime.datetime | None Expose the portable source modification timestamp. :return: The timestamp, or ``None`` when absent. .. py:property:: elements :type: tuple[str, ...] | None Expose the validated portable element symbols. :return: Alphabetically ordered element symbols, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If related source composition fields disagree. .. py:property:: nelements :type: int | None Expose the validated portable element count. :return: The element count, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If related source composition fields disagree. .. py:property:: elements_ratios :type: tuple[fractions.Fraction, ...] | None Expose exact portable element ratios. :return: Non-negative ratios summing to one, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the ratios are invalid or inconsistent. .. py:property:: chemical_formula_descriptive :type: str | None Expose the validated descriptive chemical formula. :return: The descriptive formula, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source formula is invalid. .. py:property:: chemical_formula_reduced :type: str | None Expose the validated reduced chemical formula. :return: The reduced formula, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source formula is invalid or inconsistent. .. py:property:: chemical_formula_hill :type: str | None Expose the validated Hill chemical formula. :return: The Hill formula, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source formula is invalid or inconsistent. .. py:property:: chemical_formula_anonymous :type: str | None Expose the validated anonymous chemical formula. :return: The anonymous formula, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source formula is invalid or inconsistent. .. py:property:: dimension_types :type: tuple[int, ...] | None Expose portable periodicity flags. :return: Three ``0``/``1`` flags, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the flags are invalid or inconsistent. .. py:property:: nperiodic_dimensions :type: int | None Expose the portable periodic-dimension count. :return: The count from zero through three, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the count is invalid or inconsistent. .. py:property:: nsites :type: int | None Expose the portable site count. :return: The non-negative site count, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If related arrays disagree with the count. .. py:property:: structure_features :type: tuple[str, ...] | None Expose validated OPTIMADE structure-feature flags. :return: Canonically ordered feature flags, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If flags are invalid or inconsistent. .. py:property:: lattice_vectors :type: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction] | None, ...] | None Expose exact lattice vectors from the OPTIMADE source. :return: Three vectors, with ``None`` for non-periodic directions, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If vectors conflict with periodicity. .. py:property:: fractional_site_positions :type: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], ...] | None Expose exact fractional site positions. :return: Fractional positions, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If supplied coordinate arrays disagree. .. py:property:: cartesian_site_positions :type: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], ...] | None Expose exact Cartesian site positions. :return: Cartesian positions, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If supplied coordinate arrays disagree. .. py:property:: site_coordinate_span :type: str Expose the source coordinate span. :return: The OPTIMADE coordinate-span value, defaulting to ``"unit_cell"``. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the span is invalid or lacks required symmetry. .. py:property:: site_coordinate_span_description :type: str | None Expose the description for an ``"other"`` coordinate span. :return: The span description, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If a description is invalid or used for another span. .. py:property:: molecular :type: bool Expose whether the native unit-cell projection carries molecular placement. :return: Whether the coordinate span is ``"molecular_unit_cell"``. .. py:property:: coordinate_precision :type: fractions.Fraction | None Expose the source precision for reduced coordinates. :return: The fractional precision, or ``None`` when unavailable. .. py:property:: basis_precision :type: fractions.Fraction | None Expose the source precision for lattice vectors. :return: The basis precision, or ``None`` when unavailable. .. py:property:: site_moments :type: httk.atomistic.models.moments.cartesian.CartesianSiteMoments | None Expose source Cartesian site moments. :return: Cartesian moments, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If moment rows are invalid or cannot be aligned to sites. .. py:property:: symmetry :type: httk.atomistic.models.structure.semantics.StructureSymmetry Build typed source symmetry metadata for the common unit-cell view layer. :return: Validated symmetry metadata. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If supplied symmetry fields are inconsistent. .. py:property:: optimization_type :type: str | None Expose the source optimization provenance. :return: The normalized optimization type, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source value is not a string. .. py:property:: assemblies :type: tuple[httk.atomistic.composition.Assembly, ...] | None Expose validated source site assemblies. :return: Assemblies, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If assemblies are invalid or inconsistent. .. py:property:: space_group_symbol_hall :type: str | None Expose the source Hall space-group symbol. :return: The symbol, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the symbol conflicts with source symmetry. .. py:property:: space_group_symbol_hermann_mauguin :type: str | None Expose the source short Hermann–Mauguin symbol. :return: The symbol, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the symbol conflicts with source symmetry. .. py:property:: space_group_symbol_hermann_mauguin_extended :type: str | None Expose the source extended Hermann–Mauguin symbol. :return: The symbol, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the symbol conflicts with source symmetry. .. py:property:: space_group_it_number :type: int | None Expose the source International Tables space-group number. :return: The number, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the number conflicts with source symmetry. .. py:property:: space_group_symmetry_operations_xyz :type: tuple[str, ...] | None Expose the declared raw ``xyz`` symmetry-operation strings. :return: The source operation strings, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If operations are invalid or inconsistent. .. py:property:: wyckoff_positions :type: tuple[str, ...] | None Expose source Wyckoff letters aligned with the represented sites. :return: Wyckoff letters, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If letters are invalid or misaligned. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Expose the projected exact cell. :return: The native cell projection. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source cannot project a unit cell. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Expose the projected exact sites. :return: The native site projection. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source cannot project site coordinates. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Expose decoded species definitions. :return: Distinct species definitions. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If source species dictionaries are invalid. .. py:property:: species_at_sites :type: tuple[str, ...] Expose decoded species names for each site. :return: Site species names in site order. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If names do not align with source sites. .. py:property:: charge :type: fractions.Fraction | None Expose the private exact charge extension. :return: The assigned charge, or ``None`` when absent. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source charge is not numeric. .. py:class:: PlainStructureView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.view.StructureView`, :py:obj:`tuple` A view presenting an underlying structure backend as a primitive triple. This view is a genuine ``(lattice, positions, numbers)`` tuple, built eagerly and immutable. Because the primitive representation carries only bare atomic numbers, every site's species must be a single, unattached chemical element (see ``Species.is_single_element``); otherwise a TypeError is raised. :param obj: The structure backend or source to present. :param \*\*hints: Backend-selection hints passed to structure coercion. .. py:method:: unwrap() Return the raw value wrapped by the backend. :return: The original source value. .. py:method:: unview() Return this presentation as an ordinary primitive triple. :return: The lattice, positions, and atomic numbers. .. py:class:: StructureSymmetry Store optional, explicitly supplied symmetry metadata for a unit-cell structure. :param space_group_it_number: Optional International Tables space-group number. :param space_group_symbol_hall: Optional Hall symbol. :param space_group_symbol_hermann_mauguin: Optional short Hermann–Mauguin symbol. :param space_group_symbol_hermann_mauguin_extended: Optional extended Hermann–Mauguin symbol. :param space_group_symmetry_operations_xyz: Optional declared raw ``xyz`` operations. :param wyckoff_positions: Optional Wyckoff letters aligned with represented sites. :raises TypeError: If a symbol is not a string. :raises ValueError: If the metadata is invalid or mutually inconsistent. .. py:attribute:: space_group_it_number :type: int | None :value: None .. py:attribute:: space_group_symbol_hall :type: str | None :value: None .. py:attribute:: space_group_symbol_hermann_mauguin :type: str | None :value: None .. py:attribute:: space_group_symbol_hermann_mauguin_extended :type: str | None :value: None .. py:attribute:: space_group_symmetry_operations_xyz :type: tuple[str, ...] | None :value: None .. py:attribute:: wyckoff_positions :type: tuple[str, ...] | None :value: None .. py:attribute:: matched_settings :type: ClassVar[tuple[collections.abc.Mapping[str, Any], ...]] .. py:class:: SymopsStructure(cell, sites, species, species_at_sites, symops, *, site_moments = None, moment_component_resolutions = None, moment_component_esds = None, moment_symmforms = None, bns_number = None, bns_label = None, chemical_composition = None, chemical_formula_descriptive = None, chemical_formula_hill = None, optimization_type = None, immutable_id = None, last_modified = None, charge = None) Bases: :py:obj:`httk.atomistic.models.structure.semantics.StructureSemanticsMixin`, :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Represent a magCIF cell, listed sites, and its complete symmetry-operation list. The operations are taken as declared. They are not checked for group closure: magCIF lists complete coset representatives, and an incomplete list consequently under-expands. Expansion is exact and deduplicates only by normalized fractional coordinates, species, and exact transformed moments. :param cell: The cell geometry. :param sites: The listed site coordinates. :param species: The distinct species definitions. :param species_at_sites: The species name occupying each listed site. :param symops: The declared spatial or magnetic symmetry operations. :param site_moments: Optional moments aligned with the listed sites. :param moment_component_resolutions: Optional decimal steps for each listed moment component, aligned in the moment backend's native frame. :param moment_component_esds: Optional standard uncertainties for each listed moment component, aligned in the moment backend's native frame. :param moment_symmforms: Optional source magnetic symmetry-form declarations aligned with the listed sites. :param bns_number: Optional Belov–Neronova–Smirnova number. :param bns_label: Optional Belov–Neronova–Smirnova label. :param chemical_composition: Optional chemical composition metadata. :param chemical_formula_descriptive: Optional descriptive chemical formula. :param chemical_formula_hill: Optional Hill chemical formula. :param optimization_type: Optional optimization provenance. :param immutable_id: Optional immutable source identifier. :param last_modified: Optional source modification timestamp. :param charge: An explicitly assigned charge for the cell content. :raises TypeError: If an input component or magnetic label has the wrong kind. :raises ValueError: If component lengths, operations, or semantic values are invalid. .. py:attribute:: kind :type: ClassVar[str] :value: 'symops' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Expose the cell geometry. :return: The exact cell. .. py:property:: listed_sites :type: httk.atomistic.models.sites.sites.Sites Expose the sites before symmetry expansion. :return: The listed site coordinates. .. py:property:: listed_species_at_sites :type: tuple[str, ...] Expose species names before symmetry expansion. :return: Listed site species names in input order. .. py:property:: listed_site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose moments before symmetry expansion. :return: Listed site moments, or ``None`` when unstated. .. py:property:: moment_component_resolutions :type: tuple[tuple[fractions.Fraction | None, ...], ...] | None Expose source decimal steps for each listed moment component, in its native frame. .. py:property:: moment_component_esds :type: tuple[tuple[fractions.Fraction | None, ...], ...] | None Expose source ESDs for each listed moment component, in its native frame. .. py:property:: moment_symmforms :type: tuple[str | None, ...] | None Expose source `_atom_site_moment.symmform` declarations aligned with listed sites. .. py:property:: symops :type: tuple[tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, int], ...] Expose normalized spatial and time-reversal operations. :return: Operation and time-reversal pairs in declaration order. .. py:property:: bns_number :type: str | None Expose the Belov–Neronova–Smirnova number. :return: The BNS number, or ``None`` when unstated. .. py:property:: bns_label :type: str | None Expose the Belov–Neronova–Smirnova label. :return: The BNS label, or ``None`` when unstated. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Expose the distinct species. :return: Species referenced by the listed sites. .. py:property:: coordinate_precision :type: Any Expose the listed-coordinate precision. :return: The fractional coordinate precision. .. py:property:: basis_precision :type: Any Expose the cell-basis precision. :return: The basis precision. .. py:property:: periodicity :type: tuple[bool, bool, bool] Expose the cell periodicity flags. :return: Periodicity flags for the three cell directions. .. py:property:: molecular :type: bool Expose whether the structure is molecular. :return: Always ``False`` for this backend. .. py:property:: site_coordinate_span :type: str Expose the coordinate span of the listed sites. :return: ``"unit_cell"``. .. py:property:: charge :type: fractions.Fraction | None Expose the explicitly assigned charge. :return: The charge, or ``None`` when unstated. .. py:method:: cartesian_sites() Compute exact Cartesian positions for the expanded sites. :return: Cartesian positions in the exact surd representation. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Expose the symmetry-expanded sites. :return: Expanded site coordinates. .. py:property:: species_at_sites :type: tuple[str, ...] Expose species names for the expanded sites. :return: Expanded site species names in site order. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose moments transformed onto the expanded sites. :return: Expanded site moments, or ``None`` when moments were unstated. .. py:class:: UnitcellStructure(cell, sites, species = None, species_at_sites = None, *, site_moments = None, molecular = False, assemblies = None, symmetry = None, chemical_composition = None, chemical_formula_descriptive = None, chemical_formula_hill = None, optimization_type = None, immutable_id = None, last_modified = None, charge = None) Bases: :py:obj:`httk.atomistic.models.structure.semantics.StructureSemanticsMixin`, :py:obj:`httk.atomistic.models.structure.backend.StructureBackend` Represent a crystal structure in the Unitcell representation. A UnitcellStructure holds a ``cell`` (a ``Cell`` of 3x3 cell vectors), ``sites`` (a ``Sites`` of Nx3 reduced coordinates), a list of ``species`` (each a ``Species``), and a length-N ``species_at_sites`` giving the species name occupying each site. Inputs are normalized on construction through the component families: the cell, sites, and each species are passed through their ``*Like`` unions, and every ``species_at_sites`` name must match one of the (uniquely named) species. When ``species`` is omitted, ``species_at_sites`` may itself contain species-like values; the distinct species table is then inferred in first-occurrence order. The numeric model is exact and split by purpose. The fractional frame — reduced coordinates and symmetry — is rational and lives in ``sites`` as a :class:`~httk.core.FracVector`. The Cartesian frame — where radicals such as the hexagonal ``sqrt(3)`` appear — is exact in the squarefree-radical field: ``cell.basis`` is a :class:`~httk.core.SurdVector` and :meth:`cartesian_sites` returns the exact Cartesian positions. Pure magnitudes (bond-length comparisons) stay rational-exact via ``cell.metric()``. Floats appear only at the presentation and JSON boundaries. :param cell: The unit-cell geometry. :param sites: The reduced coordinates of the sites. :param species: The distinct species definitions. Omit this to infer them from ``species_at_sites``. :param species_at_sites: The species name occupying each site; this value is required. :param site_moments: Optional magnetic moments aligned with the sites. :param molecular: Whether the structure describes a molecular unit cell. :param assemblies: Optional correlations among sites. :param symmetry: Optional symmetry metadata. :param chemical_composition: Optional chemical composition metadata. :param chemical_formula_descriptive: Optional descriptive chemical formula. :param chemical_formula_hill: Optional Hill chemical formula. :param optimization_type: Optional optimization provenance. :param immutable_id: Optional immutable source identifier. :param last_modified: Optional source modification timestamp. :param charge: An explicitly assigned charge for the cell content; it is not derived from the species, and an explicit zero remains distinct from an unstated charge. .. py:attribute:: kind :type: ClassVar[str] :value: 'unitcell' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Expose the cell geometry. :return: The cell in the structure's exact representation. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Expose the reduced site coordinates. :return: The sites in the structure's exact representation. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Expose the distinct species. :return: The species referenced by the structure. .. py:property:: species_at_sites :type: tuple[str, ...] Expose the species name occupying each site. :return: Site species names in site order. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose optional per-site magnetic moments in ``sites`` order. :return: Site moments, or ``None`` when they are unstated. .. py:property:: charge :type: fractions.Fraction | None Expose the explicitly assigned exact charge of the cell. :return: The assigned charge, or ``None`` when it is unstated. .. py:property:: coordinate_precision :type: fractions.Fraction | None Expose the precision recorded for the reduced coordinates. Read through from :attr:`sites`. Dimensionless — see :meth:`cartesian_precision` for the corresponding length. :return: The fractional precision, or ``None`` when it is unknown. .. py:property:: basis_precision :type: fractions.Fraction | None Expose the precision recorded for the cell basis. Read through from :attr:`cell`. :return: The absolute precision, or ``None`` when it is unknown. .. py:property:: periodicity :type: tuple[bool, bool, bool] Expose which cell directions are periodic. Read through from :attr:`cell`, where the full account lives. ``(True, True, True)`` for an ordinary crystal, which is what a structure built without saying otherwise is. :return: The periodicity flags for the cell directions. .. py:property:: site_coordinate_span :type: str Expose the coordinate span asserted by this representation. :return: ``unit_cell`` or ``molecular_unit_cell``. .. py:property:: molecular :type: bool Expose whether this structure describes a molecular unit cell. :return: Whether molecular semantics are enabled. .. py:property:: symmetry :type: httk.atomistic.models.structure.semantics.StructureSymmetry | None Expose the optional symmetry metadata. :return: The symmetry metadata, or ``None`` when it is absent. .. py:method:: cartesian_precision() The coordinate precision as a length, or ``None`` if it is unknown. This is the number a real tolerance wants — an interatomic matching tolerance or an spglib ``symprec`` is a distance, and a fractional precision is not. A coordinate good to ``1e-4`` of a cell edge means something quite different in a 3 Å cell and a 30 Å one. Computed as the fractional precision times the *longest* cell edge, which is the conservative choice: it is the largest displacement that fractional uncertainty can produce along any axis. The cell's own precision is folded in as well, since a cell stated to ``1e-3`` cannot place an atom better than that however many digits the coordinates carry. :return: The conservative Cartesian precision, or ``None`` when the coordinate precision is unknown. .. py:method:: cartesian_sites() Compute the exact Cartesian site positions. Under the row-vector convention this is ``reduced_coords * cell.basis`` (each Cartesian position is the sum over lattice vectors ``sum_k reduced[k] * basis[k]``). The reduced coordinates are rational (a ``FracVector``), the cell basis carries the radicals (a ``SurdVector``), so the product is exact in the surd field — the hexagonal ``sqrt(3)`` survives into the Cartesian positions. :return: The Cartesian positions in the exact surd representation. .. py:method:: numeric() Create a plain-numpy presentation of this structure. :return: The numpy-backed structure view. :raises ImportError: If numpy is unavailable. .. py:method:: supercell(transformation, *, max_sites = 100000) Build an exact supercell from an integer transformation. :param transformation: The lattice transformation to apply. :param max_sites: The maximum permitted number of sites, or ``None`` for no limit. :return: The generated supercell and transformation metadata. .. py:method:: orthogonal_supercell(multiplier = None, *, tolerance = None, max_multiplier = None, search_radius = 1, max_sites = 100000) Build a deterministically selected orthogonal supercell. :param multiplier: The requested volume multiplier, or ``None`` to search. :param tolerance: The geometric tolerance used during the search. :param max_multiplier: The largest multiplier considered when searching. :param search_radius: The integer search radius for candidate transformations. :param max_sites: The maximum permitted number of sites, or ``None`` for no limit. :return: The generated supercell and transformation metadata. .. py:method:: cubic_supercell(multiplier = None, *, tolerance = None, max_multiplier = None, search_radius = 1, max_sites = 100000) Build a deterministically selected cubic supercell. :param multiplier: The requested volume multiplier, or ``None`` to search. :param tolerance: The geometric tolerance used during the search. :param max_multiplier: The largest multiplier considered when searching. :param search_radius: The integer search radius for candidate transformations. :param max_sites: The maximum permitted number of sites, or ``None`` for no limit. :return: The generated supercell and transformation metadata. .. py:method:: conventional_cell(*, tolerance = None, limit_denominator = None) Express this structure in its conventional standard-setting cell. :param tolerance: The tolerance used when standardizing the structure. :param limit_denominator: The denominator limit used for rationalizing measured coordinates. :return: The standardized structure and its transformation metadata. .. py:class:: UnitcellStructureView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structure.view.StructureView`, :py:obj:`httk.atomistic.models.structure.unitcell.UnitcellStructure` A view presenting an underlying structure backend as a ``UnitcellStructure``. This view is a genuine ``UnitcellStructure``, so it can be passed anywhere a UnitcellStructure is accepted. Each component is normalized lazily on first access. For an ASU-backed view, accessing ``cell`` or ``species`` never triggers expansion. An ASU backend is expanded when unit-cell sites, species-at-sites, moments, or assemblies are requested. Assembly correlations that cannot be mapped from the fundamental domain to the full cell raise an error. :param obj: The structure backend or source to present. :param \**hints: Backend-selection and metadata options passed to construction. :raises httk.core.optimade.entries.IncompleteOptimadeResourceError: If the source declares a coordinate span that cannot be projected as a native unit cell. .. py:property:: site_moments :type: httk.atomistic.models.moments.backend.SiteMomentsBackend | None Expose the site's magnetic moments. .. py:method:: cartesian_site_moments_floats() Present the backend's native float moments when it has one, else the validated exact ones. :return: The Cartesian moments as float rows, or ``None``. .. py:property:: charge :type: fractions.Fraction | None Expose the explicitly assigned charge. .. py:method:: unwrap() Return the raw value wrapped by the backend. :return: The original source value. .. py:method:: unview() Materialize this presentation as a standalone unit-cell structure. :return: The exact unit-cell structure represented by this view. .. py:property:: immutable_id :type: str | None Expose the immutable source identifier. .. py:property:: last_modified :type: Any Expose the source modification timestamp. .. py:property:: molecular :type: bool Expose whether the presented structure is molecular. .. py:property:: site_coordinate_span :type: str Expose the unit-cell coordinate span. .. py:property:: symmetry :type: Any Expose the optional symmetry metadata. .. py:property:: assemblies :type: tuple[httk.atomistic.composition.Assembly, ...] | None Expose site correlations in the presented unit cell. .. py:property:: chemical_composition :type: Any Expose the optional chemical composition metadata. .. py:property:: chemical_formula_descriptive :type: str | None Expose the optional descriptive chemical formula. .. py:property:: chemical_formula_hill :type: str | None Expose the optional Hill chemical formula. .. py:property:: optimization_type :type: str | None Expose the optional optimization provenance. .. py:property:: site_coordinate_span_description :type: str | None Expose the optional coordinate-span description. .. py:property:: space_group_it_number :type: int | None Expose the optional space-group number. .. py:property:: space_group_symbol_hall :type: str | None Expose the optional Hall symbol. .. py:property:: space_group_symbol_hermann_mauguin :type: str | None Expose the optional Hermann–Mauguin symbol. .. py:property:: space_group_symbol_hermann_mauguin_extended :type: str | None Expose the optional extended Hermann–Mauguin symbol. .. py:property:: space_group_symmetry_operations_xyz :type: tuple[str, ...] | None Expose the optional symmetry operations in ``xyz`` notation. .. py:property:: wyckoff_positions :type: tuple[str, ...] | None Expose the optional Wyckoff positions. .. py:class:: JsonlTrajectory(source, **hints) Bases: :py:obj:`httk.atomistic.models.trajectory.backend.TrajectoryBackend` Stream a neutral ``httk-trajectory-jsonl`` payload or path lazily. Frame data remains in the JSONL container and is read as requested. :param source: A JSONL payload or path to one. :param \**hints: Backend-selection hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'jsonl' .. py:property:: nframes :type: int Return the number of frames in the container. .. py:property:: header :type: collections.abc.Mapping[str, Any] Return the neutral JSONL header mapping. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the constant distinct species. .. py:property:: species_at_sites :type: tuple[str, ...] Return the constant species name at each site. .. py:property:: reference_frames :type: tuple[int, ...] | None Return stored reference-frame indexes, or ``None``. .. py:property:: observable_names :type: tuple[str, ...] Return the names of available per-frame observables. .. py:method:: observable(name) Read one observable's values in frame order. :param name: Observable name. :return: The observable values. :raises KeyError: If the observable is unavailable. .. py:method:: frame(i) Read one frame from the JSONL container. :param i: Frame index. :return: The requested unit-cell structure. :raises IndexError: If the frame index is out of range. .. py:method:: frames() Stream all frames from the JSONL container. :yields: Unit-cell structures in container order. .. py:method:: unwrap() Return the original JSONL source payload or path. .. py:property:: source_locator :type: str | None Return the JSONL path, if the source has one. .. py:class:: PlainTrajectory(obj, **hints) Bases: :py:obj:`httk.atomistic.models.trajectory.backend.TrajectoryBackend` Represent a mapping whose structure properties have a frame axis. A compact constant property is represented by a one-element leading axis, e.g. ``nelements=[2]`` for any number of frames. Only properties declaring ``constant`` on that axis accept this compact form. :param obj: A trajectory property mapping. :param \**hints: Backend-selection hints. .. py:attribute:: kind :type: ClassVar[str] :value: 'plain' .. py:method:: frame(i) Return one frame from the property mapping. :param i: Frame index; negative indexes count from the end. :return: The requested unit-cell structure. :raises IndexError: If the frame index is out of range. :raises KeyError: If a required trajectory property is absent. :raises TypeError: If the frame index is not an integer. :raises ValueError: If the frame cannot be represented as a structure. .. py:method:: frames() Iterate over all frames in source order. :return: An iterator of unit-cell structures. .. py:property:: nframes :type: int Return the number of frames. .. py:property:: reference_frames :type: tuple[int, ...] | None Return normalized reference-frame indexes, or ``None``. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the constant distinct species from the first frame. .. py:property:: species_at_sites :type: tuple[str, ...] Return the constant species name at each site. .. py:property:: observable_names :type: tuple[str, ...] Return names outside the recognized trajectory and structure properties. .. py:method:: observable(name) Return one mapped observable's values in frame order. :param name: Observable property name. :return: The observable values. :raises KeyError: If the property is not an observable. .. py:method:: unwrap() Return the original property mapping. .. py:class:: Trajectory(frames, observables = None, reference_frames = None) Bases: :py:obj:`httk.atomistic.models.trajectory.backend.TrajectoryBackend` Store an immutable trajectory in the native backend. A trajectory requires at least one frame and keeps one constant composition across all frames. :param frames: Unit-cell structures to coerce and store. :param observables: Optional per-frame observable values. :param reference_frames: Optional indexes of bounded reference frames. .. py:attribute:: kind :type: ClassVar[str] :value: 'native' .. py:property:: nframes :type: int Return the number of stored frames. .. py:method:: frame(i) Return one stored frame by index. :param i: Frame index. :return: The requested unit-cell structure. :raises IndexError: If the index is out of range. .. py:method:: frames() Iterate over the stored frames. :return: An iterator of unit-cell structures. .. py:property:: reference_frames :type: tuple[int, ...] | None Return the bounded reference-frame indexes, or ``None``. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the constant distinct species. .. py:property:: species_at_sites :type: tuple[str, ...] Return the constant species name at each site. .. py:property:: observable_names :type: tuple[str, ...] Return the names of stored observables. .. py:method:: observable(name) Return one observable's values in frame order. :param name: Observable name. :return: The observable values. :raises KeyError: If the observable is unavailable. .. py:type:: TrajectoryLike :canonical: TrajectoryBackend | TrajectoryView | Trajectory | PlainTrajectory | Mapping[str, Any] .. py:class:: TrajectoryView(obj, **hints) Bases: :py:obj:`httk.core.View`\ [\ :py:obj:`httk.atomistic.models.trajectory.backend.TrajectoryBackend`\ ], :py:obj:`httk.atomistic.models.trajectory.api.TrajectoryAPI` Present any trajectory backend through the canonical trajectory API. :param obj: A trajectory backend or another accepted trajectory value. :param \**hints: Backend-selection hints. .. py:property:: nframes :type: int Return the number of frames. .. py:method:: frame(i) Return one frame by index. :param i: Frame index. :return: The requested unit-cell structure. .. py:method:: frames() Iterate over the frames. :return: An iterator of unit-cell structures. .. py:property:: reference_frames :type: tuple[int, ...] | None Return stored reference-frame indexes, or ``None``. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the constant distinct species. .. py:property:: species_at_sites :type: tuple[str, ...] Return the constant species name at each site. .. py:property:: observable_names :type: tuple[str, ...] Return the names of available per-frame observables. .. py:property:: observable_summaries :type: tuple[Any, ...] Return backend-provided observable summaries, if any. .. py:property:: immutable_id :type: str | None Return the backend immutable identifier, if available. .. py:property:: last_modified :type: Any Return the backend modification marker, if available. .. py:property:: source_locator :type: str | None Return the source locator, if available. .. py:method:: observable(name) Return one observable's values in frame order. :param name: Observable name. :return: The observable values. :raises KeyError: If the observable is unavailable. .. py:method:: unwrap() Return the original value wrapped by the backend. .. py:class:: PlaneWaveFunctions(source = None, *, cell = None, encut = None, kpoints = None, eigenvalues = None, occupations = None, coefficients = None, nplanewaves = None, double_precision = None, gamma_half = None) Provide a zero-based, NumPy-native collection of plane-wave coefficients. This is an eager NumPy representation, not a backend or view family. NumPy is required at construction time; install the ``httk-atomistic[numpy]`` extra when it is absent. A WAVECAR does not store whether gamma compression used the ``x`` or ``z`` half-space. The default interpretation is ``x``; pass ``gamma_half="z"`` to :func:`~httk.core.load` when loading a z-half gamma WAVECAR. Gamma compression is detected from the k-point and plane-wave count during construction. :param source: A WAVECAR source or neutral WAVECAR payload, or ``None`` for in-memory data. :param cell: The real-space cell used by the in-memory coefficients. :param encut: The plane-wave energy cutoff used to generate reciprocal vectors. :param kpoints: The k-points used by the in-memory coefficients. :param eigenvalues: The band eigenvalues. :param occupations: The band occupations. :param coefficients: The coefficient vectors keyed by zero-based spin, k-point, and band. :param nplanewaves: The number of plane waves for each k-point, or ``None`` to infer it. :param double_precision: Whether to retain double-precision complex coefficients. :param gamma_half: The gamma-compression half-space, ``"x"`` or ``"z"``, if applicable. :raises ImportError: If NumPy is unavailable. .. py:property:: nspins :type: int Return the number of spin channels. .. py:property:: nkpts :type: int Return the number of k-points. .. py:property:: nbands :type: int Return the number of bands. .. py:property:: encut :type: float Return the plane-wave energy cutoff. .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the real-space cell. .. py:property:: kpoints :type: Any Return the k-point coordinates. .. py:property:: eigenvalues :type: Any Return the band eigenvalues. .. py:property:: occupations :type: Any Return the band occupations. .. py:property:: nplanewaves :type: Any Return the plane-wave count for each k-point. .. py:property:: double_precision :type: bool Return whether coefficients use double precision. .. py:property:: is_gamma :type: bool Return whether the coefficients use gamma compression. .. py:property:: gamma_half :type: str | None Return the detected gamma-compression half-space, if applicable. .. py:property:: kgrid_size :type: Any Return the reciprocal-grid dimensions used for transforms. .. py:method:: close() Close a file-backed source while retaining cached coefficients and metadata. .. py:property:: closed :type: bool Report whether the file-backed source is closed. .. py:method:: coefficients(spin, kpt, band, *, cache = True) Return one coefficient vector, using an existing cache even when ``cache=False``. An uncached source read occurs once and is not stored; cached coefficients remain available after a file-backed source is closed. :param spin: The zero-based spin index. :param kpt: The zero-based k-point index. :param band: The zero-based band index. :param cache: Whether to cache a coefficient vector read from the source. :return: The selected coefficient vector. :raises ValueError: If an index is out of range or source coefficients have the wrong length. .. py:method:: gvectors(kpt = 0, *, gamma = None, gamma_half = None) Return the reciprocal grid vectors for a k-point. :param kpt: The zero-based k-point index. :param gamma: Whether to use gamma compression, or the construction default when ``None``. :param gamma_half: The gamma-compression half-space, if gamma compression is requested. :return: The reciprocal grid vectors selected by the cutoff. :raises ValueError: If the k-point, gamma flag, or half-space is invalid. .. py:method:: realspace_wave(spin, kpt, band, *, norm = True) Transform coefficients to a real-space wave using NumPy FFTs. The transform uses ``numpy.fft`` with ``norm="ortho"``. Gamma-compressed coefficients are expanded according to the detected half-space before the transform. :param spin: The zero-based spin index. :param kpt: The zero-based k-point index. :param band: The zero-based band index. :param norm: Whether to normalize the resulting wave to unit norm. :return: The real-space wave on the reciprocal grid. :raises ValueError: If an index is out of range or the stored gamma metadata is invalid. .. py:method:: select(spins = None, kpts = None, bands = None, *, format = None, gamma_half = 'x') Select spins, k-points, and bands, optionally converting coefficient format. Indices are zero-based and must be unique. Converting standard coefficients to gamma format derives a signed real wave from the standard complex wave and therefore destroys phase information; converting gamma coefficients to standard format expands the stored half-space. A gamma selection must contain exactly one gamma-point k-point. :param spins: The zero-based spin indices to retain, or all spins when ``None``. :param kpts: The zero-based k-point indices to retain, or all k-points when ``None``. :param bands: The zero-based band indices to retain, or all bands when ``None``. :param format: The requested coefficient format, ``"std"``, ``"gamma"``, or ``None``. :param gamma_half: The target gamma-compression half-space. :return: A new in-memory collection containing the selected data. :raises ValueError: If indices, format, gamma selection, or half-space conversion is invalid. .. py:function:: save_vesta(basename, structure, wave, *, cols = 10) Save real and imaginary wave components as VASP volumetric files. The files are written as ``_r.vasp`` and ``_i.vasp``. :param basename: The output filename prefix. :param structure: The structure supplying the volumetric-file cell and species metadata. :param wave: The three-dimensional complex wave to write. :param cols: The number of values written per output line. :raises ImportError: If NumPy is not installed. :raises ValueError: If ``wave`` is not a three-dimensional complex array. .. py:function:: wavefunction_overlap(phi1, phi2) Return the complex overlap of two wavefunctions. :param phi1: The first wavefunction. :param phi2: The second wavefunction. :return: The conjugate-inner-product overlap. :raises ValueError: If the wavefunctions do not have matching shapes. .. py:class:: StructureEntry Define the non-instantiable OPTIMADE structure entry family. .. py:attribute:: type :value: 'structures' .. py:attribute:: definition_id :value: 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/structures' .. py:method:: entry_type_definition() :classmethod: Load the standard structure definition with atomistic extensions. :return: The extended OPTIMADE ``structures`` definition. .. py:class:: StructureEntryProvider(entries, *, extra_definitions = None, properties = None) Bases: :py:obj:`httk.core.EntryProvider` Serve complete OPTIMADE v1.3 structure records from atomistic structures. A mapping keeps the convenient ``{"example": structure}`` form and its explicit served ids. An iterable of natural structures uses each representation's structural content id. Entry metadata lives on the structures themselves. Custom properties may extend the schema, but standard OPTIMADE fields are a pure projection of the entry and structure and cannot be replaced by custom values. :param entries: Entries keyed by explicit ids, or entries whose ids are derived from their representations; explicit entries may be ``None``. :param extra_definitions: Additional property definitions to expose. :param properties: Per-entry custom property values validated against the definition. .. py:method:: entry_types() Return the structure entry type served by this provider. :return: The ``structures`` entry-type definition. .. py:method:: property_keys(entry_type) Map served structure properties to storage keys. :param entry_type: The entry type to inspect. :return: Served-property to storage-key mappings. :raises KeyError: If ``entry_type`` is not ``structures``. .. py:method:: records(entry_type) Project the provider's structures into OPTIMADE records. ``None`` entries produce rows with null structure properties. :param entry_type: The entry type to project. :return: The projected records. :raises KeyError: If ``entry_type`` is not ``structures``. .. py:class:: TrajectoryEntry Define the non-instantiable OPTIMADE trajectory entry family. .. py:attribute:: type :value: 'trajectories' .. py:attribute:: definition_id :value: 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/trajectories' .. py:method:: entry_type_definition() :classmethod: Load the trajectory definition with httk extensions. :return: The extended OPTIMADE ``trajectories`` definition. .. py:class:: TrajectoryEntryProvider(entries, *, extra_definitions = None, properties = None) Bases: :py:obj:`httk.core.EntryProvider` Serve trajectory metadata and bounded frame projections. Native frame lists are materialized only through :data:`httk.atomistic.entries.trajectories.TRAJECTORY_FRAME_MATERIALIZATION_LIMIT` (100) frames. Larger or record-backed trajectories still serve the entry, frame count, references, and null frame properties. Recover their frame data by re-reading the original source files or the JSONL container; partial-data serving is planned. :param entries: Entries keyed by explicit ids, or entries whose ids are derived from their representations; explicit entries may be ``None``. :param extra_definitions: Additional property definitions to expose. :param properties: Per-entry custom property values validated against the definition. .. py:method:: entry_types() Return the trajectory entry type served by this provider. :return: The ``trajectories`` entry-type definition. .. py:method:: property_keys(entry_type) Map served trajectory properties to storage keys. :param entry_type: The entry type to inspect. :return: Served-property to storage-key mappings. :raises KeyError: If ``entry_type`` is not ``trajectories``. .. py:method:: records(entry_type) Project trajectories into OPTIMADE records. Native frame lists are served only for trajectories up to the materialization limit; larger and record-backed trajectories serve null frame properties. :param entry_type: The entry type to project. :return: The projected records. :raises KeyError: If ``entry_type`` is not ``trajectories``. .. py:class:: ASUStructureRecord Bases: :py:obj:`FundamentalDomainStructureRecord` Represent the native durable backing for an asserted asymmetric unit. Inherit the fundamental-domain constructor fields and validation contract while retaining the asymmetric-unit record identity. .. py:property:: type :type: str Expose the OPTIMADE entry type. :return: ``structures``. .. py:class:: FundamentalDomainTemplateRecord Represent the durable backing for a standard-setting dummy-species fundamental domain. The record carries the geometric per-structure fundamental-domain template: its standard-setting space group, its cell (surd-capable), the symmetry-distinct Wyckoff sites with their exact free parameters, and the distinct dummy species. Distinct templates with different free parameters are distinct values, so no content deduplication is expected; the content identity remains deterministic. :param cell: The durable standard-setting cell record. :param wyckoff_sites: The symmetry-distinct durable Wyckoff site records. :param species: The distinct durable dummy species records. :param spacegroup_it_number: The International Tables space-group number. :param spacegroup_hall_entry: The standard-setting Hall entry that names the stored Wyckoff data. :param coordinate_precision: The reduced-coordinate precision, if stated. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. .. py:attribute:: cell :type: CellRecord .. py:attribute:: wyckoff_sites :type: tuple[WyckoffSiteRecord, ...] .. py:attribute:: species :type: tuple[SpeciesRecord, ...] .. py:attribute:: spacegroup_it_number :type: int .. py:attribute:: spacegroup_hall_entry :type: str .. py:attribute:: coordinate_precision :type: fractions.Fraction | None :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:class:: FundamentalDomainStructureRecord Represent the native durable backing for a symmetry fundamental domain. Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook. The record's content identity is independent of its storage layout. :param cell: The durable cell record. :param domain_sites: The symmetry-distinct durable site records. :param species: The distinct durable species records. :param spacegroup_it_number: The International Tables space-group number. :param spacegroup_hall_entry: The setting that names the stored Wyckoff data. :param setting_transform: The stored-setting-to-own transform. :param coordinate_precision: The reduced-coordinate precision, if stated. :param normalized_composition: The authoritative normalized composition. :param charge: The explicitly assigned cell charge, if stated. :param molecular: Whether the structure describes molecular entities. :param assemblies: The site assemblies, if stated. :param chemical_composition: The chemical composition declaration, if stated. :param chemical_formula_descriptive: The descriptive formula, if stated. :param chemical_formula_hill: The Hill formula, if stated. :param optimization_type: The optimization provenance, if stated. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. :param last_modified: The source modification timestamp, if stated. .. py:attribute:: cell :type: CellRecord .. py:attribute:: domain_sites :type: tuple[WyckoffSiteRecord, ...] .. py:attribute:: species :type: tuple[SpeciesRecord, ...] .. py:attribute:: spacegroup_it_number :type: int .. py:attribute:: spacegroup_hall_entry :type: str .. py:attribute:: setting_transform :type: SettingTransformRecord .. py:attribute:: coordinate_precision :type: fractions.Fraction | None .. py:attribute:: normalized_composition :type: NormalizedCompositionRecord .. py:attribute:: charge :type: fractions.Fraction | None :value: None .. py:attribute:: molecular :type: bool :value: False .. py:attribute:: assemblies :type: tuple[AssemblyRecord, ...] | None :value: None .. py:attribute:: chemical_composition :type: ChemicalCompositionRecord | None :value: None .. py:attribute:: chemical_formula_descriptive :type: str | None :value: None .. py:attribute:: chemical_formula_hill :type: str | None :value: None .. py:attribute:: optimization_type :type: str | None :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:attribute:: last_modified :type: Annotated[datetime.datetime | None, IdentitySkip()] :value: None .. py:property:: type :type: str Expose the OPTIMADE entry type. :return: ``structures``. .. py:class:: ProtostructureRecord Represent the durable backing for an assigned-species classification key. The record carries exactly the value identity of :class:`~httk.atomistic.models.protostructure.protostructure.Protostructure`: its standard-setting space group and its occupied Wyckoff positions with real species, in canonical order, plus an optional exact representative and/or discriminator. The record's content identity is independent of its storage layout, and two equal protostructures produce the same content identity. :param spacegroup_it_number: The International Tables space-group number. :param spacegroup_hall_entry: The standard-setting Hall entry that names the stored Wyckoff data. :param occupations: The occupied Wyckoff positions and their real species. :param representative: The optional durable exact class anchor. :param discriminator: The optional external class discriminator. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. .. py:attribute:: spacegroup_it_number :type: int .. py:attribute:: spacegroup_hall_entry :type: str .. py:attribute:: occupations :type: tuple[WyckoffOccupationRecord, ...] .. py:attribute:: representative :type: FundamentalDomainStructureRecord | None :value: None .. py:attribute:: discriminator :type: str | None :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:property:: label :type: str Expose the httk protostructure label as a deterministic query column. The label is the httk protostructure label (``"AB_cF8_225_a_b:Na-Cl"`` for rocksalt): the prototype label of the erased template followed by ``:`` and the class species names. It is a convenience and query column only; it is not the record's identity (the content id is), and it is NOT unique across distinct protostructures: species that share a name but differ in any other :class:`~httk.atomistic.Species` field (concentration, charges, spins, mass, precision, ...) collide on the same label, so a ``GROUP BY label`` may under-count distinct protostructures — count and deduplicate by row (content id), never by label. :return: The httk protostructure label. .. py:class:: PrototypeRecord Represent the durable backing for an anonymous prototype. The record carries anonymous class-partitioned Wyckoff occupations, plus an optional exact fundamental-domain-template representative and/or discriminator. Base-only values are valid. The discriminator is species-independent and is not part of the label. :param spacegroup_it_number: The International Tables space-group number. :param spacegroup_hall_entry: The standard-setting Hall entry that names the stored Wyckoff data. :param occupations: The occupied Wyckoff positions and anonymous class labels. :param representative: The durable class representative, if one is held. :param discriminator: The externally assigned class discriminator, if one is held. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. .. py:attribute:: spacegroup_it_number :type: int .. py:attribute:: spacegroup_hall_entry :type: str .. py:attribute:: occupations :type: tuple[httk.atomistic.models.prototype.occupation.PrototypeOccupation, ...] .. py:attribute:: representative :type: FundamentalDomainTemplateRecord | None :value: None .. py:attribute:: discriminator :type: str | None :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:property:: label :type: str Expose the httk prototype label as a deterministic query column. The discriminator names the geometrical class and is not part of the label, so prototypes that share occupations but differ in class collide on this column; it is a convenience and query column only, not the record's identity (the content id is). :return: The httk prototype label. .. py:class:: UnitcellStructureRecord Represent the native durable backing for an explicit unit-cell structure. Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook. The record's content identity is independent of its storage layout. :param cell: The durable cell record. :param sites: The durable site-coordinate record. :param species: The distinct durable species records. :param species_at_sites: The species name occupying each site. :param normalized_composition: The authoritative normalized composition. :param charge: The explicitly assigned cell charge, if stated. :param site_moments_kind: The site-moment kind, if stated. :param site_moments: The flattened exact site-moment components, if stated. :param site_moments_precision: The site-moment precision, if stated. :param molecular: Whether the structure describes molecular entities. :param assemblies: The site assemblies, if stated. :param symmetry: The symmetry metadata, if stated. :param chemical_composition: The chemical composition declaration, if stated. :param chemical_formula_descriptive: The descriptive formula, if stated. :param chemical_formula_hill: The Hill formula, if stated. :param optimization_type: The optimization provenance, if stated. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. :param last_modified: The source modification timestamp, if stated. .. py:attribute:: cell :type: CellRecord .. py:attribute:: sites :type: SitesRecord .. py:attribute:: species :type: tuple[SpeciesRecord, ...] .. py:attribute:: species_at_sites :type: tuple[str, ...] .. py:attribute:: normalized_composition :type: NormalizedCompositionRecord .. py:attribute:: charge :type: fractions.Fraction | None :value: None .. py:attribute:: site_moments_kind :type: str | None :value: None .. py:attribute:: site_moments :type: tuple[httk.core.SurdScalar, ...] | None :value: None .. py:attribute:: site_moments_precision :type: fractions.Fraction | None :value: None .. py:attribute:: molecular :type: bool :value: False .. py:attribute:: assemblies :type: tuple[AssemblyRecord, ...] | None :value: None .. py:attribute:: symmetry :type: SymmetryRecord | None :value: None .. py:attribute:: chemical_composition :type: ChemicalCompositionRecord | None :value: None .. py:attribute:: chemical_formula_descriptive :type: str | None :value: None .. py:attribute:: chemical_formula_hill :type: str | None :value: None .. py:attribute:: optimization_type :type: str | None :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:attribute:: last_modified :type: Annotated[datetime.datetime | None, IdentitySkip()] :value: None .. py:property:: type :type: str Expose the OPTIMADE entry type. :return: ``structures``. .. py:function:: validate_structure_record(record) Validate a hand-built root record against native structure semantics. :param record: The exact root structure record to validate. :return: ``None`` after successful validation. :raises TypeError: If ``record`` is not an exact supported root record. :raises ValueError: If the record's normalized composition contradicts its native fields. .. py:class:: ObservableSummaryRecord Represent a bounded numeric summary for one trajectory observable. :param name: The observable name. :param first: The first finite value, if available. :param last: The last finite value, if available. :param minimum: The minimum finite value, if available. :param maximum: The maximum finite value, if available. .. py:attribute:: name :type: str .. py:attribute:: first :type: float | None :value: None .. py:attribute:: last :type: float | None :value: None .. py:attribute:: minimum :type: float | None :value: None .. py:attribute:: maximum :type: float | None :value: None .. py:class:: TrajectoryRecord Represent bounded trajectory identity and reference-frame summary. Frame data is never stored in this record. Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook. :param nframes: The total number of trajectory frames. :param species: The distinct durable species records. :param species_at_sites: The species name occupying each site. :param reference_frame_indexes: The sorted indexes of retained reference frames. :param reference_frame_structures: The retained reference-frame records. :param observable_summaries: The summaries of trajectory observables. :param source_locator: The source locator, if stated. :param id: The human-readable entry id shared by all revisions; minted by the store when None. :param immutable_id: The per-revision immutable id; minted by the store when None. :param last_modified: The source modification timestamp, if stated. .. py:attribute:: nframes :type: int .. py:attribute:: species :type: tuple[SpeciesRecord, ...] .. py:attribute:: species_at_sites :type: tuple[str, ...] .. py:attribute:: reference_frame_indexes :type: tuple[int, ...] .. py:attribute:: reference_frame_structures :type: tuple[UnitcellStructureRecord, ...] .. py:attribute:: observable_summaries :type: tuple[ObservableSummaryRecord, ...] .. py:attribute:: source_locator :type: Annotated[str | None, IdentitySkip()] :value: None .. py:attribute:: id :type: Annotated[str | None, IdentitySkip(), Indexed()] :value: None .. py:attribute:: immutable_id :type: Annotated[str | None, IdentitySkip(), Unique()] :value: None .. py:attribute:: last_modified :type: Annotated[datetime.datetime | None, IdentitySkip()] :value: None .. py:property:: type :type: str Expose the OPTIMADE entry type. :return: ``trajectories``. .. py:class:: WyckoffOccupationRecord Represent one occupied standard-setting Wyckoff orbit and its real species. The occupation carries a real (possibly disordered) ``SpeciesRecord``; it is the durable analogue of :class:`~httk.atomistic.models.protostructure.occupation.WyckoffOccupation`. :param wyckoff: The Wyckoff letter in the standard setting. :param species: The durable real species occupying the orbit. .. py:attribute:: wyckoff :type: str .. py:attribute:: species :type: SpeciesRecord .. py:class:: Formulatype(backend, **hints) Bases: :py:obj:`httk.atomistic.models.formula.backend.ChemicalFormulaBackend`, :py:obj:`str` Store a strictly canonical OPTIMADE anonymous chemical formula. The canonical class name is ``Formulatype``; the legacy ``AnonymousFormula`` name remains available as an alias. :param formula: The canonical anonymous formula text. .. py:property:: is_anonymous :type: bool Return whether the formula uses anonymous labels. .. py:property:: amounts :type: tuple[tuple[str, fractions.Fraction], ...] Return the anonymous coefficients as exact amounts. .. py:class:: FormulatypeView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase`, :py:obj:`httk.atomistic.models.formula.formulatype.Formulatype` Present a complete composition as an eager canonical anonymous formula. The canonical class name is ``FormulatypeView``; the legacy ``AnonymousFormulaView`` name remains available as an alias. :param obj: The chemical-formula-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: amounts Return the presented amounts using anonymous labels. .. py:property:: uncertainties Return the presented amount precisions using anonymous labels. .. py:property:: complete Return whether the presented composition is complete. .. py:property:: exact Return whether the presented amounts are exact. .. py:property:: normalized Return whether the presented composition is normalized. .. py:property:: normalization_status Return the presented composition's normalization status. .. py:property:: diagnostics Return diagnostics associated with the presented composition. .. py:property:: is_anonymous Return whether this formula uses anonymous labels. .. py:method:: unview() Return the presented formula as a standalone value. :return: The canonical anonymous formula value. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:class:: Composition(amounts, uncertainties = None, complete = True, exact = None, normalized = True, normalization_status = None, diagnostics = ()) Bases: :py:obj:`httk.atomistic.models.formula.backend.ChemicalFormulaBackend` Store an immutable projected composition and its formula diagnostics. :param amounts: The projected elemental amounts in symbol order. :param uncertainties: The corresponding amount precisions, if known. :param complete: Whether the projection contains no unknown elemental content. :param exact: Whether all projected amounts are exact. :param normalized: Whether all contributing probabilities and concentrations normalize. :param normalization_status: The combined normalization status. :param diagnostics: The non-fatal issues found during projection. .. py:attribute:: amounts :type: tuple[tuple[str, fractions.Fraction], ...] :value: () Ordered ``(label, exact amount)`` pairs for this chemical formula. Labels are element symbols in alphabetical order unless ``is_anonymous``, in which case they are OPTIMADE anonymous symbols in canonical (descending-coefficient) order. .. py:attribute:: uncertainties :type: tuple[tuple[str, fractions.Fraction | None], ...] :value: () Per-amount absolute uncertainties, or ``None`` where exactness is unstated. .. py:attribute:: complete :type: bool :value: True Whether the formula accounts for all represented elemental material. .. py:attribute:: exact :type: bool :value: True Whether all formula amounts are exact rather than precision-bounded. .. py:attribute:: normalized :type: bool :value: True Whether the formula is normalized within the stated precision. .. py:attribute:: normalization_status :type: str :value: 'exact' The formula's normalization status derived from exactness and normalization. .. py:attribute:: diagnostics :type: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, ...] :value: () Non-fatal structured diagnostics associated with the formula. .. py:property:: amount_mapping :type: collections.abc.Mapping[str, fractions.Fraction] Return the projected amounts as a read-only mapping. .. py:property:: uncertainty_mapping :type: collections.abc.Mapping[str, fractions.Fraction | None] Return the projected amount precisions as a read-only mapping. .. py:property:: elements :type: tuple[str, ...] Return the projected element symbols in amount order. .. py:property:: nelements :type: int Return the number of projected elements. .. py:property:: elements_ratios :type: tuple[fractions.Fraction, ...] Return the projected amounts normalized by their total. .. py:property:: chemical_formula_reduced :type: str | None Return the reduced chemical formula, if the composition is complete. .. py:property:: chemical_formula_anonymous :type: str | None Return the anonymous formula, if the composition is complete. .. py:class:: CompositionView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase`, :py:obj:`httk.atomistic.models.formula.composition.Composition` Present any chemical-formula backend as a lazy composition. :param obj: The chemical-formula-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: amounts :type: tuple[tuple[str, fractions.Fraction], ...] Return the lazily materialized elemental amounts. .. py:property:: uncertainties :type: tuple[tuple[str, fractions.Fraction | None], ...] Return the lazily materialized amount precisions. .. py:property:: complete :type: bool Return whether the presented composition is complete. .. py:property:: exact :type: bool Return whether the presented amounts are exact. .. py:property:: normalized :type: bool Return whether the presented composition is normalized. .. py:property:: normalization_status :type: str Return the presented composition's normalization status. .. py:property:: diagnostics :type: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, ...] Return diagnostics associated with the presented composition. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the presented composition as a standalone value. :return: The materialized composition value. .. py:class:: ChemicalFormula(backend, **hints) Bases: :py:obj:`httk.atomistic.models.formula.backend.ChemicalFormulaBackend`, :py:obj:`str` Store a strictly canonical reduced chemical formula. :param formula: The alphabetical formula text with greatest common divisor one. .. py:property:: amounts :type: tuple[tuple[str, fractions.Fraction], ...] Return the formula coefficients as exact amounts. .. py:class:: ChemicalFormulaView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase`, :py:obj:`httk.atomistic.models.formula.formula.ChemicalFormula` Present a complete composition as an eager canonical reduced formula. :param obj: The chemical-formula-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: amounts Return the presented elemental amounts. .. py:property:: uncertainties Return the presented amount precisions. .. py:property:: complete Return whether the presented composition is complete. .. py:property:: exact Return whether the presented amounts are exact. .. py:property:: normalized Return whether the presented composition is normalized. .. py:property:: normalization_status Return the presented composition's normalization status. .. py:property:: diagnostics Return diagnostics associated with the presented composition. .. py:property:: is_anonymous Return whether this formula uses anonymous labels. .. py:method:: unview() Return the presented formula as a standalone value. :return: The canonical reduced formula value. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:type:: ChemicalFormulaLike :canonical: httk.atomistic.models.formula.backend.ChemicalFormulaBackend | httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase | httk.atomistic.models.formula.composition.Composition | httk.atomistic.models.formula.formula.ChemicalFormula | httk.atomistic.models.formula.formulatype.Formulatype | httk.atomistic.models.structuretype.backend.StructuretypeBackend | httk.atomistic.models.structuretype.view_base.StructuretypeViewBase | httk.atomistic.models.structuretype.structuretype.Structuretype | httk.atomistic.models.structuretype.fundamental.FundamentalDomainTemplate | httk.atomistic.models.prototype.backend.PrototypeBackend | httk.atomistic.models.prototype.view_base.PrototypeViewBase | httk.atomistic.models.prototype.prototype.Prototype | httk.atomistic.models.protostructure.backend.ProtostructureBackend | httk.atomistic.models.protostructure.view_base.ProtostructureViewBase | httk.atomistic.models.protostructure.protostructure.Protostructure | httk.atomistic.storage.records.NormalizedCompositionRecord | httk.atomistic.models.structure.backend.StructureBackend | httk.atomistic.models.structure.view.StructureView | str | Mapping[str, Any] .. py:data:: AnonymousFormula .. py:data:: AnonymousFormulaView .. py:class:: Structuretype(cell, sites, species = None, species_at_sites = None) Bases: :py:obj:`httk.atomistic.models.structuretype.backend.StructuretypeBackend` Store a unit cell whose site identities are consecutive dummy labels. ``Structuretype`` is the anonymous-species, exact-geometry cell of the material-information matrix: With no geometry the anonymous/assigned pair is ``Formulatype``/``ChemicalFormula``; with Wyckoff information and optional disambiguation it is ``Prototype``/``Protostructure``; and with exact geometry it is ``Structuretype``/``Structure``. :param cell: The unit-cell geometry. :param sites: The reduced coordinates of the sites. :param species: The distinct dummy species definitions. :param species_at_sites: The dummy species name occupying each site. .. py:attribute:: kind :type: ClassVar[str] :value: 'unitcell' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the unit cell. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Return the reduced sites. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the distinct dummy species. .. py:property:: species_at_sites :type: tuple[str, ...] Return dummy species names in site order. .. py:property:: periodicity :type: tuple[bool, bool, bool] Return the periodic directions. .. py:property:: nperiodic_dimensions :type: int Return the number of periodic directions. .. py:property:: nsites :type: int Return the number of sites. .. py:method:: cartesian_sites() Return the exact Cartesian site positions. :return: The Cartesian positions in the cell's exact vector representation. .. py:property:: coordinate_precision Return the reduced-coordinate precision. .. py:property:: basis_precision Return the cell-basis precision. .. py:class:: StructuretypeView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structuretype.view_base.StructuretypeViewBase`, :py:obj:`httk.atomistic.models.structuretype.structuretype.Structuretype` Present a structuretype or ordinary structure lazily as a structuretype. :param obj: The structuretype-like or structure-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: periodicity Return the presented periodic directions. .. py:property:: nperiodic_dimensions Return the number of presented periodic directions. .. py:property:: nsites Return the number of presented sites. .. py:method:: cartesian_sites() Return the exact Cartesian presented site positions. .. py:property:: coordinate_precision Return the presented coordinate precision. .. py:property:: basis_precision Return the presented basis precision. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the presented structure as a standalone value. :return: The structuretype value. .. py:type:: StructuretypeLike :canonical: httk.atomistic.models.structuretype.backend.StructuretypeBackend | httk.atomistic.models.structuretype.view_base.StructuretypeViewBase | httk.atomistic.models.structuretype.structuretype.Structuretype | httk.atomistic.models.structuretype.fundamental.FundamentalDomainTemplate .. py:class:: ASUTemplate(cell, spacegroup, wyckoff_sites, species = None, coordinate_precision = None) Bases: :py:obj:`FundamentalDomainTemplate` Assert that a fundamental-domain template is a true asymmetric unit. Mirror :class:`~httk.atomistic.models.structure.asu.ASUStructure`: mark a :class:`FundamentalDomainTemplate` whose Wyckoff sites are known to span a real asymmetric unit rather than merely a fundamental domain. The family exposes no ``site_coordinate_span`` hook, so this marker adds no state and inherits the fundamental-domain equality and representation. .. py:class:: FundamentalDomainTemplate(cell, spacegroup, wyckoff_sites, species = None, coordinate_precision = None) Bases: :py:obj:`httk.atomistic.models.structuretype.backend.StructuretypeBackend` Store a standard-setting fundamental domain with dummy species labels. ``FundamentalDomainTemplate`` is the fundamental-domain member of the ``Structuretype`` family, the anonymous-species, exact-geometry cell used as a representative for :class:`~httk.atomistic.models.prototype.prototype.Prototype`. :param cell: The standard-setting cell geometry. :param spacegroup: The standard-setting space group. :param wyckoff_sites: The symmetry-distinct site definitions. :param species: The distinct dummy species definitions. :param coordinate_precision: The precision recorded for the reduced coordinates. .. py:attribute:: kind :type: ClassVar[str] :value: 'asu' .. py:property:: cell :type: httk.atomistic.models.cell.cell.Cell Return the standard-setting cell. .. py:property:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup Return the standard-setting space group. .. py:property:: wyckoff_sites :type: tuple[httk.atomistic.models.structure.asu.WyckoffSite, ...] Return the symmetry-distinct site definitions. .. py:property:: species :type: tuple[httk.atomistic.models.species.species.Species, ...] Return the distinct dummy species. .. py:property:: coordinate_precision Return the reduced-coordinate precision. .. py:property:: basis_precision Return the cell-basis precision. .. py:property:: sites :type: httk.atomistic.models.sites.sites.Sites Return the expanded standard-setting sites. .. py:property:: species_at_sites :type: tuple[str, ...] Return dummy species names in expanded site order. .. py:property:: periodicity :type: tuple[bool, bool, bool] Return the periodic directions. .. py:property:: nperiodic_dimensions :type: int Return the number of periodic directions. .. py:property:: nsites :type: int Return the number of expanded sites. .. py:method:: cartesian_sites() Return the exact Cartesian expanded site positions. .. py:method:: multiplicities() Return the standard-setting multiplicity for each Wyckoff site. .. py:property:: nsites_conventional :type: int Return the number of sites in the conventional cell. .. py:property:: prototype :type: httk.atomistic.models.prototype.prototype.Prototype Return the anonymous prototype this fundamental domain folds to. The template keeps this domain's occupied Wyckoff letters and their dummy-species class partition; the exact geometry is discarded. The template's constructor re-canonicalizes the class labels by the pinned group-ordering rule. :return: The folded :class:`~httk.atomistic.models.prototype.prototype.Prototype`. .. py:class:: FundamentalDomainTemplateView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.structuretype.view_base.StructuretypeViewBase`, :py:obj:`httk.atomistic.models.structuretype.fundamental.FundamentalDomainTemplate` Recognize a lazy standard-setting prototype view from a structure. Recognition accepts optional ``tolerance`` and ``limit_denominator`` values through the recognition hints. :param obj: The structuretype-like or structure-like source. :param \*\*hints: Backend-selection and recognition hints. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the recognized prototype as a standalone value. :return: The prototype value. .. py:data:: AnonymousStructure .. py:data:: AnonymousStructureView .. py:data:: AnonymousStructureLike .. py:class:: ProtostructureLabel(obj, **hints) Bases: :py:obj:`httk.atomistic.models.protostructure.view_base.ProtostructureViewBase`, :py:obj:`str` Present a protostructure as its eager httk label string. Any faithful render is the protostructure label; the *canonical* protostructure label is the one obtained from a normalizer-canonical protostructure (for example one derived via ``canonical_asu``). This view renders the label with no affine-normalizer pass. The unsuffixed part is the httk prototype label of the erased anonymous prototype (classes ordered by Wyckoff letters, not by element as AFLOW does), followed by ``:`` and the class species names in group order. :param obj: The protostructure-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: spacegroup Return the standard-setting space group of the presented protostructure. .. py:property:: occupations Return the occupied Wyckoff positions of the presented protostructure. .. py:property:: representative .. py:property:: discriminator .. py:method:: unview() Return the presented protostructure as a standalone value. :return: The protostructure value. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:type:: ProtostructureLike :canonical: httk.atomistic.models.protostructure.backend.ProtostructureBackend | httk.atomistic.models.protostructure.view_base.ProtostructureViewBase | httk.atomistic.models.protostructure.protostructure.Protostructure | str .. py:class:: WyckoffOccupation Store one Wyckoff orbit occupied by one possibly disordered species. :param wyckoff: The Wyckoff letter in the standard setting. :param species: The real species occupying the orbit. .. py:attribute:: wyckoff :type: str .. py:attribute:: species :type: httk.atomistic.models.species.species.Species .. py:class:: Protostructure(spacegroup = None, occupations = None, *, representative = None, discriminator = None) Bases: :py:obj:`httk.atomistic.models.protostructure.backend.ProtostructureBackend` Store a standard-setting space group and its occupied Wyckoff positions. The base value is provenance-independent: recognition and derivation return a base ``Protostructure``, so a value recognized from a structure compares equal to one built by hand or parsed from a label. Multiplicities, composition, and formula derivations are defined at the standard-setting conventional-cell scale, even when the source used to recognize it was stored in a volume-scaled setting. A geometrical representative and/or a discriminator are optional refinements, present only when the user constructs the value with them; recognition never attaches them. They participate in equality and content identity: equality covers the space group, the occupations, the discriminator, and the representative when present, so two values sharing space group, occupations, and discriminator but differing in representative are not equal. :param spacegroup: The standard-setting space group or its IT number. :param occupations: The occupied Wyckoff positions and their species. :param representative: An optional exact standard-setting class anchor. :param discriminator: An optional external class discriminator. .. py:attribute:: kind :type: ClassVar[str] :value: 'protostructure' .. py:property:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup Return the standard-setting space group. .. py:property:: occupations :type: tuple[httk.atomistic.models.protostructure.occupation.WyckoffOccupation, ...] Return the canonical occupied Wyckoff positions. .. py:property:: representative :type: httk.atomistic.models.structure.asu.FundamentalDomainStructure | None Return an optional retained exact representative. .. py:property:: discriminator :type: str | None Return an optional geometrical-class discriminator. .. py:class:: ProtostructureView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.protostructure.view_base.ProtostructureViewBase`, :py:obj:`httk.atomistic.models.protostructure.protostructure.Protostructure` Recognize a lazy standard-setting protostructure view. Recognition accepts optional ``setting``, ``standard``, ``transform``, ``tolerance``, and ``limit_denominator`` values through the recognition hints. :param obj: The structure-like or protostructure-like source. :param \*\*hints: Backend-selection and recognition hints. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the recognized protostructure as a standalone value. :return: The protostructure value. .. py:class:: PrototypeLabel(obj, **hints) Bases: :py:obj:`httk.atomistic.models.prototype.view_base.PrototypeViewBase`, :py:obj:`str` Present a prototype as its eager httk label string. Any faithful render is the prototype label; the *canonical* prototype label is the one obtained from a normalizer-canonical prototype (for example one derived via ``canonical_asu``). This view renders the label with no affine-normalizer pass. :param obj: The prototype-like object to present. :param \*\*hints: Backend-selection hints. .. py:property:: spacegroup Return the standard-setting space group of the presented prototype. .. py:property:: occupations Return the class-partitioned occupations of the presented prototype. .. py:property:: representative .. py:property:: discriminator .. py:method:: unview() Return the presented prototype as a standalone value. :return: The prototype value. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:type:: PrototypeLike :canonical: httk.atomistic.models.prototype.backend.PrototypeBackend | httk.atomistic.models.prototype.view_base.PrototypeViewBase | httk.atomistic.models.prototype.prototype.Prototype | httk.atomistic.models.prototype.label.PrototypeLabel | str .. py:class:: PrototypeOccupation Store one Wyckoff orbit assigned to one anonymous species class. Unlike :class:`~httk.atomistic.models.protostructure.occupation.WyckoffOccupation`, the class carries an anonymous class label (``"A"``, ``"B"``, ...) rather than a real :class:`~httk.atomistic.Species`, so it can represent an element-agnostic prototype. :param wyckoff: The Wyckoff letter in the standard setting. :param label: The anonymous species-class label. .. py:attribute:: wyckoff :type: str .. py:attribute:: label :type: str .. py:class:: Prototype(spacegroup = None, occupations = None, *, representative = None, discriminator = None, prototype = None) Bases: :py:obj:`httk.atomistic.models.prototype.backend.PrototypeBackend` Store anonymous occupied Wyckoff positions and optional class information. The base value is provenance-independent: recognition and derivation return a base ``Prototype``, so a value recognized from a structure compares equal to one built by hand or parsed from a label. A geometrical representative and/or a discriminator are optional refinements, present only when the user constructs the value with them; recognition never attaches them. They participate in equality and content identity. :param spacegroup: The standard-setting space group or its IT number. :param occupations: The occupied Wyckoff positions and canonical anonymous labels. :param representative: An optional exact anonymous class anchor. :param discriminator: An optional external class discriminator. :param prototype: An optional existing prototype whose base and unspecified optional fields are copied. .. py:attribute:: kind :type: ClassVar[str] :value: 'prototype' .. py:property:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:property:: occupations :type: tuple[httk.atomistic.models.prototype.occupation.PrototypeOccupation, ...] .. py:property:: representative :type: httk.atomistic.models.structuretype.fundamental.FundamentalDomainTemplate | None Return an optional retained exact representative. .. py:property:: discriminator :type: str | None Return an optional geometrical-class discriminator. .. py:class:: PrototypeView(obj, **hints) Bases: :py:obj:`httk.atomistic.models.prototype.view_base.PrototypeViewBase`, :py:obj:`httk.atomistic.models.prototype.prototype.Prototype` Present a lazy anonymous geometrical-class prototype view. Sources may be an existing prototype, a Protostructure (erased to its anonymous class), or a structure-like source recognized to a representative-carrying prototype. Recognition of a raw structure accepts optional ``tolerance`` and ``limit_denominator`` values; resolution is deferred until the first field access. :param obj: The prototype-like, protostructure-like, or structure-like source. :param \*\*hints: Backend-selection and recognition hints. .. py:method:: unwrap() Return the raw object behind the backend. :return: The unwrapped source object. .. py:method:: unview() Return the recognized prototype as a standalone value. :return: The prototype value. .. py:class:: AffineOperation(matrix, vector = (0, 0, 0)) Represent an exact affine map ``x -> W x + w`` on fractional coordinates. Two operations compare equal when their matrix and translation are exactly equal. Equality is *not* modulo lattice translations — use :meth:`wrapped` first when comparing symmetry operations as members of a space group, since ``x+1/2`` and ``x+3/2`` are the same operation there but different objects here. :param matrix: The 3x3 rotation part in the column-vector convention, or a comma-separated ``"x,y,z"`` operation string (as emitted by :meth:`to_xyz` and ``repr``), in which case ``vector`` is ignored. :param vector: The translation part in fractional coordinates. .. py:method:: identity() :classmethod: Return the identity operation. :return: The identity affine operation. .. py:method:: from_record(record) :classmethod: Build an operation from either vendored affine-record shape. The record's ``matrix`` and ``vector`` hold exact rational strings (``"1/2"``, ``"-1"``), which embed exactly. :param record: The affine record, or a mapping containing one under ``"affine_transformation"``. :return: The corresponding affine operation. .. py:property:: matrix :type: httk.core.FracVector Return the 3x3 rotation part ``W`` in the column-vector convention. :return: The exact rotation matrix. .. py:property:: vector :type: httk.core.FracVector Return the translation part ``w``. :return: The exact translation vector. .. py:method:: determinant() Return the determinant of the rotation part exactly. For a symmetry operation this is ``+1`` (proper) or ``-1`` (improper). For a change of basis it is the ratio of cell volumes, so a value other than ``±1`` means the operation changes the lattice. :return: The exact determinant. .. py:method:: is_identity() Report whether this operation is the identity. :return: Whether the matrix and translation are both identity values. .. py:method:: apply(coords) Map reduced coordinates through this operation exactly. ``coords`` is a single ``(3,)`` coordinate or an ``(N, 3)`` block of them; the result has the same shape. No wrapping is applied — see :meth:`apply_wrapped`. :param coords: A single reduced coordinate or a block of reduced coordinates. :return: The transformed coordinates with the same shape as ``coords``. :raises ValueError: If ``coords`` is neither a length-three coordinate nor an ``(N, 3)`` block. .. py:method:: apply_wrapped(coords) Map coordinates and wrap every component into ``[0, 1)``. :param coords: A single reduced coordinate or a block of reduced coordinates. :return: The transformed and wrapped coordinates. :raises ValueError: If ``coords`` has an unsupported shape. .. py:method:: inverse() Return the inverse map exactly. :return: The inverse affine operation. :raises ZeroDivisionError: If the rotation part is singular. .. py:method:: conjugated_by(change) Rewrite this operation through a change of basis. If ``self`` is a symmetry operation expressed in one setting and ``change`` maps that setting's coordinates into another, the result is the same symmetry operation expressed in the other setting. :param change: The affine operation defining the coordinate change. :return: This operation conjugated by ``change``. .. py:method:: wrapped() Return this operation with its translation reduced into ``[0, 1)``. Two symmetry operations of a space group are the same element modulo lattice translations exactly when their wrapped forms are equal, which is what makes symop *sets* comparable. :return: An operation with a normalized translation. .. py:method:: to_xyz() Render the operation in ``x,y,z`` notation. For example, return ``"-x+1/2,y,-z+1/2"``. :return: The crystallographic operation string. .. py:function:: find_magnetic_symmetry(structure, tolerance = 0.001) Find the magnetic symmetry of a collinear structure and return it as symops. Runs spglib's magnetic-symmetry search on the full cell, then rebuilds the result as a :class:`~httk.atomistic.SymopsStructure` carrying, in the *input* cell: * every magnetic symmetry operation spglib found, each with its ``+1``/``-1`` time-reversal flag; * one representative site per orbit, snapped exactly onto its site-stabilizer's fixed subspace so expansion regenerates the orbit and collapses the repeats; * the representatives' Cartesian moments, carried through unchanged; * the Belov–Neronova–Smirnova number of the magnetic space group. Expanding the returned structure back to a full cell reproduces ``structure`` — same sites, species, and per-site moments — to within ``tolerance`` and up to reordering. Only collinear moments along ``z`` are accepted: every site must have ``x`` and ``y`` moment components no larger than ``tolerance``. The moments must be :class:`~httk.atomistic.CartesianSiteMoments`. :param structure: The full structure whose magnetic symmetry is sought. :param tolerance: The spglib search symprec, a Cartesian distance in the cell's units. :return: The magnetic symmetry as listed representatives plus operations. :raises ImportError: If the optional spglib dependency is unavailable. :raises ValueError: If the structure is not fully periodic, carries no Cartesian moments, has a non-collinear moment, or spglib finds no magnetic dataset. .. py:data:: DEFAULT_TOLERANCE :value: 0.001 .. py:function:: recognize_asu(structure, *, setting = None, standard = None, transform = None, tolerance = None, limit_denominator = None, _retain_found_transform = False) Build an :class:`~httk.atomistic.ASUStructure` from a full structure. The space group can be supplied three ways, in decreasing order of preference: * ``setting`` — the structure's own tabulated setting, as when a CIF names its group. Nothing is searched for and spglib is not involved. * ``standard`` together with ``transform`` — for a structure in a setting that appears in no table. Also spglib-free. * neither — the symmetry is found with spglib, which must be installed (``pip install httk-atomistic[default]``). ``tolerance`` is a Cartesian distance, measured in the real cell, so it means the same thing along a short axis and a long one; a fractional tolerance would not. Left unspecified it is **derived from how precisely the structure was stated** — see :func:`structure_tolerance` — falling back to :data:`DEFAULT_TOLERANCE` for a structure that does not say. Pass a value to override that. Raises :class:`ValueError` if a site cannot be placed on any Wyckoff position within the tolerance, or if the sites do not group into complete orbits — both of which mean the structure does not actually have the symmetry it was said to have. :param structure: The full structure to recognize. :param setting: The structure's own tabulated setting, if known. :param standard: The IT standard setting for an untabulated own setting. :param transform: The stored standard-to-own transform for an untabulated setting. :param tolerance: The Cartesian matching tolerance in the real cell, or ``None`` to derive it from the structure's stated precision. :param limit_denominator: The largest denominator allowed when idealising free parameters, or ``None`` to retain their exact stated values. :param _retain_found_transform: Internal canonicalization hook retaining spglib's recognized-to-standard transform instead of folding it into the returned basis. :return: The recognized asymmetric-unit structure. :raises ImportError: If symmetry must be searched and the optional spglib dependency is unavailable. :raises TypeError: If the supplied setting arguments are incomplete or mutually exclusive. :raises ValueError: If the structure is not fully periodic, the standard setting is invalid, or the sites cannot be placed into complete Wyckoff orbits within the tolerance. .. py:function:: structure_tolerance(structure, *, fallback = DEFAULT_TOLERANCE) Derive a matching tolerance from how precisely the structure was stated. This is the point of recording precision at all: instead of a constant somebody guessed, the tolerance follows the data. Coordinates written to four decimals in a 5 A cell are good to about ``5e-4``, and the tolerance comes out near ``1e-3``; the same coordinates in a 30 A cell justify a tolerance six times larger, and coordinates written to two decimals justify one a hundred times larger. Starts from ``fallback`` when the structure does not state a precision — a structure built by hand, or read from a format that does not write its numbers to a definite number of digits. A caller that needs to know whether that happened can compare the result against the structure's own ``cartesian_precision()``. The value is capped so that it can never reach half the smallest distance between two sites, which is what would let genuinely distinct atoms be merged. Minimum separation bounds a tolerance from above; treating it as precision could make a structure with accidentally close atoms look far more precisely stated than it is. :param structure: The structure whose stated precision determines the tolerance. :param fallback: The tolerance to use when the structure has no stated precision. :return: The Cartesian matching tolerance in the structure's cell units. :raises ValueError: If no positive finite automatic tolerance can be derived, including when distinct sites coincide under periodic images. .. py:class:: SettingTransform(matrix, vector = (0, 0, 0), *, hall_entry = None) Represent an exact rational change of basis from the IT standard setting. Wraps an :class:`~httk.atomistic.AffineOperation` and gives it the standard-to-own reading described in the module docstring, plus the cell-basis and symmetry-operation transformations that follow from it. :param matrix: The 3x3 matrix ``M`` mapping standard coordinates to the own setting. :param vector: The origin shift ``v`` in the own setting. :param hall_entry: The normalized Hall entry associated with a tabulated transform, if known. .. py:method:: identity() :classmethod: Return the transform of a structure already in its IT standard setting. :return: The identity setting transform. .. py:method:: from_hall_entry(hall_entry) :classmethod: Return the tabulated transform for one of the 527 known settings. ``hall_entry`` is the normalized Hall symbol of the setting, which names it unambiguously — symbol, axes, and origin choice together. :param hall_entry: The normalized Hall symbol naming the setting. :return: The stored standard-to-own transform. :raises KeyError: If ``hall_entry`` is not in the vendored setting table. .. py:property:: operation :type: httk.atomistic.symmetry.affine_operation.AffineOperation Return the underlying affine map from standard to own setting. :return: The underlying affine operation. .. py:property:: matrix :type: httk.core.FracVector Return the 3x3 rotation part ``M``. :return: The exact change-of-basis matrix. .. py:property:: vector :type: httk.core.FracVector Return the origin shift ``v``. :return: The exact origin-shift vector. .. py:property:: hall_entry :type: str | None Return the Hall entry used to look up this transform, if any. :return: The normalized Hall entry, or ``None`` for a caller-supplied transform. .. py:method:: determinant() Return the signed inverse volume factor ``det M``. Its magnitude satisfies ``abs(det M) = V_standard / V_own``; the sign records orientation reversal. ``1`` for 520 of the 527 tabulated settings. The exceptions are the seven rhombohedral-axes settings (IT numbers 146, 148, 155, 160, 161, 166, 167) where it is ``3``, because the standard hexagonal cell holds three primitive rhombohedral cells. A caller-supplied transform may have any non-zero value. :return: The exact determinant of ``M``. .. py:method:: is_identity() Report whether the transform is the identity. :return: Whether the matrix and origin shift leave the standard setting unchanged. .. py:method:: to_setting(coords) Map standard-setting reduced coordinates into this setting without wrapping. :param coords: A reduced coordinate or block of reduced coordinates in the standard setting. :return: The corresponding coordinates in the own setting. .. py:method:: to_standard(coords) Map own-setting reduced coordinates into the standard setting without wrapping. :param coords: A reduced coordinate or block of reduced coordinates in the own setting. :return: The corresponding coordinates in the standard setting. .. py:method:: symop_to_setting(operation) Rewrite a standard-setting symmetry operation in this setting. :param operation: The symmetry operation expressed in the standard setting. :return: The conjugated symmetry operation in the own setting. .. py:method:: symop_to_standard(operation) Rewrite an own-setting symmetry operation in the standard setting. :param operation: The symmetry operation expressed in the own setting. :return: The conjugated symmetry operation in the standard setting. .. py:method:: basis_to_setting(basis) Map a standard-setting cell basis into this setting. Follows from coordinate invariance: if ``f_own = f_std * M.T()`` then ``B_own = inv(M).T() * B_std``, so that ``f * B`` is the same Cartesian point either way. The transform is rational, so an exact basis stays exact — a hexagonal cell keeps its ``sqrt(3)``. :param basis: The standard-setting cell basis with lattice vectors as rows. :return: The own-setting cell basis with lattice vectors as rows. .. py:method:: basis_to_standard(basis) Map this setting's cell basis into the standard setting. :param basis: The own-setting cell basis with lattice vectors as rows. :return: The standard-setting cell basis with lattice vectors as rows. .. py:method:: lattice_cosets() Return the translations of this setting's cell that are standard-lattice translations. Expanding an orbit generates points from the standard setting's symmetry operations, which carry the standard lattice's periodicity. When this setting's cell is *larger* than the standard one, that is not enough: points related by a standard lattice translation are genuinely distinct sites here, and the missing ones are recovered by also applying each translation returned by this method. The result is the finite subgroup of ``(Q/Z)^3`` generated by the columns of ``M`` reduced modulo 1, always including the zero translation. It is trivial (just zero) whenever ``M`` is an integer matrix, which covers **all 527** tabulated settings — including the seven with ``det M == 3``, where this setting's cell is *smaller* and the surplus points collapse under wrapping instead. So this only ever does work for a caller-supplied transform to a supercell setting. :return: The normalized finite set of translations, including zero. .. py:method:: inverse() Return the transform in the opposite direction. :return: The transform from this setting to the standard setting. .. py:class:: Spacegroup(record) Represent a tabulated space-group setting from the vendored symmetry data. :param record: The read-only vendored mapping describing one space-group setting. .. py:method:: standard(it_number) :classmethod: Return the IT standard setting for a space-group number. :param it_number: The International Tables space-group number. :return: The IT standard setting for ``it_number``. .. py:method:: from_hall_entry(hall_entry) :classmethod: Return the setting named by a normalized Hall symbol. For example, ``"-c_2yc"`` names one setting. :param hall_entry: The normalized Hall symbol naming the setting. :return: The corresponding space-group setting. .. py:method:: from_setting(setting_it_nc) :classmethod: Return the setting named by an IT number and coordinate-system code. For example, ``"15:c1"`` names one setting. :param setting_it_nc: The IT setting identifier. :return: The corresponding space-group setting. .. py:method:: from_hm_entry(hm_entry) :classmethod: Return the setting named by a Hermann-Mauguin entry. For example, ``"C 1 2/c 1"`` names one setting. :param hm_entry: The Hermann-Mauguin symbol naming the setting. :return: The corresponding space-group setting. .. py:property:: record :type: collections.abc.Mapping[str, Any] Return the raw vendored record for fields this class does not model. :return: The source record for this setting. .. py:property:: it_number :type: int Return the International Tables space-group number. :return: The space-group number from 1 through 230. .. py:property:: setting :type: str Return the setting name, such as ``"15:c1"``. :return: The IT number and coordinate-system code. .. py:property:: hall_entry :type: str Return the normalized Hall symbol naming the setting unambiguously. :return: The normalized Hall symbol. .. py:property:: hall_symbol :type: str Return the Hall symbol as conventionally written. :return: The conventional Hall symbol. .. py:property:: hermann_mauguin :type: str Return the short Hermann-Mauguin symbol for this setting. :return: The short Hermann-Mauguin symbol. .. py:property:: hermann_mauguin_full :type: str Return the full Hermann-Mauguin symbol for this setting. :return: The full Hermann-Mauguin symbol. .. py:property:: crystal_system :type: str Return the crystal system, such as ``"monoclinic"``. :return: The crystal-system name. .. py:property:: centring_type :type: str Return the lattice centring letter, such as ``"P"``, ``"C"``, or ``"F"``. :return: The centring letter. .. py:property:: is_standard_setting :type: bool Report whether this is the IT standard setting for its space-group number. :return: Whether this setting is the IT reference setting. .. py:property:: symmetry_operations :type: tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, ...] Return every symmetry operation of the group in this setting's coordinates. The full set with centring translations already folded in, so its length is the group order and no separate centring pass is needed. :return: The complete tuple of symmetry operations. .. py:property:: centering_translations :type: tuple[httk.core.FracVector, ...] Return the lattice centring translations, including zero. :return: The centring translations in this setting. .. py:property:: wyckoff :type: tuple[httk.atomistic.symmetry.wyckoff.WyckoffPosition, ...] Return the Wyckoff positions ordered most specific first. Sorted by ``(free_count, multiplicity, letter)``, so identifying a coordinate by walking this order returns the most specific position it lies on. :return: The ordered Wyckoff positions for this setting. .. py:method:: wyckoff_position(letter) Return the Wyckoff position with the given letter. For example, ``"e"`` selects the position with letter ``e``. :param letter: The bare Wyckoff letter. :return: The matching Wyckoff position. :raises KeyError: If this setting has no position with ``letter``. .. py:method:: identify_wyckoff(coordinate) Identify the most specific Wyckoff position holding an exact coordinate. Returns ``None`` when the coordinate lies on no position, which for a complete table means the input was not an exact rational site of this group. Matching is exact: an approximate coordinate must be snapped first (see :class:`~httk.atomistic.ASUStructure`'s recognition path), never passed here in the hope that it lands. :param coordinate: The exact reduced coordinate to identify. :return: The matching position and free parameters, or ``None`` when no position matches exactly. .. py:property:: transform_from_standard :type: httk.atomistic.symmetry.setting_transform.SettingTransform Return the change of basis from the IT standard setting to this one. The identity exactly when this *is* the standard setting. :return: The stored standard-to-own setting transform. .. py:method:: standard_setting() Return the IT standard setting for this space-group number. :return: The IT standard setting. .. py:function:: wyckoff_letter_map(standard, target) Map standard-setting Wyckoff letters to their names in another setting. Almost always the identity — but not always, and the exception is silent. Across all 3210 non-reference ``(setting, letter)`` pairs in the vendored tables, exactly one setting permutes letters: in ``224:1`` the standard setting's ``j`` is that setting's ``i`` and vice versa. So a CIF that declares site ``24i`` in setting ``224:1`` does *not* mean standard-setting letter ``i``, and taking the letter at face value across a setting boundary produces the wrong structure with no error. Computed rather than hard-coded, so it survives a data refresh: each standard position is evaluated at generic parameters, mapped through the setting transform, and identified in the target's own Wyckoff table. :param standard: The IT standard setting whose letters are being mapped. :param target: The setting receiving the mapped letters. :return: A mapping from standard-setting letters to target-setting letters. :raises ValueError: If the settings belong to different space groups or the mapping is not bijective. .. py:class:: PrimitiveCellResult Store a structure in the fixed primitive cell of its conventional cell. ``transform`` is the row-convention matrix actually applied to the conventional basis: ``basis_primitive = transform * basis_conventional``. The matrices are the transposes of spglib's documented column-vector matrices, where ``B_p = B_s P_c``; fractional row coordinates therefore transform as ``f_p = f_s * transform.inv()`` and are wrapped into ``[0, 1)``. See the `spglib primitive-cell definition `_. ``multiplier`` is the exact ratio of primitive-cell site count to input site count. :param structure: The resulting primitive-cell structure. :param spacegroup: The space group of the standardized input. :param conventional: The conventional-cell result used as input. :param transform: The row-convention matrix applied to the conventional basis. :param multiplier: The exact ratio of result site count to input site count. .. py:attribute:: structure :type: httk.atomistic.models.structure.unitcell.UnitcellStructure .. py:attribute:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:attribute:: conventional :type: httk.atomistic.symmetry.standardization.ConventionalCellResult .. py:attribute:: transform :type: httk.core.FracVector .. py:attribute:: multiplier :type: fractions.Fraction .. py:function:: primitive_cell(structure, *, tolerance = None, limit_denominator = None) Return ``structure`` in the spglib-convention primitive cell. The input is first recognized or, when it already contains an asymmetric unit, used exactly as stored. Recognition arguments are rejected for an existing ASU. The recognized structure is converted to its IT standard-setting conventional cell by :func:`~httk.atomistic.conventional_cell`, then the fixed matrix for its centring type is applied exactly. Site moments are carried through as per-site data: Cartesian and collinear moments are unchanged by the basis recombination, and translation images that collapse onto one primitive site must agree, or the magnetic order needs the larger cell. Assemblies are refused because the centring collapse cannot preserve correlated site groups. This operation does not perform Niggli reduction. :param structure: The structure to express in a primitive cell. :param tolerance: The Cartesian recognition tolerance, or ``None`` to derive it. :param limit_denominator: The maximum denominator for idealised free parameters, or ``None`` to retain their exact stated values. :return: The primitive-cell structure and transform metadata. :raises ImportError: If recognition is needed and the optional spglib dependency is unavailable. :raises ValueError: If recognition arguments are invalid for the input, the structure has assemblies or crystal-axis moments, its magnetic order is incompatible with the primitive cell, it is not fully periodic, or it has an unsupported centring type. .. py:class:: ConventionalCellResult Store a structure in its space group's IT standard-setting conventional cell. ``asu`` is the new standard-setting ASU that was expanded to make ``structure``. ``transform`` is the standard-to-own transform from the ASU that was supplied to, or recognized from, the operation; its orientation is :math:`f_own = f_std M^T + v`, so this operation undoes it for the cell basis. ``multiplier`` is the exact ratio of conventional-cell site count to input-cell site count. For the 527 vendored settings it is at least one; an untabulated, caller-supplied supercell transform may still produce a ratio below one. :param structure: The resulting full conventional-cell structure. :param asu: The resulting asymmetric-unit structure in the standard setting. :param spacegroup: The space group represented by the result. :param transform: The standard-to-own transform used for the input structure. :param multiplier: The exact ratio of result site count to input site count. .. py:attribute:: structure :type: httk.atomistic.models.structure.unitcell.UnitcellStructure .. py:attribute:: asu :type: httk.atomistic.models.structure.asu.ASUStructure .. py:attribute:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:attribute:: transform :type: httk.atomistic.symmetry.setting_transform.SettingTransform .. py:attribute:: multiplier :type: fractions.Fraction .. py:function:: conventional_cell(structure, *, tolerance = None, limit_denominator = None) Return ``structure`` in its space group's IT standard-setting conventional cell. An existing :class:`~httk.atomistic.ASUStructure` (including an :class:`~httk.atomistic.ASUStructureView`, an ASU backend, or a full-cell view backed by one) is used exactly as stored. Supplying ``tolerance`` or ``limit_denominator`` for that path raises :class:`ValueError`, because those arguments belong to recognition. Any other :class:`~httk.atomistic.StructureLike` is first passed to :func:`~httk.atomistic.recognize_asu`. That tolerant step may snap measured coordinates onto symmetry positions and chooses the transform recorded in the result; it does not preserve an unstated input transform or promise a :func:`~httk.atomistic.same_crystal` match to noisy input coordinates. The optional tolerance is a Cartesian matching distance and the optional denominator limit idealises free parameters. The returned ``transform`` is the existing ASU's transform, or the transform chosen by recognition for a plain input; the returned ``asu`` has an identity transform. Construction and expansion are exact, including the rhombohedral case where the standard hexagonal cell contains three primitive cells. Basis precision is multiplied by ``M.T()`` and coordinate precision by the maximum absolute column sum of ``inv(M.T())``; unknown precision remains unknown. Requires a fully 3D-periodic structure. :param structure: The structure or asymmetric-unit structure to standardize. :param tolerance: The Cartesian recognition tolerance, or ``None`` to derive it. :param limit_denominator: The maximum denominator for idealised free parameters, or ``None`` to retain their exact stated values. :return: The standardized structure and transform metadata. :raises ImportError: If recognition is needed and the optional spglib dependency is unavailable. :raises ValueError: If recognition arguments are supplied for an existing ASU, the structure is not fully periodic, or unsupported site moments are present. .. py:function:: maximal_subgroups(spacegroup) Return the distinct tabulated maximal-subgroup IT numbers. Self-referencing isomorphic entries are excluded from graph navigation. :param spacegroup: A space group or IT number identifying the parent. :return: Sorted unique target IT numbers, excluding ``spacegroup`` itself. :raises KeyError: If the IT number has no vendored subgroup record. .. py:function:: minimal_supergroups(spacegroup) Return the distinct tabulated minimal-supergroup IT numbers. Self-referencing isomorphic entries are excluded from graph navigation. :param spacegroup: A space group or IT number identifying the subgroup. :return: Sorted unique parent IT numbers, excluding ``spacegroup`` itself. :raises KeyError: If the IT number has no vendored subgroup record. .. py:class:: SubgroupRepresentationResult Store an exact asymmetric-unit representation in a subgroup. :param asu: The subgroup-standard-setting asymmetric unit with identity transform. :param spacegroup: The subgroup space group in its standard setting. :param path: The selected maximal-subgroup transforms, in parent-first order. :param multiplier: The exact child-to-parent cell-content ratio. .. py:attribute:: asu :type: httk.atomistic.models.structure.asu.ASUStructure .. py:attribute:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:attribute:: path :type: tuple[SubgroupTransform, ...] .. py:attribute:: multiplier :type: fractions.Fraction .. py:function:: subgroup_closure(spacegroup, *, include_self = False) Return the graph-derived transitive subgroup closure. :param spacegroup: A space group or IT number identifying the parent. :param include_self: Include the root IT number in the result. :return: Sorted reachable subgroup IT numbers. :raises KeyError: If the IT number has no vendored subgroup record. .. py:function:: subgroup_representation(structure, subgroup) Express an exact ASU in a subgroup's IT standard setting. :param structure: The fully periodic parent asymmetric-unit structure. :param subgroup: The target subgroup space group or IT number. :return: The child ASU, selected maximal-subgroup path, and exact multiplier. :raises TypeError: If ``structure`` is not an :class:`ASUStructure`. :raises ValueError: If the structure is not fully periodic, carries site moments, assemblies, or molecular semantics, or if the target is not reachable. .. py:function:: supergroup_closure(spacegroup, *, include_self = False) Return the graph-derived transitive supergroup closure. :param spacegroup: A space group or IT number identifying the subgroup. :param include_self: Include the root IT number in the result. :return: Sorted reachable supergroup IT numbers. :raises KeyError: If the IT number has no vendored subgroup record. .. py:function:: canonical_asu(structure, *, tolerance = None, factors = (Fraction(1, 5), 1, 5), lift = False, preserve_chirality = True) Return the canonical :class:`~httk.atomistic.ASUStructure` of a measured structure's symmetry. This is the noisy-input counterpart to :func:`~httk.atomistic.canonicalize`: it first normalizes the exact measured geometry in P1, recognizes its symmetry with spglib, and then canonicalizes the recognized result exactly. P1 preconditioning prevents spglib's tolerance-boundary result from depending on an equivalent input shear, origin shift, or site ordering. An :class:`~httk.atomistic.ASUStructure` input is expanded to its unit cell first and the symmetry is re-recognized from the actual coordinates -- always from the geometry, never the declared label. Re-recognition can raise a declared symmetry (a hand-written low-symmetry cell whose coordinates in fact support more) and can also lower it (a declared symmetry the coordinates do not support at the derived tolerance). Recognition is swept over the ``base * factor`` symprecs from loosest to tightest. A member is accepted only when its recognized model reproduces every input site within the **base** tolerance (never the swept one), by an injective same-species match, and matches the per-species site counts. The first accepted member wins -- by the same operation-count monotonicity the loosest fitting member is the highest-symmetry one -- so recognition (and the expensive stage) runs once in the common case, and a looser member still rescues a tolerance-boundary flip a tighter one fails. ``lift`` selects the expensive stage applied to that winner: * ``lift=False`` (default): it is mapped to the deterministic canonical representative *within its recognized group* -- the exact terminal representation (setting, origin, orbit representatives, basis orientation all fixed), returned *without* searching upward. The result is the canonical form of the recognized symmetry; no pseudosymmetry above it is sought. * ``lift=True``: it is additionally run through the exact upward search (:func:`~httk.atomistic.canonicalize`) to find higher pseudosymmetry the recognition missed. This is exact but can be expensive -- minutes and beyond for low-symmetry, many-atom cells. Tolerance bound: the recognition stage is held to the base tolerance -- every returned atom sits within ``base`` of the input. Under ``lift=False`` that is the whole bound (no further hops). Under ``lift=True`` each lift hop can move coordinates and snap the metric by up to another ``base`` and the residual/path are not re-checked here, so the returned structure's distance from the input is bounded roughly by ``base * (1 + hops)``. Determinism: the recognition stage is floating-point/spglib-based, so its outcome is reproducible on one platform but may differ across floating-point architectures or spglib builds. The exact stage is platform-independent and erases spglib's representational freedom for ordinary rational crystallographic Gram matrices, so cross-platform variation is confined to *which* symmetry is accepted near a tolerance boundary, never to *how* an accepted symmetry is represented. An exact non-rational Gram whose canonical Cartesian factor requires nested radicals outside the supported surd field remains idempotent but can retain its input's global Cartesian rotation. Free-parameter values are least-squares fits of the measured coordinates, so two noisy measurements of the same crystal reach the same Wyckoff choices but slightly different rational parameter values. :param structure: The measured structure, ``UnitcellStructure`` or ``ASUStructure``. :param tolerance: The base Cartesian tolerance, or ``None`` to derive it from the structure's stated precision (:func:`~httk.atomistic.symmetry.recognition.structure_tolerance`). :param factors: Multipliers for the recognition symprec sweep; each candidate symprec is ``base * factor``. :param lift: Whether to search upward for pseudosymmetry above the recognized group (default ``False``: return the canonical representative of the recognized symmetry). :param preserve_chirality: How enantiomorphic space groups are canonicalized. By default (``True``) the recognized group is kept, so a genuinely chiral crystal retains its handedness. When ``False`` a result landing in the higher member of one of the 11 enantiomorphic pairs (76/78, 91/95, 92/96, 144/145, 151/153, 152/154, 169/170, 171/172, 178/179, 180/181, 212/213) is mapped to the LOWER-numbered member by an exact chirality-flipping transformation (fractional coordinates ``f -> (-f) mod 1`` with the cell basis unchanged -- the Cartesian inversion ``r -> -r`` -- and the group swapped to its partner), so an enantiomorphic pair shares one canonical representative and the canonical labels of the two partners coincide. The exact bridge :func:`~httk.atomistic.normalize_chirality` maps a preserved (``True``) result to the normalized (``False``) one directly, without re-canonicalizing. A structure carrying site moments is never flipped (axial vectors are out of scope under improper maps) and is left in its own group regardless of this flag. :return: The canonical asymmetric unit. :raises ImportError: If spglib is unavailable when symmetry must be searched (the error names the ``httk-atomistic[default]`` extra). :raises ValueError: If recognition fails or is rejected at every swept tolerance. .. py:class:: LiftResult One exact or tolerance-accepted parent representation. :param asu: The parent-standard-setting asymmetric unit. :param spacegroup: The parent space group in standard setting. :param path: Child-first tabulated parent-to-child subgroup transforms used. :param shift: The continuous-normalizer origin shift from the final hop, expressed in that hop's parent standard frame. ``path`` and ``shift`` document the lift route; they do not by themselves reconstruct ``asu``, since :func:`highest_symmetry` additionally passes each state through an unrecorded normal form and canonical orientation. ``asu`` is authoritative. When a default (chirality-normalizing) canonicalization flips an enantiomorphic terminal, ``path`` and ``shift`` describe the route to the pre-flip higher-member terminal, while ``asu``/``spacegroup`` carry the flipped lower-member result -- ``asu`` remains authoritative. :param residual: The largest wrapped fractional residual accepted. .. py:attribute:: asu :type: httk.atomistic.models.structure.asu.ASUStructure .. py:attribute:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:attribute:: path :type: tuple[httk.atomistic.symmetry.subgroups.SubgroupTransform, ...] .. py:attribute:: shift :type: httk.core.FracVector .. py:attribute:: residual :type: fractions.Fraction .. py:function:: backward_lift(structure, supergroup, *, tolerance = None) Return all exact or tolerance-accepted lifts into one minimal supergroup. :param structure: The child-group asymmetric unit to lift. :param supergroup: The one-hop parent space group or IT number. :param tolerance: Cartesian acceptance tolerance, or the recognition-derived default. :return: Distinct parent representations in table order and canonical order. :raises ValueError: If the input is unsupported or the target is not one hop above it. A bounded normalizer retry applies tabulated cosets to child fractional coordinates and maps successful results back with the exact inverse, in tabulated coset order. .. py:function:: canonicalize(structure, *, tolerance = None, preserve_chirality = True) Return the first deterministic highest-symmetry representation. The result is the normalizer-canonical representative of the input's crystal: the same exact ``(it_number, sorted (species, wyckoff, free_params), cell basis)`` for any origin shift, cell-basis choice (relabeling/shear), or site ordering of that crystal, and coherent with direct entry at its own space group. See :func:`highest_symmetry` for the full contract; for a P1/unit-cell start build the ASU in SG 1 and pass it here. :param structure: The structure to canonicalize. :param tolerance: Cartesian acceptance tolerance, or the recognition-derived default. :param preserve_chirality: When ``True`` (the default), the recognized group is kept, so a genuinely chiral crystal retains its handedness. When ``False``, a result in the higher member of an enantiomorphic pair is normalized to its lower-numbered partner by an exact chirality flip (magnetic structures excepted; :func:`~httk.atomistic.normalize_chirality` is the standalone bridge). See :func:`highest_symmetry`. :return: The canonical terminal lift. .. py:function:: highest_symmetry(structure, *, tolerance = None, all_paths = False, preserve_chirality = True) Return all terminal upward lifts reached by breadth-first search. :param structure: The starting asymmetric-unit structure. :param tolerance: Cartesian acceptance tolerance, or the recognition-derived default. :param all_paths: When ``False`` (default) the visited set collapses alternate Bärnighausen routes to one entry per state, so each terminal appears once. When ``True`` the visited set also keys on the accumulated path, so every distinct ``(terminal, path)`` pair is returned; the ``.asu`` representatives of the extra results are identical, only ``path`` differs. The state cap therefore binds sooner under the flag. :param preserve_chirality: When ``True`` (the default), the recognized group is kept. When ``False``, a terminal landing in the higher member of an enantiomorphic pair is flipped by an exact chirality transformation to its lower-numbered partner and re-normal-formed in that partner group. The flip is applied only at terminal emission, never to mid-search states (the Bärnighausen tables are per-group). :return: Deterministically ordered highest-symmetry representations. :raises ValueError: If the input is unsupported, or if the breadth-first search exceeds its visited-state cap. A per-parent modular-solver branch-cap failure is not raised: that parent target is skipped and reported through the ``"symmetry"`` warning channel, so in that rare case the returned symmetry may be lower than the true maximum. The noisy least-squares fallback is capped the same way -- a candidate whose integer-wrap box exceeds the noisy cap is skipped (also on the ``"symmetry"`` warning channel), which could likewise lower the returned symmetry for a genuinely noisy large-box lift. An exact P1 supercell entry is first collapsed to its unique primitive description (any multiplicity or sublattice orientation), and a triclinic (SG 1 or 2) entry is then Niggli-reduced so the search is independent of the input basis choice. Each search state is then reduced to its normalizer-canonical normal form -- special-site demotion plus the continuous- and discrete-Euclidean-normalizer translation quotients and the affine-normalizer coset quotient -- collapsing origin-, basis- and normalizer-equivalent representations to one visited entry so the search terminates from a raw P1 input. The returned ``asu`` is that normalizer-canonical representative, its cell placed in the standard orientation of its metric, so the result is invariant under origin shift, cell-basis choice, and site order for the same crystal. ``path`` records the tabulated hops of the route that reached it, and a bounded normalizer retry along that route applies tabulated cosets to child coordinates and maps results back with the exact inverse, in tabulated coset order. .. py:function:: lift_candidates(structure, *, tolerance = None) Return all one-hop parent lifts in deterministic order. :param structure: The child-group asymmetric unit to lift. :param tolerance: Cartesian acceptance tolerance, or the recognition-derived default. :return: Results ordered by parent IT number, table order, and exact key. .. py:function:: normalize_chirality(structure) Collapse a canonical ASU's higher enantiomorph onto its lower-numbered partner. Structures outside the higher member of an enantiomorphic pair, including magnetic structures, are returned by identity. A flipped partner is put back into its canonical normal form. .. py:function:: rerepresent(structure, target, *, tolerance = None) Express a structure in a reachable subgroup or supergroup setting. :param structure: The input asymmetric-unit structure. :param target: The target space group or IT number. :param tolerance: Cartesian acceptance tolerance for upward lifts. :return: The target-group asymmetric unit. :raises ValueError: If the target is unrelated, an upward hop has no lift, or a cross-group rerepresentation requires descending or lifting a structure with site moments, assemblies, or molecular semantics. .. py:class:: StructurePath A finite exact interpolation path between two aligned asymmetric units. :param frames: The endpoint-inclusive asymmetric-unit frames. :param spacegroup: The shared space group and setting of all frames. :param start: The first frame. :param end: The last frame. .. py:attribute:: frames :type: tuple[httk.atomistic.models.structure.asu.ASUStructure, ...] .. py:attribute:: spacegroup :type: httk.atomistic.symmetry.spacegroup.Spacegroup .. py:attribute:: start :type: httk.atomistic.models.structure.asu.ASUStructure .. py:attribute:: end :type: httk.atomistic.models.structure.asu.ASUStructure .. py:function:: canonicalize_full(structure, target, *, tolerance = None) Return the canonically least representation of a crystal in a target group's standard setting. The least element, by exact orbit-canonical site key then cell gram, of :func:`list_representations`. On the crystal's own group this is a normalizer-canonical form: it selects the same representative the upward search's normal form does, over the same discrete normalizer crossing and modulo the continuous quotient. It is idempotent -- re-running it on its own result in the same target returns that result. This honors the explicit ``target`` exactly and never flips an enantiomorphic group; normalizing an enantiomorphic pair to its lower-numbered member is the closed-target canonicalizers' (:func:`~httk.atomistic.canonicalize`, :func:`~httk.atomistic.canonical_asu`) job. :param structure: The crystal, as an asymmetric-unit structure. :param target: The target space group or IT number. :param tolerance: Cartesian acceptance tolerance passed to any upward lift; ``None`` derives it. :return: The canonically least representation in ``target``'s standard setting. :raises ValueError: If ``target`` is unrelated, or the input is unsupported. .. py:function:: interpolate_structures(start, end, *, steps, tolerance = None) Build an exact symmetry-preserving linear interpolation. Free parameters follow the wrapped shortest rational displacement and cell bases are linearly interpolated in the shared setting. Every intermediate frame is expanded so a collision with an already occupied orbit is reported with its step index. Frames carry the start structure's setting transform, while their Wyckoff parameters remain standard- setting values. :param start: The first endpoint. :param end: The second endpoint. :param steps: Number of endpoint-inclusive frames, at least two. :param tolerance: Cartesian tolerance passed to upward rerepresentation. :return: The exact interpolation path. :raises ValueError: If endpoints cannot be aligned, charges differ, or an intermediate frame is invalid. .. py:function:: list_representations(structure, target, *, tolerance = None) Return every distinct representation of one crystal in a target group's standard setting. The crystal is first expressed once in ``target`` by :func:`~httk.atomistic.symmetry.lift.rerepresent` -- an exact descent for a subgroup target, a round-trip-gated lift for a supergroup target, itself for the same group -- and the full discrete affine-normalizer orbit of that one realization is then enumerated. Every representation is returned in its continuous-translation normal form (otherwise a polar or triclinic target would have infinitely many), deduplicated by exact orbit-canonical site key and cell gram, and sorted by that key. **Scope.** When ``target`` is the crystal's *own* full symmetry group, two representations differ only by an element of that group's affine normalizer, so this one orbit is the complete set -- modulo the continuous normalizer and limited only by the bounded tabulated coset table. For a PROPER-SUBGROUP (or supergroup) target only the normalizer orbit of the single :func:`~httk.atomistic.symmetry.lift.rerepresent` embedding is returned; inequivalent embeddings reachable by *other* descent chains -- the same crystal at the same cell size but a genuinely different site placement -- are deliberately out of scope and are NOT returned, because enumerating every chain is combinatorially explosive for deep targets (many tabulated chains), so a single canonical embedding is chosen. Representations needing an untabulated conventional-cell re-choice (the A.5 recell-class freedom) are likewise not generated. A supercell description is the same crystal in a larger cell; it too is not enumerated -- the exclusion there is "not a distinct representation at the same cell size", not "not the same crystal". This honors the explicit ``target`` exactly and never flips an enantiomorphic group; normalizing an enantiomorphic pair to its lower-numbered member is the closed-target canonicalizers' (:func:`~httk.atomistic.canonicalize`, :func:`~httk.atomistic.canonical_asu`) job. :param structure: The crystal, as an asymmetric-unit structure. :param target: The target space group or IT number. :param tolerance: Cartesian acceptance tolerance passed to any upward lift; ``None`` derives it. :return: The distinct representations in ``target``'s standard setting, sorted by canonical key. :raises ValueError: If ``target`` is unrelated to the crystal's group, or the input is unsupported by the exact symmetry machinery. .. py:function:: represent_like(structure, reference, *, tolerance = None) Represent a structure in a reference's group and setting. The input is first sent through :func:`~httk.atomistic.symmetry.lift.rerepresent`, then equivalent affine-normalizer coset images of that one descent realization are scored against the reference. This is deliberately bounded: tabulated variants of alternate multi-hop descent paths are not enumerated because :func:`~httk.atomistic.symmetry.lift.rerepresent` exposes only its deterministic selected realization. Site pairing is brute force and capped at 40,320 permutations per class; larger classes require a future assignment solver. :param structure: The structure to represent. :param reference: The structure supplying the group, setting, and alignment target. :param tolerance: Cartesian tolerance passed to upward rerepresentation. :return: The input represented in the reference's group and setting. :raises ValueError: If the groups are unrelated, signatures differ, or the input is unsupported by the exact symmetry machinery. .. py:function:: structure_delta(first, second, *, tolerance = None) Return the total Cartesian atom travel between two compatible structures. Each exact asymmetric-unit or fundamental-domain input is first canonicalized in its declared space group, without symmetry recognition. The canonical structures are then expressed in every compatible common Bärnighausen subgroup, in the same descending-symmetry order used by :func:`~httk.atomistic.symmetry.paths.common_subgroup_representation`, and the second is aligned through the bounded affine-normalizer search used by :func:`~httk.atomistic.symmetry.paths.represent_like`. Compatible full :class:`~httk.atomistic.Species` and Wyckoff-letter classes are paired one-to-one, choosing the minimum total physical travel within each class. Every member of each paired Wyckoff orbit contributes its shortest Cartesian distance to the total; the first and second positions are converted with their respective endpoint cells, so a lattice deformation contributes even when fractional coordinates do not change. Periodic endpoint images are selected by a finite closest-vector search in the arithmetic mean endpoint metric. This remains correct for skew cells and is symmetric when the endpoints are interchanged. The return value is a finite non-negative ``float`` in the units of the cells' bases (ångström for ordinary crystallographic structures). Both directed bounded normalizer alignments are considered for each common subgroup, and their least travel is used. This makes the metric symmetric without pretending to enumerate every possible Bärnighausen embedding. The subgroup and normalizer searches are deliberately bounded: only the deterministic subgroup embedding exposed by :func:`~httk.atomistic.symmetry.lift.rerepresent` and its tabulated normalizer images are considered. The recognized space group of either input, when it is a common subgroup, is the most faithful shared representation and is evaluated first; the travel of the first such group that yields a finite delta is returned (so two same-group structures are aligned in their own group, not a same-order sibling). Only when neither input's own group is common does the search descend the remaining common subgroups in descending-symmetry order, evaluating at most ``_STRUCTURE_DELTA_SUBGROUP_LIMIT`` of them and returning at an exact coincidence or the least travel seen within that bound. Each subgroup considers both directed bounded normalizer alignments and every tabulated normalizer image, scoring each by its exact per-orbit Cartesian travel and keeping the minimum, which makes the metric symmetric. Atom and orbit assignment uses a deterministic Hungarian minimum-cost matching, so repeated Wyckoff classes do not require a factorial permutation search. Charges do not enter this geometrical metric. :param first: The first fully periodic, non-molecular asymmetric-unit or fundamental-domain structure. :param second: The second fully periodic, non-molecular asymmetric-unit or fundamental-domain structure. :param tolerance: Cartesian tolerance passed only to any required upward rerepresentation. :return: Total atom travel in the endpoint cells' length units. :raises ValueError: If the structures are unsupported, cannot be represented in a common subgroup, have incompatible species/Wyckoff classes, or yield a non-finite travel. .. py:class:: WyckoffPosition(record) Represent a Wyckoff position of one space-group setting. :param record: The vendored record describing the Wyckoff position. .. py:method:: from_record(record) :classmethod: Build a Wyckoff position from a vendored record. :param record: The vendored Wyckoff-position record. :return: The corresponding Wyckoff position. .. py:property:: letter :type: str Return the bare Wyckoff letter, such as ``"e"``. :return: The Wyckoff letter without a multiplicity prefix. .. py:property:: multiplicity :type: int Return the number of sites generated by one parameter set. :return: The position multiplicity in the unit cell. .. py:property:: site_symmetry :type: str Return the site-symmetry group in Hermann-Mauguin notation. :return: The site-symmetry symbol. .. py:property:: free :type: tuple[int, ...] Return the indices of the free parameters in ``(x, y, z)``. :return: The free-parameter indices. .. py:property:: free_count :type: int Return the number of degrees of freedom of the position. :return: The number of free parameters, from zero through three. .. py:property:: branches :type: tuple[WyckoffBranch, ...] Return the complete, deduplicated orbit branches. :return: One branch for each equivalent site. .. py:property:: representative :type: WyckoffBranch Return the first orbit member printed as ``first_orbit`` in the tables. :return: The representative orbit branch. .. py:method:: coordinates(parameters) Compute every coordinate of the orbit as an exact ``(multiplicity, 3)`` block. Not wrapped and not deduplicated: within one setting the tabulated orbit is already distinct, so wrapping is the caller's business (and matters only once a setting transform enters). :param parameters: The free-parameter values for the position. :return: The unwrapped coordinates of all orbit branches. :raises ValueError: If the number of parameters does not match a branch. .. py:method:: parameters_of(coordinate) Recover free parameters placing some branch on ``coordinate``, if possible. Tries every branch, not only the representative. That matters: across the vendored tables, 11673 of the 20639 non-representative orbit members lie on a different branch than the representative, so a matcher that only tested ``first_orbit`` would reject a majority of legitimate orbit points. :param coordinate: The exact reduced coordinate to match. :return: The normalized free parameters, or ``None`` when no branch matches. .. py:function:: wyckoff_positions(record) Build the Wyckoff positions of a setting record, most specific first. Ordered by ``(free_count, multiplicity, letter)`` so that the first match found when identifying a coordinate is the most specific position it lies on. Ties do not arise: positions are affine subspaces, so a coordinate on two distinct positions of the same dimension also lies on their lower-dimensional intersection, which is covered by an earlier entry. :param record: The vendored space-group setting record. :return: The setting's ordered Wyckoff positions. .. py:function:: asu_structure_from_cif(data, *, tolerance = None, limit_denominator = None, trust_declared_symmetry = True, allow_large_cif_uncertainty = False, repair = False) Build an exact :class:`~httk.atomistic.ASUStructure` from a neutral CIF mapping. ``data`` is one block of the mapping returned by ``httk.atomistic.io.cif`` (its ``format`` must be ``"cif"``). The cell is built exactly from the file's ``a, b, c, alpha, beta, gamma`` rather than from the pre-multiplied floating-point basis, so a cubic cell keeps exact right angles and a hexagonal one keeps its ``sqrt(3)`` instead of inheriting rounding noise. Coordinates are embedded as the rational the file literally wrote — ``0.3333`` is ``3333/10000``, not the binary value of ``float("0.3333")`` — and are then snapped onto the Wyckoff position they lie within ``tolerance`` of. That snapping is the only tolerant step; see :mod:`~httk.atomistic.symmetry.recognition` for the full contract. ``tolerance`` left unspecified is derived from the precision the file's own digits imply, so a coarsely written file is matched loosely and a carefully written one tightly, without anybody choosing a constant. Site occupancies become the composition of the corresponding :class:`~httk.atomistic.Species`, so a half-occupied site survives into the structure instead of being dropped. ``trust_declared_symmetry=False`` ignores the file's declared Hall symbol or space-group number and identifies the setting from its symmetry operations alone; see :func:`cif_setting` for when that is the right thing to do. :param data: One loaded CIF data block. :param tolerance: The Cartesian matching tolerance, or ``None`` to derive it from the CIF. :param limit_denominator: The maximum denominator for snapped free parameters, if supplied. :param trust_declared_symmetry: Whether to validate the declared symmetry before matching operations. :param allow_large_cif_uncertainty: Whether to allow positional uncertainty at or above one angstrom. :param repair: Apply documented CIF input repairs with warnings; atom-type normalization is unconditional. :return: The exact asymmetric-unit structure. :raises ValueError: If the block format, symmetry, coordinates, occupancies, or Wyckoff matches are invalid. .. py:function:: asu_structures_from_cif(payload, *, repair = False, **options) Return every structure in a loaded CIF payload, one per structural data block. Accepts either a whole loaded payload (with ``blocks``) or a single block. Reading a CIF is tolerant — a file may hold blocks that are not structures at all — but *asking it for structures* is not. If the file yielded none, the reasons the reader recorded are raised here rather than returning an empty list, so a file that could not be interpreted does not read as a file that contained nothing. :param payload: The loaded whole-CIF payload or one loaded CIF block. :param repair: Apply documented CIF input repairs other than unconditional atom-type normalization, also enabled by a stamped payload. :param \*\*options: Options forwarded to :func:`asu_structure_from_cif`. :return: One asymmetric-unit structure for each structural data block. :raises ValueError: If the payload has no interpretable structural data or a block is invalid. .. py:function:: cif_setting(data, *, trust_declared_symmetry = True) The space-group setting a CIF block is written in. The setting is identified from the file's symmetry **operations**, by exact set comparison against the tabulated settings. That is what makes a file written in a non-standard setting come out as itself rather than being silently reinterpreted. What the file *declares* — a Hall symbol, an International Tables number, or a recognized H-M symbol — is treated as a claim to be checked, not a hint to be taken or dropped. A declaration that names no known setting, or that names one whose operations are not the file's, is a genuine inconsistency in the file and raises rather than being worked around: the two halves of the file disagree, and quietly believing one of them is how a wrong structure gets built. An unrecognized H-M spelling is the exception and remains ignored. Pass ``trust_declared_symmetry=False`` to ignore the declaration entirely and identify the setting from the operations alone. That is the escape hatch for a file whose symbols are known to be wrong but whose operations are good. A Hermann-Mauguin symbol is consulted, when neither a Hall symbol nor an International Tables number is declared, only if its normalized spelling is recognized. A recognized symbol narrows the candidate IT number; the operations still identify the exact setting and a contradiction fails like a contradicting IT-number declaration. Unrecognized H-M spellings are ignored for compatibility with the previous operations-only behavior. Raises :class:`ValueError` when the block states no operations, when a declaration is inconsistent with them, or when the operations match no tabulated setting at all. In the last case the transform to the standard setting genuinely cannot be *derived* — infinitely many are equally valid and they describe different crystals — so such a file has to be built with an explicit :class:`~httk.atomistic.SettingTransform`. :param data: The loaded CIF data block. :param trust_declared_symmetry: Whether to check the declared Hall, IT, or H-M symbol. :return: The tabulated space-group setting matching the block's operations. :raises ValueError: If operations are absent, inconsistent with the declaration, or unknown. .. py:class:: Assembly Represent one site-disorder assembly without normalizing its probabilities. :param sites_in_groups: The non-overlapping site-index groups in the assembly. :param group_probabilities: The probability assigned to each group. :param group_probabilities_precision: The precision of each group probability, if known. .. py:attribute:: sites_in_groups :type: tuple[tuple[int, ...], ...] .. py:attribute:: group_probabilities :type: tuple[fractions.Fraction, ...] .. py:attribute:: group_probabilities_precision :type: tuple[fractions.Fraction | None, ...] | None :value: None .. py:property:: normalized :type: bool Whether the group probabilities sum to one within their precision. .. py:property:: normalization_status :type: str Return the probability normalization status. .. py:property:: normalization_diagnostic :type: httk.atomistic.models.formula.diagnostics.CompositionDiagnostic | None Return the normalization diagnostic, if the probabilities are outside precision. .. py:class:: ChemicalComposition(amounts, mode = 'implicit', amounts_precision = None) Store explicit elemental amounts as additional or authoritative composition. ``implicit`` amounts supplement the site-derived composition; ``full`` amounts replace it while still recording a mismatch diagnostic when the two disagree. :param amounts: The positive amounts for named chemical elements. :param mode: Whether the amounts are ``"implicit"`` or authoritative ``"full"`` values. :param amounts_precision: The precision of the stated amounts, if known. .. py:attribute:: amounts :type: tuple[tuple[str, fractions.Fraction], ...] .. py:attribute:: amounts_precision :type: tuple[tuple[str, fractions.Fraction | None], ...] .. py:attribute:: mode :type: Literal['implicit', 'full'] .. py:property:: elements :type: tuple[str, ...] Return the element symbols in the stored amount order. .. py:property:: amount_mapping :type: collections.abc.Mapping[str, fractions.Fraction] Return the elemental amounts as a read-only mapping. .. py:property:: precision_mapping :type: collections.abc.Mapping[str, fractions.Fraction | None] Return the amount precisions as a read-only mapping. .. py:function:: atomic_number(symbol) Return the atomic number of an element symbol. The pseudo-symbols ``"X"`` and ``"vacancy"`` are not elements here. :param symbol: The IUPAC element symbol. :return: The element's atomic number. :raises ValueError: If ``symbol`` is not one of the 118 element symbols. .. py:function:: symbol_of(z) Return the element symbol for an atomic number. :param z: The atomic number in the range 1 through 118. :return: The corresponding IUPAC element symbol. :raises ValueError: If ``z`` is outside the range 1 through 118. .. py:class:: SupercellResult Store a materialized supercell with its exact construction metadata. ``orthogonality_score`` is the sum of the squared pairwise cosines between cell vectors. ``cubicity_score`` is the squared Frobenius distance between the trace-normalized Gram matrix and the identity. Both are exact :class:`~httk.core.SurdScalar` values; zero proves the ideal shape exactly. :param structure: The resulting full-periodic unit-cell structure. :param transformation: The integer row-convention transformation applied to the source basis. :param multiplier: The exact number of source cells represented in the result. :param orthogonality_score: The exact orthogonality score of the result. :param cubicity_score: The exact cubicity score of the result. .. py:attribute:: structure :type: httk.atomistic.models.structure.unitcell.UnitcellStructure .. py:attribute:: transformation :type: httk.core.FracVector .. py:attribute:: multiplier :type: int .. py:attribute:: orthogonality_score :type: httk.core.SurdScalar .. py:attribute:: cubicity_score :type: httk.core.SurdScalar .. py:function:: build_supercell(structure, transformation, *, max_sites = DEFAULT_MAX_SITES) Build the exact supercell selected by an integer transformation matrix. Lattice vectors are rows and the returned basis is ``transformation * basis``. Reduced coordinates are transformed by the inverse matrix and wrapped into ``[0, 1)``. Any input representation is first presented as a full :class:`~httk.atomistic.models.structure.unitcell.UnitcellStructure`. Crystal-axis site moments are converted to Cartesian moments because the supercell has new crystal axes; Cartesian and collinear moments retain their representation. Structure charge and explicit composition amounts are scaled by the exact cell-content multiplier. Requires a fully 3D-periodic structure. Repeating a slab within its own plane is a perfectly sensible operation, but it is not this one: the transformation matrix here mixes all three rows and the coordinates are wrapped in all three directions, so applied to a reduced-periodicity cell it would generate images along a direction that has no lattice translation. Refused rather than half-supported. :param structure: The structure to replicate. :param transformation: A nonsingular integer transformation matrix, or a positive integer selecting a diagonal repetition. :param max_sites: The maximum allowed resulting site count, or ``None`` for no limit. :return: The materialized supercell and its exact construction metadata. :raises ValueError: If the transformation, site limit, cell, or periodicity is invalid. .. py:function:: cubic_supercell(structure, multiplier = None, *, tolerance = None, max_multiplier = None, search_radius = 1, max_sites = DEFAULT_MAX_SITES) Build the most cubic supercell in the bounded candidate set. Exactly one of ``multiplier`` and ``tolerance`` must be provided. With ``multiplier``, it is the exact number of source cells in the result. With ``tolerance``, the multiplier is increased from one until the exact cubicity score is at most the given bound, up to ``max_multiplier``. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most ``search_radius`` (0--2); diagonal factorizations provide guaranteed determinant-matching fallbacks. :param structure: The structure to replicate. :param multiplier: The exact positive cell-content multiplier, or ``None`` to search. :param tolerance: The maximum cubicity score, or ``None`` to use ``multiplier``. :param max_multiplier: The largest multiplier considered during a tolerance search. :param search_radius: The integer-entry radius around the ideal candidate transform. :param max_sites: The maximum resulting site count, or ``None`` for no limit. :return: The selected supercell and its exact construction metadata. :raises ValueError: If the arguments are inconsistent, invalid, or no candidate meets the bound. .. py:function:: orthogonal_supercell(structure, multiplier = None, *, tolerance = None, max_multiplier = None, search_radius = 1, max_sites = DEFAULT_MAX_SITES) Build the most orthogonal supercell in the bounded candidate set. Exactly one of ``multiplier`` and ``tolerance`` must be provided. With ``multiplier``, it is the exact number of source cells in the result. With ``tolerance``, the multiplier is increased from one until the exact orthogonality score is at most the given bound, up to ``max_multiplier``. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most ``search_radius`` (0--2); diagonal factorizations provide guaranteed determinant-matching fallbacks. Exact orthogonality is ranked first and cubicity breaks equal-shape ties. :param structure: The structure to replicate. :param multiplier: The exact positive cell-content multiplier, or ``None`` to search. :param tolerance: The maximum orthogonality score, or ``None`` to use ``multiplier``. :param max_multiplier: The largest multiplier considered during a tolerance search. :param search_radius: The integer-entry radius around the ideal candidate transform. :param max_sites: The maximum resulting site count, or ``None`` for no limit. :return: The selected supercell and its exact construction metadata. :raises ValueError: If the arguments are inconsistent, invalid, or no candidate meets the bound. .. py:class:: NiggliReducedStructureResult Store a structure whose cell and fractional coordinates are in Niggli form. ``transform`` uses the row-vector convention ``basis_reduced = transform * basis``; site coordinates are remapped by its exact inverse and wrapped into ``[0, 1)``. :param structure: The structure expressed in the reduced cell. :param cell: The reduced cell. :param transform: The integer row-convention transform from the source basis. .. py:attribute:: structure :type: httk.atomistic.models.structure.unitcell.UnitcellStructure .. py:attribute:: cell :type: httk.atomistic.models.cell.cell.Cell .. py:attribute:: transform :type: httk.core.FracVector .. py:class:: NiggliReductionResult Store a cell in exact Niggli-reduced form. ``transform`` uses the row-vector convention ``basis_reduced = transform * basis``. Its entries are integers and its determinant is +1. ``parameters`` contains the reduced ``(A, B, C, xi, eta, zeta)`` metric parameters as exact fractions. :param cell: The reduced cell. :param transform: The integer row-convention transform from the source basis. :param parameters: The reduced exact metric parameters. .. py:attribute:: cell :type: httk.atomistic.models.cell.cell.Cell .. py:attribute:: transform :type: httk.core.FracVector .. py:attribute:: parameters :type: tuple[fractions.Fraction, ...] .. py:function:: is_niggli_reduced(cell) Return whether a fully periodic cell satisfies the complete exact Niggli conditions. :param cell: The cell to inspect. :return: Whether the cell satisfies the exact Niggli conditions. :raises ValueError: If the cell is not fully periodic or its Gram matrix is not rational. .. py:function:: niggli_reduce(cell) Return the exact Niggli reduction of a fully periodic cell. The calculation uses the rational Gram matrix with no tolerance. The returned integer transform follows ``basis_reduced = transform * basis`` and has determinant +1. :param cell: The fully periodic cell to reduce. :return: The reduced cell, transform, and exact metric parameters. :raises ValueError: If the cell is not fully periodic or its Gram matrix is not rational. .. py:function:: niggli_reduced(structure) Return a structure remapped into the exact Niggli-reduced cell. The site order and count are unchanged. With row-vector fractional coordinates, the exact remapping is ``f_reduced = f_original * transform.inv()`` followed by periodic normalization. Species, species-at-sites order, Cartesian site moments, molecular information, assemblies, chemical composition, formulas, optimization type, charge, and precision are carried unchanged or propagated. Symmetry is invalidated because its operations are basis-relative; immutable identifiers and last-modified metadata are invalidated because this operation creates a derived structure. :param structure: The structure to express in a Niggli-reduced cell. :return: The reduced structure and its exact reduction metadata. :raises ValueError: If the structure cell is not fully periodic or its Gram matrix is not rational.