Material-information levels¶

httk-atomistic describes a crystalline material at several levels of information, organised as a matrix. The rows differ in how much geometrical information is kept; the columns differ in whether the site identities are anonymous placeholders or real chemical species. Each cell is a value family (a backend value plus its views) in httk.atomistic.

Level of geometrical information	Anonymous occupation	Assigned species
None (composition only)	`Formulatype`	`ChemicalFormula`
Wyckoff positions, optionally with a representative/discriminator	`Prototype`	`Protostructure`
Exact geometry	`Structuretype`	Structure

The top row keeps only the composition. The middle row keeps a standard-setting space group and its occupied Wyckoff positions. The bottom row fixes the exact continuous degrees of freedom (cell parameters and free coordinates). Reading down a column loses geometrical information; reading right across a row assigns real species to anonymous placeholders.

Prototype and Protostructure are the two middle-row geometrical-classification keys. A base value contains only its standard-setting space group and occupied Wyckoff positions. Either may additionally carry an exact fundamental-domain representative (a standard-setting value holding one exact realization), an externally assigned discriminator string (AFLOW -001-style), or both. These optional fields participate in equality and content identity, so a representative-only value never equals a discriminator-only value, and a base-only value is distinct from either refined form. Recognizing a key from a structure, and deriving one key from another, always return a base value; the representative and discriminator are supplied only by explicit construction.

The representative’s continuous degrees of freedom are a class anchor, not exact-structure data: its coordinates and cell are retained exactly so the anchor can be reconstructed, while the structural key stays a coarse classification. A prototype or protostructure therefore corresponds to many exact structures — every realization that shares the class — whereas a Structuretype or a Structure fixes the continuous degrees of freedom and so names a single exact geometry. Prototype uses a FundamentalDomainTemplate representative and anonymous PrototypeOccupation values; Protostructure uses a FundamentalDomainStructure representative and real-species WyckoffOccupation values.

How the levels relate¶

The levels combine by adding one piece of information at a time. These are information-content relationships, not class inheritance:

Prototype + species assignment → Protostructure
Prototype + exact geometrical parameters → Structuretype
Protostructure + exact geometrical parameters → Structure
Structuretype + species assignment → Structure
Prototype or Protostructure projected onto composition only → Formulatype or ChemicalFormula

A representative and/or a discriminator refine a base Prototype or Protostructure — pinning a specific geometrical class — without changing which row it occupies; both refined and base forms are middle-row keys.

Naming and capitalization¶

The canonical taxonomy terms are single-capital compound words: Formulatype, Prototype, Protostructure, and Structuretype. The suffix -type marks the anonymous-occupation column (Formulatype, Structuretype, and Prototype are the anonymous counterparts of ChemicalFormula, Structure, and Protostructure); the prefix Proto marks the cutoff-free Wyckoff classification.

The word “Template” no longer names the exact anonymous family — that family is Structuretype. “Template” survives only for the exact fundamental-domain anonymous values used as class anchors and ASU keys: FundamentalDomainTemplate and ASUTemplate (and their view family, e.g. FundamentalDomainTemplateView). The name Prototype is the already-established term for what a fully systematic naming scheme would call a “templatetype”; there is no code alias for the latter (see Naming of httk₂ structural classes).

The older names survive as aliases for discoverability only; documentation and new code use the canonical names.

Alias	Canonical
`AnonymousStructure`, `AnonymousStructureView`, `AnonymousStructureLike`	`Structuretype` family
`AnonymousFormula`, `AnonymousFormulaView`	`Formulatype` family

Dummy species¶

