httk.atomistic.supercell

Exact supercell construction and deterministic cell-shape search.

Construction itself is rational/surd-exact. An integer matrix A maps the old row-vector basis B to A * B and multiplies the number of sites by abs(det(A)). The corresponding finite rational translation group supplies every periodic image exactly; no geometric tolerance or open-ended cell search is involved.

Automatic shape selection fixes that multiplier up front. A 50-digit Decimal approximation of the exact Gram matrix seeds a bounded set of nearby integer matrices, but candidates are ranked by exact, dimensionless Gram-matrix scores. The result is therefore the best member of the documented candidate set, not a claim of unrestricted global optimality.

Classes

SupercellResult

A materialized supercell together with its exact construction metadata.

Functions

build_supercell(→ SupercellResult)	Build the exact supercell selected by an integer transformation matrix.
orthogonal_supercell(→ SupercellResult)	Build the most orthogonal supercell in the bounded candidate set.
cubic_supercell(→ SupercellResult)	Build the most cubic supercell in the bounded candidate set.

Module Contents

class httk.atomistic.supercell.SupercellResult

A materialized supercell together with its exact construction metadata.

orthogonality_score is the sum of the squared pairwise cosines between cell vectors. cubicity_score is the squared Frobenius distance between the trace-normalized Gram matrix and the identity. Both are exact SurdScalar values; zero proves the ideal shape exactly.

structure: httk.atomistic.structure.Structure

transformation: httk.core.FracVector

multiplier: int

orthogonality_score: httk.core.SurdScalar

cubicity_score: httk.core.SurdScalar

httk.atomistic.supercell.build_supercell(structure: httk.atomistic.structure_like.StructureLike, transformation: httk.core.VectorLike, *, max_sites: int | None = DEFAULT_MAX_SITES) → SupercellResult

Build the exact supercell selected by an integer transformation matrix.

Lattice vectors are rows and the returned basis is transformation * basis. Reduced coordinates are transformed by the inverse matrix and wrapped into [0, 1). Any input representation is first presented as a full Structure.

Requires a fully 3D-periodic structure. Repeating a slab within its own plane is a perfectly sensible operation, but it is not this one: the transformation matrix here mixes all three rows and the coordinates are wrapped in all three directions, so applied to a reduced-periodicity cell it would generate images along a direction that has no lattice translation. Refused rather than half-supported.

httk.atomistic.supercell.orthogonal_supercell(structure: httk.atomistic.structure_like.StructureLike, multiplier: int | None = None, *, tolerance: fractions.Fraction | str | float | None = None, max_multiplier: int | None = None, search_radius: int = 1, max_sites: int | None = DEFAULT_MAX_SITES) → SupercellResult

Build the most orthogonal supercell in the bounded candidate set.

Exactly one of multiplier and tolerance must be provided. With multiplier, it is the exact number of source cells in the result. With tolerance, the multiplier is increased from one until the exact orthogonality score is at most the given bound, up to max_multiplier. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most search_radius (0–2); diagonal factorizations provide guaranteed determinant-matching fallbacks. Exact orthogonality is ranked first and cubicity breaks equal-shape ties.

httk.atomistic.supercell.cubic_supercell(structure: httk.atomistic.structure_like.StructureLike, multiplier: int | None = None, *, tolerance: fractions.Fraction | str | float | None = None, max_multiplier: int | None = None, search_radius: int = 1, max_sites: int | None = DEFAULT_MAX_SITES) → SupercellResult

Build the most cubic supercell in the bounded candidate set.

Exactly one of multiplier and tolerance must be provided. With multiplier, it is the exact number of source cells in the result. With tolerance, the multiplier is increased from one until the exact cubicity score is at most the given bound, up to max_multiplier. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most search_radius (0–2); diagonal factorizations provide guaranteed determinant-matching fallbacks.