httk.atomistic.symmetry.paths

Exact symmetry-preserving structure alignment and interpolation.

Classes

CommonSubgroupResult

Two aligned structures in their highest common subgroup.

StructurePath

A finite exact interpolation path between two aligned asymmetric units.

Functions

represent_like(structure, reference, *[, tolerance])

Represent a structure in a reference's group and setting.

list_representations(structure, target, *[, tolerance])

Return every distinct representation of one crystal in a target group's standard setting.

canonicalize_full(structure, target, *[, tolerance])

Return the canonically least representation of a crystal in a target group's standard setting.

common_subgroup_representation(first, second, *[, ...])

Represent two structures in their highest common subgroup.

interpolate_structures(start, end, *, steps[, tolerance])

Build an exact symmetry-preserving linear interpolation.

Module Contents

class httk.atomistic.symmetry.paths.CommonSubgroupResult[source]

Two aligned structures in their highest common subgroup.

Parameters:

  • first – The first input represented in the common subgroup’s standard setting.

  • second – The second input represented and aligned to first.

  • spacegroup – The selected highest common subgroup in standard setting.

first: httk.atomistic.models.structure.asu.ASUStructure[source]
second: httk.atomistic.models.structure.asu.ASUStructure[source]
spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup[source]
class httk.atomistic.symmetry.paths.StructurePath[source]

A finite exact interpolation path between two aligned asymmetric units.

Parameters:

  • frames – The endpoint-inclusive asymmetric-unit frames.

  • spacegroup – The shared space group and setting of all frames.

  • start – The first frame.

  • end – The last frame.

frames: tuple[httk.atomistic.models.structure.asu.ASUStructure, Ellipsis][source]
spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup[source]
start: httk.atomistic.models.structure.asu.ASUStructure[source]
end: httk.atomistic.models.structure.asu.ASUStructure[source]
httk.atomistic.symmetry.paths.represent_like(structure, reference, *, tolerance=None)[source]

Represent a structure in a reference’s group and setting.

The input is first sent through rerepresent(), then equivalent affine-normalizer coset images of that one descent realization are scored against the reference. This is deliberately bounded: tabulated variants of alternate multi-hop descent paths are not enumerated because rerepresent() exposes only its deterministic selected realization. Site pairing is brute force and capped at 40,320 permutations per class; larger classes require a future assignment solver.

Parameters:
Returns:

The input represented in the reference’s group and setting.

Raises:

ValueError – If the groups are unrelated, signatures differ, or the input is unsupported by the exact symmetry machinery.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.symmetry.paths.list_representations(structure, target, *, tolerance=None)[source]

Return every distinct representation of one crystal in a target group’s standard setting.

The crystal is first expressed once in target by rerepresent() – an exact descent for a subgroup target, a round-trip-gated lift for a supergroup target, itself for the same group – and the full discrete affine-normalizer orbit of that one realization is then enumerated. Every representation is returned in its continuous-translation normal form (otherwise a polar or triclinic target would have infinitely many), deduplicated by exact orbit-canonical site key and cell gram, and sorted by that key.

Scope. When target is the crystal’s own full symmetry group, two representations differ only by an element of that group’s affine normalizer, so this one orbit is the complete set – modulo the continuous normalizer and limited only by the bounded tabulated coset table. For a PROPER-SUBGROUP (or supergroup) target only the normalizer orbit of the single rerepresent() embedding is returned; inequivalent embeddings reachable by other descent chains – the same crystal at the same cell size but a genuinely different site placement – are deliberately out of scope and are NOT returned, because enumerating every chain is combinatorially explosive for deep targets (many tabulated chains), so a single canonical embedding is chosen. Representations needing an untabulated conventional-cell re-choice (the A.5 recell-class freedom) are likewise not generated. A supercell description is the same crystal in a larger cell; it too is not enumerated – the exclusion there is “not a distinct representation at the same cell size”, not “not the same crystal”.

Parameters:
Returns:

The distinct representations in target’s standard setting, sorted by canonical key.

Raises:

ValueError – If target is unrelated to the crystal’s group, or the input is unsupported by the exact symmetry machinery.

Return type:

tuple[httk.atomistic.models.structure.asu.ASUStructure, Ellipsis]

httk.atomistic.symmetry.paths.canonicalize_full(structure, target, *, tolerance=None)[source]

Return the canonically least representation of a crystal in a target group’s standard setting.

The least element, by exact orbit-canonical site key then cell gram, of list_representations(). On the crystal’s own group this is a normalizer-canonical form: it selects the same representative the upward search’s normal form does, over the same discrete normalizer crossing and modulo the continuous quotient. It is idempotent – re-running it on its own result in the same target returns that result.

Parameters:
Returns:

The canonically least representation in target’s standard setting.

Raises:

ValueError – If target is unrelated, or the input is unsupported.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.symmetry.paths.common_subgroup_representation(first, second, *, tolerance=None)[source]

Represent two structures in their highest common subgroup.

Common subgroups are ordered by descending symmetry-operation count and then descending International Tables number. The first group for which both exact descents succeed is selected; the second structure is then aligned to the first by represent_like().

Parameters:
Returns:

The two aligned structures and their selected common subgroup.

Raises:

ValueError – If no common subgroup can represent both structures.

Return type:

CommonSubgroupResult

httk.atomistic.symmetry.paths.interpolate_structures(start, end, *, steps, tolerance=None)[source]

Build an exact symmetry-preserving linear interpolation.

Free parameters follow the wrapped shortest rational displacement and cell bases are linearly interpolated in the shared setting. Every intermediate frame is expanded so a collision with an already occupied orbit is reported with its step index. Frames carry the start structure’s setting transform, while their Wyckoff parameters remain standard- setting values.

Parameters:
Returns:

The exact interpolation path.

Raises:

ValueError – If endpoints cannot be aligned, charges differ, or an intermediate frame is invalid.

Return type:

StructurePath