AICCM2026DEV-B finite-torus space-group symmetry¶

Status: experimental, diagnostic only. The default is off and is unchanged.

Scope¶

The aiccm2026dev-b cyclic cluster has a finite translation group. Crystal space-group operations can reduce quantities on that group only if they also preserve the chosen cyclic-cluster shape. This implementation obtains the three-dimensional space group, Wyckoff letters, site-symmetry symbols, and fractional operations from spglib. It then constructs the exact compatible subgroup, atom and cell mappings, and reciprocal-net orbits.

No integral is skipped in this increment. symmetry_mode="diagnostic" runs the unchanged full-net SCF and attaches a symmetry witness to the result. symmetry_mode="integrals" raises NotImplementedError. The latter guard is intentional: AO sewing matrices at general k and shell-quartet petite-list scattering are not yet validated against the full build.

Finite-cluster compatibility¶

Let the primitive translation lattice be

[ \Lambda = {A\mathbf r : \mathbf r\in\mathbb Z^3}, \tag{1} ]

where the columns of (A), measured in meters, are the primitive lattice vectors. A diagonal Born-von Karman cluster with (N=\operatorname{diag}(N_1,N_2,N_3)) identifies translations modulo

[ \Lambda_N = {AN\mathbf z : \mathbf z\in\mathbb Z^3}. \tag{2} ]

A space-group operation is written (g={W\mid\mathbf w}), where (W) is integer-valued in fractional coordinates and (\mathbf w) is fractional. It descends to an automorphism of (\Lambda/\Lambda_N) exactly when

[ W\Lambda_N=\Lambda_N. \tag{3} ]

For an invertible crystallographic (W), Equation (3) is equivalent to

[ N^{-1}WN\in\mathbb Z^{3\times3}. \tag{4} ]

Indeed, (WN\mathbf z=N\mathbf z’) must hold for every integer (\mathbf z), so (\mathbf z’=N^{-1}WN\mathbf z) is integer for every integer input. Conversely, integrality of this matrix maps every generator of (N\mathbb Z^3) back into that sublattice. Since (W^{-1}) is another space-group operation and satisfies the same condition in the compatible set, the inclusion is an equality. The implementation checks Equation (4) with integer divisibility, not floating-point rounding.

An anisotropic cluster may therefore retain only a subgroup of the crystal space group. This is mathematically valid and is reported explicitly. Setting symmetry_require_full_group=True instead refuses such a shape.

Atom and cell mapping, including screw and glide translations¶

For fractional atom coordinate (\mathbf f_a), element-preserving atom matching determines a unique atom (p_g(a)) and integer vector (\mathbf q_{g,a}) from

[ W\mathbf f_a+\mathbf w =\mathbf f_{p_g(a)}+\mathbf q_{g,a}. \tag{5} ]

The residual is evaluated in Cartesian distance,

[ \epsilon_{g,a} =\left|A\left(W\mathbf f_a+\mathbf w -\mathbf f_{p_g(a)}-\mathbf q_{g,a}\right)\right|_2, \tag{6} ]

and must not exceed the requested spglib tolerance. The public vibe-qc API expresses that tolerance in bohr; the corresponding SI distance is (a_0\epsilon_{g,a}), with (a_0) the Bohr radius in meters.

An atom in cyclic cell (\mathbf r) maps as

[ (a,\mathbf r)\mapsto \left(p_g(a),;W\mathbf r+\mathbf q_{g,a}\pmod{\mathbf N}\right). \tag{7} ]

Keeping (\mathbf q_{g,a}) is essential for screw and glide operations. Discarding it gives correct-looking atom permutations but wrong image-cell labels.

Reciprocal-net orbits¶

The reciprocal characters of the cyclic translation group are

[ \mathbf k_{\mathbf m} =\left(m_1/N_1,m_2/N_2,m_3/N_3\right), \quad 0\le m_i<N_i. \tag{8} ]

The reciprocal action follows from phase preservation, (\mathbf k’\mathbin{\cdot}W\mathbf r =\mathbf k\mathbin{\cdot}\mathbf r), and is therefore

[ \mathbf k’=W^{-T}\mathbf k\pmod{\mathbb Z^3}. \tag{9} ]

