P1 expansion with provenance

Problem

A CIF or a builder stores only the asymmetric unit. Every drawing, bond search and measurement needs the whole cell, and an edit to one drawn atom must map back to the site that generated it. The P1 expansion therefore carries provenance, not only coordinates.

Formulation

For site s and operation o with integer rotation R_o and fractional translation t_o:

base = R_o x_s + t_o
floor = floor(base)
frac = base - floor
tau = -floor

The stored atom satisfies frac = o.apply(x_s) + tau, where tau is an integer lattice shift. All arithmetic is in fractional coordinates; the lattice is applied only when a Cartesian position is needed.

Duplicate images arise on special positions. Each site has its own fractional grid: the expansion keeps the first image and drops a later one when the periodic distance is within the tolerance (default 0.05 Angstrom). The grid is reset per site, so two disordered sites that occupy the same point both survive. The resulting count is the Wyckoff multiplicity for a well-formed file.

Complexity

The expansion walks n_sites * n_ops images. Duplicate detection uses a fractional grid sized from the perpendicular cell widths, so each image checks only its neighbouring bins; the cost is linear in the number of images plus the local coincidences, not the previous quadratic scan.

Caveats

• An explicit operation loop is the source of truth. Without one, the CIF reader resolves the Hall/H-M symbol through the space-group catalogue; detect_symmetry/set_space_group can replace the operations from moyo when a caller wants the detected setting.
• A file that lists the whole cell under a non-P1 group produces duplicates; they are dropped by the periodicity filter. Duplicates across different sites are kept: they are separate disorder components, as in CFA1.
• The CIF reader resolves an H-M/Hall symbol into operations when the file has no operation loop; only an unknown symbol records symmetry_warning.
• tau is the shift that brings the image back into [0, 1); it is not the periodic image used by a neighbour search.

Validation

crates/xtalforge-core/tests/p1.rs covers triplet parsing, composition, inversion, provenance consistency, special positions and the identity case. The corpus comparison with Crystal-Builder is Task 1.6.4 and runs when the CIF reader lands.