The anonymous exact values (Structuretype, FundamentalDomainTemplate, and the representative held by a Prototype) 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.structuretype.anonymize 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. A Prototype carries the anonymous class labels (A, B, C, …) directly and has no dummy Species objects at all.

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 → `Structuretype`/`FundamentalDomainTemplate`	disorder or partial occupancy; duplicate- or multi-element species; a species whose symbol is `"X"` or `"vacancy"`; assemblies; `chemical_composition`; site moments	species identities become dummy labels; charge, spin, mass, formula metadata, `optimization_type`, `immutable_id`, `last_modified`, and molecular metadata
Structure → `Protostructure`	assemblies; molecular structures; `chemical_composition`; site moments; a species containing `"X"` (including attached `"X"`)	charge/formula metadata, `optimization_type`, `immutable_id`, `last_modified`, and molecular metadata

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 below. Views either present an existing value (exact, pass-through), extract a coarser level from a finer one (exact), or recognize a level from a plain structure (tolerant, needs the symmetry-recognition path, spglib).

Construction	Result	Boundary
`PrototypeView(Prototype)`	prototype view	exact/pass-through
`PrototypeView(Protostructure)`	anonymous prototype (species erased; any explicit representative/discriminator carried over)	exact erasure of species
`PrototypeView(FundamentalDomainTemplate)`	folded base prototype	exact extraction/discretization
`PrototypeView(Structuretype)`	prototype recognized from the exact anonymous geometry	tolerant recognition (spglib)
`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 (spglib)
`StructuretypeView(Structuretype)`	structuretype view	exact/pass-through
`StructuretypeView(FundamentalDomainTemplate)`	expanded unit cell	exact
`StructuretypeView(structure)`	anonymized projection	exact; validates the rejection rules above
`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 (spglib)
`ProtostructureView(Structuretype or FundamentalDomainTemplate)`	—	raises: dummy species are not real species
`UnitcellStructureView(Structuretype or FundamentalDomainTemplate)`	—	raises: dummy species are not real species

Recognition from a plain structure is the tolerant/spglib boundary. Existing ASU, structuretype, prototype, and protostructure values use exact data, with no recognition tolerance. For a source that needs a particular setting, use the sanctioned idiom shown above: PrototypeView(ASUStructureView(s, setting=...)). Recognition of a raw structure resolves the standard setting.

Formula conveniences¶

The geometry-bearing anonymous cells (Structuretype and Prototype, through their views) expose anonymous_formula; the assigned cells expose both formula (real species) and anonymous_formula (site amounts anonymized). A Formulatype has no anonymous_formula attribute — it is the anonymous formula, rendered as its string value (str(FormulatypeView(...)), e.g. "A3B2"). Formula projections use Wyckoff multiplicities, and reduced rendering removes a common GCD:

from httk.atomistic import Structuretype, StructuretypeView

template = Structuretype(
    [[5, 0, 0], [0, 5, 0], [0, 0, 5]],
    [[0, 0, 0], [1 / 2, 1 / 2, 1 / 2]],
    species_at_sites=("A", "B"),
)
view = StructuretypeView(template)
assert view.anonymous_formula == "AB"
assert view.unwrap() is template

Protostructure is the isopointal-with-species key: it has no cell or coordinates. Equality uses its standard-setting space group and its occupied Wyckoff positions together with the associated Species values (plus any representative or discriminator), so equivalent construction order does not change it. Prototype is the anonymous counterpart of that key. Both families are hashable and safe as dictionary or set keys: hashing uses the base key (space group, occupied Wyckoff positions, species or anonymous occupation, and the discriminator), while equality additionally compares a representative when one is present. Equal objects therefore hash equal; two values that differ only in their representative may collide on the hash but remain unequal.

Labels¶

An httk label is a compact string encoding the information content of an unsuffixed AFLOW-style prototype label: a space group, its occupied Wyckoff letters, and the partition of those occupations into species classes. The single home of the notation is httk.atomistic.models.prototype.notation. The grammar is:

ANON_PEARSON_ITNUMBER_GROUP(_GROUP)*                 # prototype label
ANON_PEARSON_ITNUMBER_GROUP(_GROUP)*:NAME(-NAME)*    # protostructure label

