httk.atomistic.structure_entries
================================

.. py:module:: httk.atomistic.structure_entries

.. autoapi-nested-parse::

   An :class:`~httk.core.EntryProvider` serving OPTIMADE ``structures`` from httk-atomistic.

   :class:`StructureEntryProvider` maps :class:`~httk.atomistic.Structure` objects to
   the neutral httk-core entry-provider contract, so a serving module (such as
   *httk-optimade*) can expose them as an OPTIMADE ``structures`` endpoint without
   this module depending on the serving module. The served entry type is described
   by the vendored OPTIMADE standard ``structures`` definition (loaded via
   :func:`httk.core.load_entry_type_definition`).

   Beyond the core structural fields, the provider auto-derives the standard
   composition fields (``nperiodic_dimensions``, ``dimension_types``,
   ``elements_ratios``, ``chemical_formula_reduced`` / ``_anonymous`` /
   ``_descriptive``) for ordered structures, may serve custom database-specific
   properties layered on via an
   :meth:`~httk.core.EntryTypeDefinition.extended` definition, and may map an entry
   id to ``None`` (a known entry with no structure — structural columns serve
   null).



Classes
-------

.. autoapisummary::

   httk.atomistic.structure_entries.StructureEntryProvider


Module Contents
---------------

.. py:class:: StructureEntryProvider(entries: collections.abc.Mapping[str, httk.atomistic.structure_like.StructureLike | None], *, extra_definitions: collections.abc.Mapping[str, httk.core.PropertyDefinition] | None = None, properties: collections.abc.Mapping[str, collections.abc.Mapping[str, Any]] | None = None)

   Bases: :py:obj:`httk.core.EntryProvider`


   Serves OPTIMADE ``structures`` from a mapping of id to structure.

   ``entries`` maps each entry id to a :class:`~httk.atomistic.Structure` (or
   any structure exposing the ``cell``/``sites``/``species``/
   ``species_at_sites`` quartet, or a ``(cell, sites, species,
   species_at_sites)`` tuple), or to ``None`` for a known entry that has no
   structure (its structural columns then serve null).

   The always-served structural fields are ``id``, ``type``, ``nsites``,
   ``elements``, ``nelements``, ``species`` (as OPTIMADE species dicts),
   ``species_at_sites``, ``lattice_vectors`` (the cell basis rows),
   ``cartesian_site_positions`` (reduced coordinates times the cell basis), and
   ``structure_features`` (``disorder`` when any species mixes several chemical
   symbols; ``site_attachments`` when any species has attached atoms). The
   standard composition fields ``nperiodic_dimensions``, ``dimension_types``,
   ``elements_ratios``, ``chemical_formula_reduced`` / ``_anonymous`` /
   ``_descriptive`` are auto-derived for a fully ordered structure (every
   species a single, unattached element), else served as null.

   ``extra_definitions`` extends the served entry-type definition with custom
   database-specific properties (each carrying a registered prefix), and
   ``properties`` supplies their per-entry values as ``{entry_id: {name:
   value}}``; every property named there MUST be described by the (extended)
   definition (a :class:`ValueError` at construction names any offender), and a
   value absent for an entry is served as null.


   .. py:method:: entry_types() -> collections.abc.Mapping[str, httk.core.EntryTypeDefinition]


   .. py:method:: columns(entry_type: str) -> collections.abc.Mapping[str, str]


   .. py:method:: records(entry_type: str) -> collections.abc.Iterable[collections.abc.Mapping[str, Any]]