httk.atomistic.structure_entries

An EntryProvider serving OPTIMADE structures from httk-atomistic.

StructureEntryProvider maps 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 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 extended() definition, and may map an entry id to None (a known entry with no structure — structural properties serve null).

Classes

StructureEntryProvider

Serves OPTIMADE structures from a mapping of id to structure.

Module Contents

class httk.atomistic.structure_entries.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: httk.core.EntryProvider

Serves OPTIMADE structures from a mapping of id to structure.

entries maps each entry id to a 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 properties 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 ValueError at construction names any offender), and a value absent for an entry is served as null.

entry_types() → collections.abc.Mapping[str, httk.core.EntryTypeDefinition]

Return the served entry types keyed by name.

Each value is an EntryTypeDefinition describing the entry type and its properties. The subset a provider actually serves is named by property_keys(); a definition may describe more properties than are served.

property_keys(entry_type: str) → collections.abc.Mapping[str, str]

Return the served-property-name to record-key map for entry_type.

The mapping MUST include entries for at least id and type. Every key names a property described by entry_types(); every value names the key under which that property’s value is found in a record from records().

records(entry_type: str) → collections.abc.Iterable[collections.abc.Mapping[str, Any]]

Yield the records for entry_type as plain JSON-able mappings.

Each record is a mapping keyed by the record keys named in property_keys(); values are JSON-able (strings, numbers, booleans, None, or nested lists/dicts of the same).