Annotate phase-convention-adjusted code with [⚠️ phase] markers + move investigation notes to devdocs

Add [⚠️ phase] annotations at phase-convention-sensitive locations in
symmetry_analysis.jl (the only file that intentionally deviates from the
physical Convention 1 formulas to match Crystalline.jl's calc_bandreps).

Consolidate PHASE6_NOTES.md investigation log into
symmetry_eigenvalue_conventions.md (inlining the SG 88 worked example and
the note about Hamiltonian phase independence), then delete the separate
investigation file. Add entry to devdocs README.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: thchr

PHASE6_NOTES.md

@@ -16,3 +16,8 @@ user-facing theory exposition, see [`theory.md`](../theory.md).
 - **[`1d_example.md`](1d_example.md)** — Worked example of a 1D bipartite lattice with
   inversion, illustrating the M-matrix approach by comparing a hand-derived Hamiltonian with
   the symmetry-constrained result.
+
+- **[`symmetry_eigenvalue_conventions.md`](symmetry_eigenvalue_conventions.md)** — Phase
+  convention mismatch between the physical derivation (`theory.md`) and Crystalline.jl's
+  `calc_bandreps`, how `symmetry_eigenvalues` corrects for it, the centered-lattice
+  primitivization fix, and options for future cleanup.

docs/src/devdocs/README.md

@@ -195,14 +195,46 @@ In this option, `theory.md` should also gain a note (or a new devdoc section) ex
 Since `symmetry_eigenvalues` must match Crystalline.jl's irreps for subduction to work, we
 adopt the conjugated convention for $\mathbf{D}_\mathbf{k}$."
 
-## Test results with the fix
+## The centering fix: `primitivize` with `modw=false`
+
+Beyond the phase convention mismatch, a separate bug affected all centered lattices (C- and
+I-centered space groups: SG 68, 88, 141, 142, 214, 220, 230). The original
+`collect_compatible` primitivized little groups via `primitivize(group(first(lgirs)))`, which
+calls `primitivize(g::LittleGroup)` with the default `modw=true`, reducing translations
+modulo the primitive lattice. For centered lattices, the primitivization transforms
+conventional translations $\mathbf{v}_\text{conv}$ to primitive translations
+$P^{-1}\mathbf{v}_\text{conv}$, then reduces mod 1. The discarded lattice vector
+$\mathbf{R}$ changes the phase $e^{2\pi i(g\mathbf{k})\cdot\mathbf{v}}$ by a factor
+$e^{2\pi i(g\mathbf{k})\cdot\mathbf{R}} \neq 1$ at non-$\Gamma$ high-symmetry points.
+
+**Concrete example:** SG 88 ($I4_1/a$), operation $\{-4^+_{001}|\frac{1}{4},\frac{3}{4},\frac{3}{4}\}$ at the P-point $[\frac{1}{2},\frac{1}{2},\frac{1}{2}]$:
+- Conventional translation: $\mathbf{v} = [\frac{1}{4}, \frac{3}{4}, \frac{3}{4}]$
+- Primitivized (full): $P^{-1}\mathbf{v} = [\frac{3}{2}, 1, 1]$
+- Primitivized (reduced mod 1): $[\frac{1}{2}, 0, 0]$ — discards lattice vector $\mathbf{R} = [1, 1, 0]$
+- $g\mathbf{k} \cdot \mathbf{R} = -\frac{1}{4}$, giving phase error $e^{2\pi i \times 0.25} = i$
+
+The fix uses `primitivize(::Collection{LGIrrep})`, which internally passes `modw=false`,
+preserving full (unreduced) translations:
+
+```julia
+clgirsv = irreps(cbr)
+lgirsv = primitivize.(clgirsv)
+lgs = group.(lgirsv)
+```
+
+## Note: the Hamiltonian Fourier phase is independent
+
+The Hamiltonian evaluation phase ($e^{-2\pi i \mathbf{k}\cdot\boldsymbol{\delta}}$ in
+`evaluate_tight_binding_term!`) does **not** affect symmetry analysis results. This was
+verified during the investigation: the phase sign only transposes $H(\mathbf{k}) \to H(-\mathbf{k})$,
+and eigenvectors at the high-symmetry $\mathbf{k}$-points used by `symmetry_eigenvalues` are
+obtained from `solve(ptbm, k)` which always uses the actual $\mathbf{k}$. Changing the
+Hamiltonian phase sign is therefore not a route to fixing symmetry analysis.
+
+## Test results with all fixes
 
 Across all 230 3D space groups (and all 1D and 2D space groups):
 
 - **All 1D:** pass
 - **All 2D:** pass (including p3, p6, which previously failed at the K-point)
-- **3D:** 223/230 pass; 7 fail (SG 68, 88, 141, 142, 214, 220, 230)
-- The 7 remaining failures are **pre-existing** bugs (present in the original code before
-  the fix), all in centered lattices (C or I centering). These are a separate class of issue,
-  likely originating in Crystalline.jl's orbit/position handling for non-primitive lattices.
-  The fix actually *improves* some of these (SG 214: 10→8 failures; SG 220: 6→4; SG 230: 9→4).
+- **All 3D:** pass (including all centered lattices)

docs/src/devdocs/symmetry_eigenvalue_conventions.md

@@ -1,3 +1,7 @@
+# Note [⚠️ phase]: Several phase choices in this file intentionally deviate from the physical
+#   Convention 1 formulas derived in `docs/src/theory.md` to match Crystalline.jl's
+#   `calc_bandreps` convention. See `docs/src/devdocs/symmetry_eigenvalue_conventions.md`.
+
 """
     collect_compatible(ptbm::ParameterizedTightBindingModel{D}; multiplicities_kws...)
 
@@ -40,7 +44,7 @@ function Crystalline.collect_compatible(
     cbr = CompositeBandRep(tbm)
 
     clgirsv = irreps(cbr) # irreps associated to the EBRs (conventional setting operations)
-    lgirsv = primitivize.(clgirsv)
+    lgirsv = primitivize.(clgirsv) # [⚠️ phase]: must use `modw=false` (via Collection method)
     lgs = group.(lgirsv)  # little groups associated to the EBRs (primitive setting)
     ops = unique(Iterators.flatten(lgs))
 
@@ -110,14 +114,14 @@ function symmetry_eigenvalues(
         g = sgrep.op
         gk = compose(g, ReciprocalPoint{D}(k)) # NB: for k ∈ Gₖ, there exist G st g∘k = k+G
         G = gk - k # the possible reciprocal vector-difference G between k & g∘k; for Θᴳ
-        # NB: we use -G (i.e., `conj(Θᴳ)`) rather than G because the symmetry eigenvalue
-        #     formula `⟨ψ|ĝ|ψ⟩ = w† Θ_G† D_k w` uses the physical Convention 1 result with
-        #     Θ_G†; but `calc_bandreps` in Crystalline.jl (following Cano et al.) computes
+        # [⚠️ phase]: we use -G (i.e., `conj(Θᴳ)`) rather than G because the symmetry
+        #     eigenvalue formula `⟨ψ|ĝ|ψ⟩ = w† Θ_G† D_k w` uses the physical Conv 1 result
+        #     with Θ_G†; but `calc_bandreps` in Crystalline.jl (following Cano et al.) computes
         #     characters as `Tr(Θ_G D_k)` (not Θ_G†). To match, we compute `w† Θ_G D_k w`,
         #     achieved by placing `conj(Θ_G)` in the conjugated slot of the dot product.
         Θᴳ_conj = reciprocal_translation_phase(orbital_positions(ptbm), -G) # = conj(Θᴳ)
-        # NB: the `sgrep` functor computes `D_k(g) = e^{-2πi(gk)·v} ρ(h)` (physical Conv 1),
-        #     but `calc_bandreps` in Crystalline.jl uses the conjugated global phase
+        # [⚠️ phase]: the `sgrep` functor computes `D_k(g) = e^{-2πi(gk)·v} ρ(h)` (physical
+        #     Conv 1), but `calc_bandreps` in Crystalline.jl uses the conjugated global phase
         #     `e^{+2πi(gk)·v}` (cf. Crystalline.jl issue #12). To match, we conjugate the
         #     global phase by multiplying by `e^{+4πi(gk)·v}` (flipping the sign of the
         #     exponent).