httk.atomistic.symmetry.comparison_grid

Conservative sparse grids for approximate structure comparison candidates.

Classes

StructureComparisonGrid

Index necessary atom-neighborhood conditions for one same-group comparison batch.

Module Contents

class httk.atomistic.symmetry.comparison_grid.StructureComparisonGrid(values, delta, *, dimensions=2, strategy='occupancy', cache=None, max_points=100000, max_images=512)

Index necessary atom-neighborhood conditions for one same-group comparison batch.

A false result from might_match() excludes a pair; a true result still needs the ordinary similarity comparison. One to three Cartesian projections of expanded Wyckoff coordinates are gridded. Every candidate orbit member and normalizer image is indexed, allowing repeated sites and symmetry-equivalent descriptions. Queries include the reference cell’s periodic images and both alignment directions.

For atom travel c, the current endpoint metric implies norm(r1 - r2 + n B1) <= sqrt(2) c for some integer image n. Total travel within delta therefore requires every matched atom to satisfy this neighborhood condition. Selected projections only weaken that condition. Sparse buckets retain occupied cells only; caps and unsupported preparations fall back to ordinary comparison.

Parameters:

• values (collections.abc.Sequence[httk.atomistic.models.structure.asu.ASUStructure | httk.atomistic.models.structure.asu.FundamentalDomainStructure | httk.atomistic.models.prototype.api.PrototypeAPI | httk.atomistic.models.protostructure.api.ProtostructureAPI]) – Exact structures or geometry-carrying prototypes/protostructures.

• delta (float) – Finite non-negative Cartesian travel threshold.

• dimensions (int) – Number of Cartesian projections to index, from one to three.

• strategy (str) – Axis selection: first, variance, or occupancy.

• cache (httk.atomistic.symmetry.comparison_cache.StructureComparisonCache | None) – Optional shared canonicalization and prototype-conversion cache.

• max_points (int) – Maximum expanded points retained during index preparation.

• max_images (int) – Maximum periodic images examined for any reference anchor.

Raises:

• ValueError – If a threshold, strategy, dimension, or capacity is invalid.

• TypeError – If a value is not a supported structure or prototype.

• ImportError – If NumPy is unavailable.

property fallback_reason: str | None

Return why this index permits every pair, or None when indexing succeeded.

property indexed_points: int

Return the number of candidate orbit points processed by the index.

property selected_axes: tuple[int, ...]

Return the selected Cartesian coordinate indices in grid-key order.

might_match(first, second)

Return whether a pair still requires the ordinary similarity comparison.

Parameters:

• first (int) – Index of the first input value.

• second (int) – Index of the second input value.

Returns:

False only when both directed neighborhood tests exclude the pair.

Raises:

IndexError – If an index is outside the supplied sequence.

Return type:

bool