httk.atomistic.models.protopattern.notation

The one home of httk’s protopattern and protostructure label notation.

An httk label encodes 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 grammar is:

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

A GROUP is the concatenation of one species 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 built from anonymous_symbol() in group order with per-group summed conventional multiplicities reduced by their overall gcd.

httk labels are deliberately NOT AFLOW labels. AFLOW orders classes by element symbol (alphabetically) so its unsuffixed prefix still depends on the chemistry; httk orders classes by their Wyckoff letters, so the unsuffixed prefix is element-agnostic and a protostructure label is exactly the protopattern label of the erased pattern followed by : and the class species names. render_aflow_label() renders the AFLOW-style variant for interoperability; it has no parser here.

“Canonicality” terminology: any faithful render of an object is the protopattern or protostructure label; the canonical protopattern or protostructure label is the one obtained from a normalizer-canonical object (for example one derived via canonical_asu). The renderer performs no affine-normalizer pass.

ponytail: the label is canonical only up to the fixed Wyckoff-letter naming of the IT standard setting; two normalizer-equivalent occupation sets can still render to distinct labels. The upgrade path is to vendor the per-Hall affine-normalizer coset data in httk.atomistic.data, induce the Wyckoff-letter permutations it generates, and emit the lexicographic-min label over that orbit. Not needed until labels must match across normalizer-equivalent settings.

Functions

pearson_symbol(spacegroup, nsites_conventional)

Return the Pearson symbol for a setting and its conventional-cell site count.

canonical_label_map(class_letters)

Map input class keys to consecutive anonymous class labels in group order.

render_protopattern_label(spacegroup, occupations)

Render the protopattern label of a space group and its class-partitioned Wyckoff letters.

render_protostructure_label(spacegroup, occupations)

Render the httk protostructure label of a space group and its named occupations.

render_aflow_label(spacegroup, occupations)

Render the AFLOW-style label of a space group and its named occupations.

parse_protopattern_label(text)

Parse a strictly canonical protopattern label into a protopattern.

parse_protostructure_label(text)

Parse a strictly canonical httk protostructure label into a protostructure.

try_parse_protopattern(text)

Return the parsed protopattern, or None when text is not a canonical one.

try_parse_protostructure(text)

Return the parsed protostructure, or None when text is not a canonical one.

Module Contents

httk.atomistic.models.protopattern.notation.pearson_symbol(spacegroup, nsites_conventional)[source]

Return the Pearson symbol for a setting and its conventional-cell site count.

The crystal-system letter follows the space group’s crystal_system; the centring letter follows its centring_type with the base-centred variants A, B, C, and S folded to C; the count is nsites_conventional, except a rhombohedral R setting (tabulated on hexagonal axes) divides it by three. Calcite (167 with 30 conventional sites) yields hR10.

Parameters:
Returns:

The Pearson symbol, such as "cF8".

Raises:

ValueError – If a rhombohedral count is not divisible by three.

Return type:

str

httk.atomistic.models.protopattern.notation.canonical_label_map(class_letters)[source]

Map input class keys to consecutive anonymous class labels in group order.

Classes are ordered lexicographically by their sorted Wyckoff-letter sequence (including repetitions); the input key breaks ties deterministically. Two classes with identical letter sequences are interchangeable, so either tie order renders the identical label.

Parameters:

class_letters (collections.abc.Mapping[str, tuple[str, Ellipsis]]) – For each input class key its sorted Wyckoff letters.

Returns:

A mapping from each input class key to its canonical anonymous label.

Return type:

dict[str, str]

httk.atomistic.models.protopattern.notation.render_protopattern_label(spacegroup, occupations)[source]

Render the protopattern label of a space group and its class-partitioned Wyckoff letters.

Parameters:
Returns:

The protopattern label text.

Raises:

ValueError – If any Wyckoff letter is absent from the setting.

Return type:

str

httk.atomistic.models.protopattern.notation.render_protostructure_label(spacegroup, occupations)[source]

Render the httk protostructure label of a space group and its named occupations.

Classes are ordered by their sorted Wyckoff letters, ties broken by species name. The unsuffixed prefix equals the protopattern label of the erased pattern; the suffix lists the class species names in group order.

Parameters:
Returns:

The protostructure label text.

Raises:

ValueError – If any Wyckoff letter is absent from the setting.

Return type:

str

httk.atomistic.models.protopattern.notation.render_aflow_label(spacegroup, occupations)[source]

Render the AFLOW-style label of a space group and its named occupations.

Unlike the httk label, classes are ordered by species name alphabetically and the anonymous symbols are reassigned in that order, so the unsuffixed prefix depends on the chemistry. Provided for interoperability only; there is no parser for this form.

Parameters:
Returns:

The AFLOW-style label text.

Raises:

ValueError – If any Wyckoff letter is absent from the setting.

Return type:

str

httk.atomistic.models.protopattern.notation.parse_protopattern_label(text)[source]

Parse a strictly canonical protopattern label into a protopattern.

Every Wyckoff letter must exist in the resolved standard setting, and the Pearson symbol, reduced anonymous counts, and group ordering must all match their recomputed canonical values; any deviation is rejected. This canonical-string-only stance mirrors parse_anonymous_formula().

Parameters:

text (str) – The protopattern label to parse.

Returns:

The parsed Protopattern.

Raises:

ValueError – If text is not a canonical protopattern label.

Return type:

httk.atomistic.models.protopattern.protopattern.Protopattern

httk.atomistic.models.protopattern.notation.parse_protostructure_label(text)[source]

Parse a strictly canonical httk protostructure label into a protostructure.

The unsuffixed part is validated as for a protopattern label; each : name must be a known element symbol and becomes Species(name, (name,), (1,)). Non-canonical labels are rejected.

Parameters:

text (str) – The protostructure label to parse.

Returns:

The parsed Protostructure.

Raises:

ValueError – If text is not a canonical protostructure label.

Return type:

httk.atomistic.models.protostructure.protostructure.Protostructure

httk.atomistic.models.protopattern.notation.try_parse_protopattern(text)[source]

Return the parsed protopattern, or None when text is not a canonical one.

Parameters:

text (str) – The label text to test.

Returns:

The parsed protopattern, or None for a non-label string.

Return type:

Protopattern | None

httk.atomistic.models.protopattern.notation.try_parse_protostructure(text)[source]

Return the parsed protostructure, or None when text is not a canonical one.

Parameters:

text (str) – The label text to test.

Returns:

The parsed protostructure, or None for a non-label string.

Return type:

Protostructure | None