A GROUP is the concatenation of one class’s Wyckoff letters, sorted alphabetically, a letter occupied k >= 2 times prefixed by the integer k (2e); count 1 is omitted. ANON is the anonymous formula (A, B, C, …) built in group order with per-group summed conventional multiplicities reduced by their overall GCD.

A structure’s canonicalization preserves chirality by default. The canonical Protostructure/Prototype label is instead built from the chirality-normalized result (canonical_asu(preserve_chirality=False), or normalize_chirality applied to a chirality-preserved result; see Asymmetric units), so the two members of an enantiomorphic pair share one canonical label.

httk labels are not AFLOW labels¶

The httk group-ordering convention orders the occupation groups lexicographically by their sorted Wyckoff-letter sequences. This ordering is element-agnostic, so a protostructure label is exactly its erased prototype label plus the : species suffix. AFLOW, by contrast, orders the classes by element symbol alphabetically, so its unsuffixed prefix depends on the chemistry. The two are therefore genuinely different strings, and an httk label is not an AFLOW label.

The assigned-species classes expose both, as distinct properties: label (the httk convention, a ProtostructureLabel) and aflow_label (the AFLOW-style rendering, a plain str). For calcite, Protostructure(167, a:Ca, b:C, e:O):

from httk.atomistic import Protostructure, Species

Ca, C, O = Species("Ca", ("Ca",), (1,)), Species("C", ("C",), (1,)), Species("O", ("O",), (1,))
calcite = Protostructure(167, [("a", Ca), ("b", C), ("e", O)])
assert calcite.label == "ABC3_hR10_167_a_b_e:Ca-C-O"
assert calcite.aflow_label == "ABC3_hR10_167_b_a_e:C-Ca-O"

The httk label orders the groups a, b, e by Wyckoff letter; the AFLOW label orders them b, a, e to follow the alphabetical elements C, Ca, O.

Pearson symbol¶

The Pearson symbol is system + centring + count. The system letter follows the space group’s crystal system (a, m, o, t, h, h, c for triclinic through cubic, trigonal and hexagonal both mapping to h). The centring letter follows the centring type, with the base-centred variants A, B, C, and S folded to C (the A case fires for groups 38–41). The count is the conventional-cell site count, except a rhombohedral R setting — tabulated on hexagonal axes — divides it by three (and asserts divisibility). Calcite’s 30 conventional sites give hR10.

The 27th Wyckoff letter used by a few high-multiplicity settings (group 47’s eightfold orbit, internally 'α') renders as A and parses back from it; positionally a group token never collides with the leading anonymous formula.

Strict parser¶

The parser is strict and canonical-only: it resolves the standard setting, validates every Wyckoff letter, recomputes the Pearson symbol, the reduced anonymous counts, and the group ordering, and rejects any string that deviates from the recomputed canonical form. Suffix names must be known element symbols and become Species(name, (name,), (1,)). Round trips are pinned in both directions: parse(render(x)) == x for element-pure values and render(parse(s)) == s for canonical strings. This mirrors parse_anonymous_formula for Formulatype.

Canonical vs plain labels¶

Any faithful render of an object is the prototype or protostructure label. The canonical prototype or protostructure label is the one obtained from a normalizer-canonical object — one derived via canonical_asu. The renderer performs no affine-normalizer pass this round, so labels from hand-built, non-canonical objects are faithful but not necessarily canonical. Whenever text speaks of the label of an arbitrary value it uses the plain form (“the protostructure label”), reserving “the canonical … label” for a normalizer-canonical source.

The AFLOW-style -001 discriminators belong to a Prototype or a Protostructure (their discriminator field), which name a species-independent geometrical class. They are never part of the label.

Similarity and exact travel¶

