mbpt: closed-shell Kramers (time-reversal) CC tracer (round 2) - #566
Draft
kshitij-05 wants to merge 11 commits into
Draft
mbpt: closed-shell Kramers (time-reversal) CC tracer (round 2)#566kshitij-05 wants to merge 11 commits into
kshitij-05 wants to merge 11 commits into
Conversation
Add spinor.{hpp,cpp}: a Kramers tracer for closed-shell relativistic
(2-/4-component) theories, structured like the naive spin tracer
spintrace_impl but folding whole-config time-reversal (T) partners into
RealPart-wrapped representatives inline. Reuses the Spin quantum number as
the Kramers label (alpha=up, beta=down); expands the integral g while
keeping the amplitude t antisymmetric; leaves particle-interchange (sigma)
to canonicalize. Also adds symbolic RealPart/ImagPart Expr markers.
External-index antisymmetry, hermiticity, and the per-column internal-T-reach
are deferred (CC phase).
test_spinor.cpp: traces the MP2 energy 1/4 g-bar t-bar into 7 canonical
Re[g.t-bar] representatives whose outer coefficients sum to 2^n.
…lic)
Extend spinor.{hpp,cpp} toward Kramers-restricted CCSD (symbolic phase):
- kramers_config_orbits: rank-agnostic n-bit configuration orbits under a set
of bit-permutation generators + optional global time reversal T (the fold
engine).
- closed_shell_kramers_CC_trace: stages 1-2 of the CCSD pipeline. Factor out
the antisymmetrizer  (its bra/ket give the external virt/occ groups), fold
the external indices (rank-general S_k transpositions + T) into the
symmetry-unique blocks, and fold the internal contracted indices (enumerate
+ sum, sigma-merge via canonicalize). A-expand, g-expansion and the g TRS
folds (stages 3-5), and the internal-T-reach, are deferred.
- kramers_external_blocks: per-member sign/conj/perm reconstruction transforms
(compute the canonical block, fill the rest) -- the eval-time external
reconstruction (notes' open item).
Validated symbolically (test_spinor.cpp): singles/doubles/triples external
folds (2/5/8 blocks); CCD driver/pp-ladder/ring/quad internal folds
(5 blocks; 3/4/9 internal classes -- the quad's 9-vs-10 noted); reconstruction
transforms (perm/conj<->config invariant, T-pair signs).
Add an optional symm_perms argument (sign +1 permutation generators, default
none) alongside antisym_perms (sign -1), so the eval-time external
reconstruction also covers a raw, non-antisymmetrized g leaf: it folds under
particle interchange sigma (a symmetry, sign +1) + T into 6 blocks, vs the
antisymmetric residual's {P_ab, P_ij} + T into 5. Tested (test_spinor.cpp): the
{sigma} + T case yields 6 blocks with the sigma members carrying sign +1.
Thin public wrapper over the file-local find_antisymmetrizer, so a caller (the CC spintrace dispatch) can distinguish a residual equation (carries a leading Â) from a fully contracted scalar (the energy, no Â) and route each to the right Kramers tracer.
- closed_shell_kramers_CC_trace: fold each residual term over its OWN contracted indices, not the whole block over the union of all terms' internals. A term invariant under an index (e.g. the driver, which has no internal index) was over-counted 2^k. Only surfaces on the full multi-term R2 — the unit tests feed single terms, so single-term behavior is unchanged (114 [spinor] assertions still pass). - closed_shell_kramers_trace: add fold_T (default true). With fold_T=false, emit every configuration (sigma-merged) verbatim with no RealPart wrapper — the complex config sum whose real part the caller takes — for evaluators that cannot evaluate Re() of a tensor network (the CCk energy observable).
When expand_g=false, the integral g is kept antisymmetric (ḡ) instead of expanded to the level-1 raw-g form, so the evaluator fetches the factory [as] block and the cross-Kramers antisymmetry is handled inside the integral. The CCk energy path uses expand_g=false; g-expansion (level-1) remains the default and a later optimization stage. Default expand_g=true preserves SpinorMP2 behavior.
The CCSD Kramers trace now A-expands the antisymmetrizer  (expand_A_op) into explicit signed external permutations, so the full external antisymmetry — cross-Kramers pairs included — is explicit per term. The earlier strip- + within-block bitwise form could not antisymmetrize cross-Kramers t-dependent terms (a post-hoc block sign only flips, it does not antisymmetrize). Adds two flags: expand_g (expand each ḡ to raw NonSymm leaves so the evaluator fetches raw ⟨..|..⟩ blocks instead of the factory [as] block, which omits the cross-Kramers swap for mixed-Kramers pairs) and use_T (fold external configs under global time reversal; default on).
The eval-node CSE identity (the canonical colored connectivity graph) is value- invariant for ordinary tensors but not for complex tensors whose leaf value is reconstructed downstream (e.g. relativistic Kramers t-amplitudes via an external recon): two contractions can share a canonical graph yet evaluate to genuinely different (NOT merely sign-flipped) tensors, surfacing as a +1/-1 canon_phase collision. Keying canon_phase into the eval-node equality splits those apart. This only ever splits cache entries (never merges), so it is correctness- preserving; real closed-shell paths (all phase +1) are unaffected and lose no CSE. Interim hack. TODO: replace with a faithful conjugation-aware eval-node identity once TensorNetworkV3 exploits BraKetSymmetry::Conjugate (carry the conjugation through canonicalization, the way canon_phase carries the sign).
compose() composed the reconstruction perm in reversed order (tx.perm[g_perm[k]] instead of g_perm[tx.perm[k]]) for the convention block(cfg)[v] = block(canon)[v_perm]. The two orders agree for the abelian S1/S2 external groups of singles/doubles (all involutions), so CCD/CCSD were unaffected, but differ for the non-abelian S3+ groups of triples and higher, where 3-cycles reconstructed to the wrong tensor. Validated offline at ranks 1-4 against a fully antisymmetric + TRS reference (reversed order fails at rank 3; this order passes to machine precision at every rank).
The S_rank adjacent-transposition generator set for the external Kramers fold (virtual group [0,rank), occupied group [rank,2*rank)) was hand-built inline in closed_shell_kramers_CC_trace and, MPQC-side, in two more places (the amplitude allocator and the leaf reconstruction). Provide it as one shared helper and use it in the tracer. Pure refactor.
kshitij-05
marked this pull request as draft
June 30, 2026 16:28
Orphaned when 7f69992 switched A-handling to expand_A_op; its only references are its own definition and a self-recursive call, so it is unused. clang -Wunneeded-internal-declaration (-Werror) in SeQuant's unit build rejects it (the MPQC build that validated the branch uses looser flags, so it slipped through).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a closed-shell Kramers (time-reversal-symmetry) tracer for relativistic
2-/4-component coupled cluster to
mbpt, plus the eval-layer CSE fix needed toevaluate the complex tensors it produces. This is the "round-2" rebuild of the
Kramers tracer: a small, self-contained API that mirrors the existing spin
tracer in structure but folds Kramers configurations under time reversal instead
of applying Ms conservation.
The tracer takes an all-spinor (Kramers-free) closed-shell expression and emits a
sum over time-reversal-canonical Kramers-block representatives, each with the
{sign, conjugation, permutation}transform that reconstructs the remainingblocks. A consumer (here, MPQC's
CCk/SpinorMP2) evaluates one representativeblock per symmetry orbit and fills the rest from the transforms, so the
relativistic residual is computed on a reduced set of unique blocks (doubles:
16 → 5).
All numerics are validated downstream in MPQC against the full-spinor
("spinorbital") oracle: MP2, CCD, CCSD, and CCSDT all reproduce the spinor
energy (e.g. HSeOH/6-31G X2C: CCD 2.6e-11, frozen CCSDT 2.1e-10). The unit
tests here cover the symbolic structure (orbit counts, fold classes,
reconstruction transforms).
What's added
SeQuant/domain/mbpt/spinor.{hpp,cpp}— the tracer and its orbit machinery:closed_shell_kramers_trace(expr, ext_groups, fold_T, expand_g)2 Re[...].closed_shell_kramers_CC_trace(expr, expand_g, use_T)kramers_config_orbits(n, bit_perms, use_T)kramers_external_generators(rank)kramers_external_blocks(n, antisym_perms, use_T, symm_perms)kramers_config_orbitsbut each member carries its reconstruction transformblock(cfg) = sign·[conj]·permute(block(canonical)).has_antisymmetrizer(expr)RealPart/ImagPart(+real_part/imaginary_part)2 Refold; symbolic-only (no native TN evaluation yet — see below).SeQuant/core/eval/eval_node_compare.hpp— split CSE cache keys bycanon_phase. For complex/Kramers tensors whose leaf value is reconstructeddownstream, two contractions can share a canonical colored graph yet evaluate to
genuinely different (not merely sign-flipped) tensors; without this they
over-merge under CSE and reuse the wrong intermediate. The split only ever
separates cache entries (never merges), so it is correctness-preserving and
real closed-shell paths (all phase +1) are unaffected.
tests/unit/test_spinor.cpp— orbit counts and reconstruction transforms:MP2-energy fold, rank-general external folds (ranks 1/2/3), CCD R2 → 5 labeled
blocks, internal-fold classes (pp-ladder, ring, separable T2² quad), and the
kramers_external_blocksreconstruction transforms (antisymmetric residual andraw-g forms). Build glue in
CMakeLists.txt/tests/unit/CMakeLists.txt.Known limitations / follow-ups
BraKetSymmetry::Conjugateis not yet exploited byTensorNetworkV3. Theeval_node_comparecanon_phasesplit is the interim correctness measure; thefaithful fix is to carry conjugation through canonicalization (TODO noted in
the header). This is the keystone for the planned next step — teaching the
canonicalizer time-reversal symmetry so the downstream reconstruction machinery
dissolves.
Re()/Im()evaluation of a tensor network — the tracer emitsRealPart/ImagPartmarkers and the consumer either honors them or uses thefold_T=falseform (sum the complex blocks, take the real part).applied here.
Testing
tests/unit/test_spinor.cpp— symbolic structure (orbit counts, fold classes,reconstruction transforms).
(
SpinorMP2/CCk): Kramers-restricted MP2/CCD/CCSD/CCSDT all match thefull-spinor energy to the SCF/precision floor.