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.

structure_delta(first, second, *[, tolerance])

Return the total Cartesian atom travel between two compatible structures.

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, ...][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”.

This honors the explicit target exactly and never flips an enantiomorphic group; normalizing an enantiomorphic pair to its lower-numbered member is the closed-target canonicalizers’ (canonicalize(), canonical_asu()) job.

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, …]

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.

This honors the explicit target exactly and never flips an enantiomorphic group; normalizing an enantiomorphic pair to its lower-numbered member is the closed-target canonicalizers’ (canonicalize(), canonical_asu()) job.

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.structure_delta(first, second, *, tolerance=None)[source]

Return the total Cartesian atom travel between two compatible structures.

Each exact asymmetric-unit or fundamental-domain input is first canonicalized in its declared space group, without symmetry recognition. The canonical structures are then expressed in every compatible common Bärnighausen subgroup, in the same descending-symmetry order used by common_subgroup_representation(), and the second is aligned through the bounded affine-normalizer search used by represent_like(). Compatible full Species and Wyckoff-letter classes are paired one-to-one, choosing the minimum total physical travel within each class. Every member of each paired Wyckoff orbit contributes its shortest Cartesian distance to the total; the first and second positions are converted with their respective endpoint cells, so a lattice deformation contributes even when fractional coordinates do not change.

Periodic endpoint images are selected by a finite closest-vector search in the arithmetic mean endpoint metric. This remains correct for skew cells and is symmetric when the endpoints are interchanged. The return value is a finite non-negative float in the units of the cells’ bases (ångström for ordinary crystallographic structures).

Both directed bounded normalizer alignments are considered for each common subgroup, and their least travel is used. This makes the metric symmetric without pretending to enumerate every possible Bärnighausen embedding. The subgroup and normalizer searches are deliberately bounded: only the deterministic subgroup embedding exposed by rerepresent() and its tabulated normalizer images are considered. The recognized space group of either input, when it is a common subgroup, is the most faithful shared representation and is evaluated first; the travel of the first such group that yields a finite delta is returned (so two same-group structures are aligned in their own group, not a same-order sibling). Only when neither input’s own group is common does the search descend the remaining common subgroups in descending-symmetry order, evaluating at most _STRUCTURE_DELTA_SUBGROUP_LIMIT of them and returning at an exact coincidence or the least travel seen within that bound. Each subgroup considers both directed bounded normalizer alignments and every tabulated normalizer image, scoring each by its exact per-orbit Cartesian travel and keeping the minimum, which makes the metric symmetric. Atom and orbit assignment uses a deterministic Hungarian minimum-cost matching, so repeated Wyckoff classes do not require a factorial permutation search. Charges do not enter this geometrical metric.

Parameters:
Returns:

Total atom travel in the endpoint cells’ length units.

Raises:

ValueError – If the structures are unsupported, cannot be represented in a common subgroup, have incompatible species/Wyckoff classes, or yield a non-finite travel.

Return type:

float

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