Prototype.similar and Protostructure.similar first compare their discrete space-group and occupation keys, then apply discriminator compatibility. If both values have representatives, the continuous comparison is the total Cartesian atom travel returned by the public structure_delta(first, second); missing representatives do not invent a distance. structure_delta maps the structures into a common subgroup and setting, pairs compatible Wyckoff orbits, and sums the shortest periodic Cartesian travel of their atoms. Each endpoint uses its own cell, so lattice changes contribute through the atom positions. It is not a content-id or label comparison. similar returns False only when no common representation exists (NoCommonRepresentation, a ValueError subclass in httk.atomistic.symmetry.paths); other errors from a broken representative — a singular cell basis, a non-three-dimensional cell, or non-finite travel — propagate.

Storage records¶

The families have durable, layout-independent storage records in httk.atomistic.storage.records:

Record	Storage name	Value
`PrototypeRecord`	`atomistic_prototype`	`Prototype`
`ProtostructureRecord`	`atomistic_protostructure`	`Protostructure`
`FundamentalDomainTemplateRecord`	`atomistic_fundamental_domain_template`	`FundamentalDomainTemplate`
`FundamentalDomainStructureRecord`	`atomistic_fundamental_domain_structure`	`FundamentalDomainStructure`

Each record carries the value identity of its family, so two equal values produce records with the same content id (the deduplication key) and unequal values differ. PrototypeRecord and ProtostructureRecord accept base-only values and store the optional representative as a nested record (FundamentalDomainTemplateRecord for a prototype, FundamentalDomainStructureRecord for a protostructure) and the optional discriminator as a plain column. Structuretype itself stays non-storable.

Both PrototypeRecord.label and ProtostructureRecord.label render the httk label (for example AB_cF8_225_a_b and AB_cF8_225_a_b:Na-Cl) as a queryable label column. The content ids are unchanged by this — the label is a convenience and query column, not the record’s identity, and it is not unique: the discriminator is not part of the label, so records that share occupations but differ in class collide on it, and two protostructures whose species share a name but differ in another Species field also collide. Count and deduplicate by row (content id), never by label.

The registry record names are atomistic-prototype (family prototypes) and atomistic-protostructure (family protostructures), with atomistic-fundamental-domain-structure in the structures family. FundamentalDomainTemplateRecord is an embedded component record (nested inside PrototypeRecord as the optional representative) and deliberately has no registry entry of its own.

Because the taxonomy and the storage layout were redesigned, pre-existing stores carry orphaned tables and, where the label format changed, stale label columns. Rebuilding the store from its source values is the documented remedy; no compatibility registry keys are provided. Concretely, the following tables are orphaned — their rows are not migrated, and (because the identity name participates in hashing) re-ingesting the source values produces new content ids under the current records:

the retired four-class layout’s atomistic_prototemplate and atomistic_structuretype tables (and any earlier atomistic_prototype_v1 tables);
the atomistic_protostructure_v1 and atomistic_wyckoff_occupation_v1 tables, orphaned by removing the _v1 storage-name suffixes (now atomistic_protostructure and atomistic_wyckoff_occupation);
the pre-“Pattern”→”Template” rename tables atomistic_protopattern and atomistic_fundamental_domain_pattern.

Separately, a store written across the label-format switch holds mixed formats in the ProtostructureRecord.label column — old "225/b:Cl,a:Na"-style rows alongside httk-label rows. Record identity (the content id) is unaffected there; a rebuild simply normalizes the column.

Deferred features¶

The following are deliberately not part of this round and not part of the conversion contracts above:

same_prototype().
OPTIMADE serving (definitions, providers, and bindings) for the prototype and protostructure families.
The species-assignment convenience constructors (Protostructure(prototype, species=...), Structure(structuretype, species=...)).
Normalizer-canonicalized label rendering (the affine-normalizer pass that would make every faithful label canonical).

The full guide, Naming of httk₂ structural classes, covers the naming rationale and how the classes relate to isopointal/isoconfigurational structures and AFLOW labels.