Prototype families¶

The prototype APIs describe crystal geometry at three different resolutions. AnonymousStructure keeps a unit cell, sites, and dummy species labels; Prototype keeps a standard-setting space group and one Wyckoff site per orbit, with dummy species labels; Protostructure keeps only a standard-setting space group and occupied Wyckoff positions with real Species objects. Views (AnonymousStructureView, PrototypeView, and ProtostructureView) present existing values or recognize them from compatible sources. The first two representations form the dummy-species/geometry family; Protostructure is the real-species/geometry-free family. PrototypeLike is the umbrella union over both families.

Dummy species¶

Anonymous structures and prototypes use a deliberately narrow dummy-species shape. The label is carried through the labels decoration and the species name; it is never encoded as a chemical symbol:

from httk.atomistic import Species
from httk.atomistic.models.prototype import dummy_species, is_dummy_species

species = dummy_species("A")
assert species == Species("A", ("X",), (1,), labels=("A",))
assert is_dummy_species(species)

is_dummy_species requires exactly one "X" chemical symbol, unit concentration, matching name/label, and no mass, attachments, charge, spin, original name, or concentration decoration. Consequently a species named A with labels=("other",) is not a dummy species.

What crosses the boundary¶

The conversion boundary is intentionally explicit. The following table lists features rejected during conversion and features deliberately erased when a conversion is otherwise valid.

Conversion boundary	Rejected	Deliberately erased
Structure → `AnonymousStructure`/`Prototype`	disorder or partial occupancy; duplicate-element species; assemblies; `chemical_composition`; site moments	species identities become dummy labels; charge, formula metadata, `optimization_type`, `immutable_id`, `last_modified`, molecular metadata, and representatives
Structure → `Protostructure`	assemblies; `chemical_composition`; site moments; a species containing `"X"` (including attached `"X"`)	charge, formula metadata, `optimization_type`, `immutable_id`, `last_modified`, molecular metadata, and representatives

Protostructure is different here: its Species objects retain disorder and partial occupancy, including their real chemical symbols, concentrations, and decorations. Those are not rejected merely because they are non-singleton.

The useful conversion matrix is:

Construction	Result	Boundary
`AnonymousStructureView(AnonymousStructure)`	lazy anonymous view	exact/pass-through
`AnonymousStructureView(structure)`	lazy anonymous projection	validates the rejection rules above
`PrototypeView(Prototype)`	prototype view	exact/pass-through
`PrototypeView(ASUStructureView(s, setting=...))`	standard-setting prototype	exact ASU path after the requested setting is chosen
`PrototypeView(unitcell or ordinary structure)`	recognized prototype	tolerant recognition; requires the symmetry-recognition path (spglib)
`ProtostructureView(Protostructure)`	protostructure view	exact/pass-through
`ProtostructureView(ASUStructureView(s, setting=...))`	geometry-free real-species key	exact ASU path
`ProtostructureView(unitcell or ordinary structure)`	recognized protostructure	tolerant recognition; requires the symmetry-recognition path
`UnitcellStructureView(AnonymousStructure or Protostructure)`	—	raises: neither family is a unit-cell structure input
`ProtostructureView(AnonymousStructure)`	—	raises: dummy species are not real species
`PrototypeView(Protostructure)`	—	raises: the families have different species semantics

Recognition from a plain structure is the tolerant/spglib boundary. Existing ASU and prototype/protostructure values use exact data, with no recognition tolerance. For a source that needs a particular setting, use the sanctioned idiom shown in the PrototypeView row: PrototypeView(ASUStructureView(s, setting=...)). Prototype itself is standard-setting-only; it does not accept setting=, standard=, or transform= as recognition arguments.

Formula conveniences¶

AnonymousStructure and Prototype expose anonymous_formula. Their views retain the same convenience. Protostructure and ProtostructureView expose both formula and anonymous_formula; the former uses the real species and the latter anonymizes their site amounts. Formula projections use Wyckoff multiplicities, and reduced rendering removes a common GCD:

from httk.atomistic import AnonymousStructure, AnonymousStructureView

anonymous = AnonymousStructure(
    [[5, 0, 0], [0, 5, 0], [0, 0, 5]],
    [[0, 0, 0], [1 / 2, 1 / 2, 1 / 2]],
    species_at_sites=("A", "B"),
)
view = AnonymousStructureView(anonymous)
assert view.anonymous_formula == "AB"
assert view.unwrap() is anonymous

Protostructure is the isopointal key: it has no cell or coordinates, is hashable, and is safe as a dictionary key. Equality and hashing use its standard-setting space group and its occupied Wyckoff positions together with the associated Species values, so equivalent construction order does not change the key.

Storage records¶

Both prototype families have durable, layout-independent storage records in httk.atomistic.storage.records.

ProtostructureRecord (atomistic_protostructure_v1) carries exactly the value identity of Protostructure: its standard-setting space group (as spacegroup_it_number plus the standard spacegroup_hall_entry, mirroring the structure records) and its occupations — a tuple of WyckoffOccupationRecord (atomistic_wyckoff_occupation_v1), each a Wyckoff letter and a real SpeciesRecord, in the protostructure’s canonical order (sorted by species name then Wyckoff letter). It has no cell or coordinates. Because the record carries the same value identity, two equal Protostructure values (==, including a permuted construction order) produce records with the same content id, and unequal values differ; this is the deduplication key for a COD-scale protostructure catalog (count by rows; filter by spacegroup_it_number).

ProtostructureRecord exposes a queryable label stored property with the deterministic compact format "<it_number>/<wyckoff>:<species_name>,...", listing the occupations in the record’s stored canonical order (for example "225/b:Cl,a:Na"). The label 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 sharing a name but differing in any other Species field (concentration, charges, spins, mass, precision, …) collide on the same label, so counting or grouping by label may under-count distinct protostructures; count by row (content id) instead. The record declares composite indexes on ("spacegroup_it_number",) and ("label",).

PrototypeRecord (atomistic_prototype_v1) is the geometric per-structure object: a surd-capable CellRecord, WyckoffSiteRecord sites with their exact free parameters, distinct dummy SpeciesRecord species, the standard-setting space group, and the reduced-coordinate precision. Distinct free parameters make distinct values, so no content deduplication is expected; the content id is still deterministic. It indexes ("spacegroup_it_number",) and ("spacegroup_hall_entry",).

Conversion follows the established record idiom: each record declares __httk_canonical_source__ and __httk_project__ (so content_id and a store project a source value directly), and the module provides _protostructure_record_from_value/_protostructure_from_record and _prototype_record_from_value/_prototype_from_record for building records and recovering values. The records register under the logical protostructures and prototypes entry families (ProtostructureEntry/PrototypeEntry). A Prototype value stores directly through its record; a Protostructure value is stored through its ProtostructureRecord (the derived label column is computed from the record).

Deferred features¶

AFLOW/symgen labels and Pearson symbols, Wyckoff-sequence strings, OPTIMADE serving (definitions and providers) for the prototype families, and same_prototype() are deferred. They are not part of the conversion contracts described here.