Equation (4) guarantees closure of Equation (9) on the finite net. For a closed-shell nonmagnetic reference, time reversal additionally identifies (\mathbf k) and (-\mathbf k). If orbit (\mathcal O_\alpha) has size (|\mathcal O_\alpha|), its exact integration weight is

[ \omega_\alpha =\frac{|\mathcal O_\alpha|}{N_1N_2N_3}, \qquad \sum_\alpha\omega_\alpha=1. \tag{10} ]

The diagnostic records these orbits but SCF continues to use all (N_1N_2N_3) points. Thus enabling diagnostics cannot change the energy.

Safe Gamma projection¶

At Gamma all cell-translation Bloch phases are one. The existing vibe-qc real-solid-harmonic Wigner matrices and atom permutation then define a real orthogonal AO action (U_g). An AO matrix can be projected by the Reynolds operator

[ \mathcal P_G[M]=\frac{1}{|G_N|}\sum_{g\in G_N}U_gMU_g^T. \tag{11} ]

Group closure proves idempotency:

[ \mathcal P_G[\mathcal P_G[M]] =\frac{1}{|G_N|^2}\sum_{g,h}U_{gh}MU_{gh}^T =\mathcal P_G[M], \tag{12} ]

because every product occurs exactly (|G_N|) times. The implementation exposes Equation (11) as a diagnostic utility and reports (\max_g|U_gMU_g^T-M|_F) for Gamma Fock and density matrices. It does not insert the projection into DIIS or SCF.

At general k, the nonsymmorphic translation and the atom-dependent image-cell shift in Equation (5) generate Bloch sewing phases. Their sign depends on the Bloch-sum convention used by each existing backend. Omitting them breaks the space-group representation. General-k AO symmetrization is therefore blocked until the sewing matrix is derived in the exact backend convention and passes full-net Fock and energy parity tests.

Shell-pair and quartet orbit diagnostics¶

For each operation, primitive shells map by atom permutation while retaining their within-atom shell slot and angular momentum. The diagnostic partitions intrinsic-unique shell pairs

[ (a,b)\equiv(b,a) ]

and intrinsic eightfold shell quartets

[ ((a,b),(c,d)) \equiv ((b,a),(c,d)) \equiv ((c,d),(a,b)) ]

into point-group orbits. Every pair or quartet must occur in exactly one orbit. The SCF output reports representative/full counts. Explicit quartet enumeration is skipped above 24 primitive shells to avoid a diagnostic fourth-power memory cost.

These are mapping tables, not an accelerated integral build. A representative quartet cannot be scattered at general k using only its shell orbit: the AO Wigner blocks, nonsymmorphic sewing phases, density transform, and orbit stabilizer must all enter the contraction. integrals therefore continues to fail closed.

Usage¶

result = vibeqc.run_aiccm2026dev_b_rhf(
    system,
    basis,
    mesh=(2, 2, 2),
    backend="ri",
    symmetry_mode="diagnostic",
)

symmetry = result.aiccm2026dev_b_symmetry
print(symmetry.plan.international_symbol)
print(symmetry.plan.n_operations_compatible)
print(symmetry.plan.n_kpoints_irreducible)

The periodic runner exposes the same route as aiccm_symmetry="diagnostic" with jk_method="aiccm2026dev-b".

Decisions and open questions¶

The feature is off by default. The off path does not invoke spglib or add result attributes.
A compatible subgroup is accepted because it is an exact symmetry of the finite torus. Users can require the full group explicitly.
Three-dimensional spglib is not applied to wires or slabs. A vacuum-padded 3D classification is not a rod or layer group, so 1D and 2D diagnostics fail closed pending the correct group treatment.
Fractional translations and atom-dependent lattice shifts are retained in every mapping table. Nonsymmorphic operations are not filtered out.
Gamma AO projection is available for validation only. It does not alter the SCF fixed point or energy.
General-k AO sewing, symmetry-unique shell pairs, shell quartets, and libint representative scattering remain open. The integrals option is a hard error until an enabled-versus-disabled parity test passes for Fock and total energy.
Degeneracy classification by little-group irreducible representations is not yet implemented. The present k-orbit reduction alone does not label bands by irreducible representation.