Optimize complex CPU contractions with faer GEMM

[exAClior]

Summary

• dispatch Standard<Complex32> and Standard<Complex64> to faer in all four CPU GEMM paths
• borrow contiguous, transposed, positive/negative-stride, and direct batched layouts without copying inputs
• allocate one batched result buffer and write batches directly, while allowing faer's internal workspace
• preserve genuine zero extents in CPU contraction planning and add public regressions
• add deterministic TDVP-shaped benchmarks and record controlled baseline/candidate medians

No public API or contraction-order behavior changes.

Performance

Controlled Criterion median comparison on 6xa800 (Intel Xeon Platinum 8378A, Rust 1.88.0): scalar baseline eaf29fe, faer implementation 6c273ae.

chi=64 case	Baseline median	faer median	Speedup
h1 left environment	7.94239 ms	0.613996 ms	12.94x
h1 right environment	12.0928 ms	0.944706 ms	12.80x
h2 left environment	17.5628 ms	1.18860 ms	14.78x
h2 right environment	31.9260 ms	1.88922 ms	16.90x

Full median speedup ranges:

• chi=32: 7.77x-12.10x
• chi=64: 12.80x-16.90x
• chi=128: 18.23x-23.19x

The existing real-f32 binary suite showed no repeatable regression above 5%. Full confidence intervals and throughput are recorded in benchmarks/complex_tdvp.md.

Verification

• make check
  • formatting and clippy with tropical parallel
  • 158 library tests passed; 11 ignored
  • 333 integration tests passed
  • 16 doctests passed; 4 ignored
• cargo bench --bench complex_tdvp --no-run
• representative 64x64 batched allocation regression
• fresh-context review-implementation: APPROVE, Git audit PASS; complete verdict posted as a PR comment

Known follow-up

• downstream rydbergsim-rs TDVP validation remains pending
• runscribe was unavailable on both benchmark hosts; the exception and easy-ssh provenance are documented
• non-blocking review note: aggregate make bench does not yet invoke bench-complex-tdvp; the direct target is available

Risk / rollback

The main risk is incorrect exact-type dispatch or layout rebasing. Casts remain adjacent to checked TypeId branches, and both complex widths are covered across contiguous, transposed, arbitrary-stride, batched, and zero-size cases. Reverting the implementation commit restores the scalar fallback.

Refs #53

[exAClior]

Code Quality Review

Updated for PR head ef80db8 after the allocation-counter CI fix.

Build Status

• Local make check: PASS — 159 library tests passed (11 ignored), 333 integration tests passed, and 16 doctests passed (4 ignored).
• GitHub CI and Coverage: action required — no jobs were created for the new head; maintainer approval is required before merge.

Design Principles

• DRY: ISSUE — CPU shadows the shared dimension-product helper to preserve zero extents (src/backend/cpu/contract.rs:5-20), while the backend-neutral helper collapses zero to one (src/backend/contract_plan.rs:76-83). Consolidation is desirable, but the shared CUDA semantics must be checked first.
• KISS: OK — generic faer helpers cover all four standard scalar types without adding a trait hierarchy (src/backend/cpu/mod.rs:748-891).
• HC/LC: OK — specialization remains behind the crate-private CPU GEMM boundary (src/backend/cpu/mod.rs:208-430, src/backend/cpu/mod.rs:514-616).

Public-API ergonomics

• Error messages: Not applicable — no public error path changed.
• Discoverability: Not applicable — no public surface changed.
• Consistency: Not applicable — public contraction APIs are unchanged.
• Least surprise: Not applicable — output ordering and non-conjugating einsum semantics are preserved.
• Feedback: Not applicable — no interactive interface changed.

Test Quality

• Naive test detection: OK
  • Hand-checked products detect accidental conjugation for both complex widths.
  • Rectangular, transposed, positive/negative-stride, and batched layouts compare concrete values against generic GEMM.
  • Public zero-free and zero-contracted regressions check both shapes and values (tests/suites/binary_rules.rs:15-30).
  • Allocation behavior is measured after warm-up, and the new two-thread regression deterministically verifies counter isolation (src/backend/cpu/mod.rs:173-199).

Change Hygiene

• Docs/config consistency (code.config-docs-consistent): ISSUE — make bench omits bench-complex-tdvp despite claiming to run all Rust benchmarks (Makefile:149-159). The committed verification record and PR body also still say 158 library tests instead of 159 (benchmarks/complex_tdvp.md:210-212).
• Dependency reproducibility (dependency.reproducible): Not applicable — no dependency changed; Cargo.toml only registers the benchmark target.

Git Audit (from github-pr-audit)

• GATE: PASS
• harm.secrets (security.no-secrets): OK — no credential, token, private-key, or sensitive-data patterns found in the committed range or local candidates.
• harm.dangerous-files (git.harm-signals): OK — the committed range contains ordinary text files and no conflicts, archives, or binaries. Machine-specific .easy-ssh* files remain untracked and outside the PR.
• harm.generated-artifacts (code.generated-artifacts): OK — none are committed. Raw benchmarks/runs/ output remains untracked and should not be bulk-added.
• harm.cache (code.generated-cache): OK — no cache directory is committed or visible among candidates.
• harm.debug-leftovers (code.debug-leftovers): OK — no production debug probes, conflict markers, breakpoints, or WIP markers were added.
• pr.description-quality (github.pr-description-quality): OK — PR Optimize complex CPU contractions with faer GEMM #54 states scope, benchmark results, verification, pending downstream work, and rollback risk.
• pr.traceable (github.prs-traceable): OK — the PR and benchmark record link issue Optimize Standard complex CPU contractions with faer GEMM #53.

Issues

Critical (Must Fix)

None.

Important (Should Fix)

None.

Minor (Nice to Have)

• Consolidate zero-extent dimension handling after checking CUDA behavior.
• Add bench-complex-tdvp to the aggregate make bench recipe.
• Update the committed verification count and PR body from 158 to 159 library tests.

Summary

• No correctness or soundness blocker found. Exact TypeId guards remain adjacent to casts; faer views use checked layout rebasing; ordinary multiplication does not conjugate operands.
• Coverage is concrete across both complex widths, adversarial layouts, zero extents, batching, allocation behavior, and deterministic thread isolation.
• Git audit passes; local profiling/config artifacts are not PR content.
• Final verdict: APPROVE — no Critical or Important findings. Do not merge until CI is approved and passes.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[exAClior]

The generic operand-materialization optimization discovered during follow-up profiling has been split out of this PR. It is tracked in #55 and stacked draft #56; #54 remains focused on Complex64 faer dispatch and validation.