Add fixed-basis QSGW workflow and regression tests

[bhjia-phys]

Summary

• Add experimental qsgw and qsgw_band driver tasks on top of the current LibRPA master architecture.
• Keep the QSGW implementation isolated in src/qsgw/ and driver/tasks/qsgw.cpp, while reusing the existing EXX, GW, RPA, symmetry, and distributed-matrix paths.
• Preserve an immutable initial KS basis (mf0) for self-energy construction, update the live eigenpairs after each fixed-basis diagonalization, and support same-grid analytic head-only updates.
• Add explicit FHI-aims/ABACUS input-contract and Vxc readers, optional linear Hamiltonian mixing, iteration traces, and qsgw_band output helpers.
• Add unit/MPI coverage plus two small two-update regressions: molecular H2O with linear mixing (beta = 0.2) and bulk Si k333 with head-only correction and no solid-state mixing.
• Remove the obsolete, unbuilt QSGW draft sources that were already present under src/qsgw/.

This does not change the numerical implementation in src/core/gw.*, src/core/exx.*, or the existing G0W0 tasks. The only shared-core helper added is PeriodicMapping::erase_mapping() in src/core/pbc.h, used by the QSGW band BvK remapping path.

Deliberate scope limits

• Hartree updates are not included.
• Independent-grid head/wing updates and the PyATB head route are rejected by input validation.
• The solid regression uses qsgw_mixer = none; linear mixing is covered only by the molecular H2O regression.
• The Si case is a workflow/numerical regression, not a claim that two updates are physically converged.

Regression footprint

• Si k333 dataset: 5.13 MB compressed.
• Si regression runtime on Fisherd with 4 MPI ranks and 1 OpenMP thread: 12.7 s including validation.

Validation

Validated at 7fc613eb2c043292a7dbf2f2b249b3761b553df8 with a Release+LibRI build on Fisherd:

• ctest --output-on-failure -j 4: 57/57 passed.
• QSGW Python comparator/wiring tests: 18/18 passed.
• python3 utilities/check_librpa_options.py: passed.
• H2O QSGW regression: passed; maximum eigenvalue-trace difference 1.253e-14 Ha.
• Si k333 head-only QSGW regression: passed; maximum eigenvalue-trace difference 1.588e-13 Ha, maximum gap difference 1.007e-12 eV.
• Existing G0W0 H2O regression: passed; maximum Wc difference 2.082e-15.
• Existing G0W0 Si grid regression: passed; maximum QP-energy difference 0.
• Existing G0W0 Si band regression: passed; maximum difference 1.0e-11, below the existing 1.0e-4 tolerance.
• git diff --check: passed.

This supersedes the closed, conflicting #6 with a clean rebase, a narrower head-only scope, and committed molecular and solid regression coverage.

[Copilot]

Pull request overview

This PR introduces an experimental fixed-basis QSGW / QSGW-band workflow to LibRPA, including a new src/qsgw/ module, driver/task wiring, and regression gates (H2O + Si head-only) while keeping the existing GW/EXX/RPA core paths unchanged except for a small PBC remap helper.

Changes:

• Add src/qsgw/ implementation building blocks (input contract + hashing, occupations, mixing, correlation potential, effective Hamiltonian assembly, tracing, and distributed-matrix helpers).
• Wire new task = qsgw and task = qsgw_band driver paths plus inputfile parsing/validation and backend comparator/wiring tests.
• Add unit/MPI tests and two committed regression testcases + reference traces for iteration summary/eigenvalue trajectories.

Reviewed changes

Copilot reviewed 77 out of 80 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/test/test_qsgw_sha256.cpp	Unit test for QSGW SHA256 helpers.
src/test/test_qsgw_projection_target.cpp	Unit test for projection target validation.
src/test/test_qsgw_occupation.cpp	Unit test for QSGW occupation analysis/update logic.
src/test/test_qsgw_mixing.cpp	Unit test for linear Hamiltonian mixer behavior and validation.
src/test/test_qsgw_input_contract.cpp	Unit test for QSGW input-contract parsing/binding/hash checking.
src/test/test_qsgw_hamiltonian_cut.cpp	Unit test for Hamiltonian cut modes/options.
src/test/test_qsgw_fixed_basis_mpi.cpp	MPI test for distributed velocity alignment to reference WFC.
src/test/test_qsgw_effective_hamiltonian.cpp	Unit test for effective Hamiltonian assembly + reference build.
src/test/test_qsgw_distributed_matrix.cpp	MPI test for BLACS collection + Spin/K map broadcast.
src/test/test_qsgw_convergence.cpp	Unit test for convergence snapshot/change computation.
src/test/test_qsgw_band_output.cpp	Unit test for legacy-format band table output + validation.
src/test/test_qsgw_band_bvk_remap.cpp	Unit test for legacy BvK remap behavior vs upstream mapping.
src/test/CMakeLists.txt	Registers new QSGW unit and MPI tests.
src/qsgw/vxc_io.h	Declares Vxc manifest + readers/projection helpers for QSGW.
src/qsgw/sha256.h	Declares SHA256 helper API for QSGW inputs/contracts.
src/qsgw/sha256.cpp	Implements SHA256 digest + hex validation.
src/qsgw/projection_target.h	Declares projection target validation API.
src/qsgw/projection_target.cpp	Implements projection target layout/finiteness validation.
src/qsgw/occupation.h	Declares QSGW occupation settings/results and update functions.
src/qsgw/occupation.cpp	Implements fixed-reference global filling + invariants/validation.
src/qsgw/mixing.h	Declares linear Hamiltonian mixing API + decision/result structs.
src/qsgw/mixing.cpp	Implements linear mixing with residual measurement + validation.
src/qsgw/matrix_map.h	Defines Spin/K and related matrix map aliases.
src/qsgw/iteration_trace.h	Declares iteration/eigenvalue/matrix trace writers.
src/qsgw/input_contract.h	Declares QSGW input contract parser + binding helpers.
src/qsgw/Hamiltonian.h	Removes obsolete/unbuilt legacy QSGW draft header.
src/qsgw/hamiltonian_mixing.h	Declares Spin/K Hamiltonian packing + mixing wrapper.
src/qsgw/hamiltonian_mixing.cpp	Implements packing/unpacking + layout validation and mixing wrapper.
src/qsgw/hamiltonian_cut.h	Declares Hamiltonian cut API (modes/options).
src/qsgw/hamiltonian_cut.cpp	Implements Hamiltonian cut behavior + validation.
src/qsgw/fixed_basis.h	Declares fixed-basis diagonalization + velocity alignment APIs.
src/qsgw/fermi_energy_occupation.h	Removes obsolete/unbuilt legacy Fermi/occupation implementation header.
src/qsgw/fermi_energy_occupation.cpp	Removes obsolete/unbuilt legacy Fermi/occupation implementation.
src/qsgw/effective_hamiltonian.h	Declares reference/effective Hamiltonian builders.
src/qsgw/effective_hamiltonian.cpp	Implements reference build + assembled effective Hamiltonian.
src/qsgw/distributed_matrix.h	Declares BLACS collection + Spin/K map broadcast helpers.
src/qsgw/distributed_matrix.cpp	Implements BLACS collection + metadata-driven broadcast w/ validation.
src/qsgw/correlation_potential.h	Declares analytic-continuation-based correlation potential builder.
src/qsgw/correlation_potential.cpp	Implements ModeA/ModeB correlation potential build with validation.
src/qsgw/convergence.h	Declares eigenvalue snapshot/change + iteration convergence gate.
src/qsgw/convergence.cpp	Implements snapshot capture and max-change computation with checks.
src/qsgw/CMakeLists.txt	Adds QSGW sources to rpa_lib.
src/qsgw/band_output.h	Declares legacy-format QSGW/KS/EXX band-table writer.
src/qsgw/band_output.cpp	Implements band-table output with layout/stream/matrix validation.
src/qsgw/band_bvk_remap.h	Declares legacy BvK remap builder used by QSGW band path.
src/qsgw/band_bvk_remap.cpp	Implements legacy remap override using new PBC erase helper.
src/core/pbc.h	Adds AtomPairBvKRemap::erase_mapping() helper used by QSGW band remap.
src/CMakeLists.txt	Integrates src/qsgw subdirectory into core build.
driver/tasks/qsgw.cpp	Adds QSGW/QSGW-band stage-one driver workflow implementation.
regression_tests/testsuite.xml	Registers new H2O + Si head-only QSGW regression testcases.
regression_tests/testcases/qsgw_aims_Si_k333_headonly_libri/librpa/librpa.in	Adds Si head-only QSGW regression input (no mixing).
regression_tests/testcases/qsgw_aims_mole_H2O_libri/librpa/librpa.in	Adds molecular QSGW regression input (linear mixing beta=0.2).
regression_tests/refs/qsgw_aims_Si_k333_headonly_libri/librpa/librpa.d/qsgw_iterations.dat	Adds reference iteration-summary trace for Si head-only regression.
regression_tests/refs/qsgw_aims_mole_H2O_libri/librpa/librpa.d/qsgw_iterations.dat	Adds reference iteration-summary trace for H2O regression.
regression_tests/backend/test_qsgw_driver_wiring.py	Adds Python wiring tests asserting key QSGW driver invariants.
regression_tests/backend/comparisons/test_cmp_qsgw.py	Adds unit tests for QSGW trace comparators/contracts.
driver/test/test_qsgw_inputfile.cpp	Adds driver inputfile parsing/validation tests for QSGW parameters.
driver/test/CMakeLists.txt	Registers new test_qsgw_inputfile target/test.
driver/task.h	Exposes task_qsgw / task_qsgw_band task entry points.
driver/task.cpp	Registers QSGW tasks in task dispatch map.
driver/inputfile.cpp	Adds QSGW-specific parsing + validation for new driver parameters.
driver/driver.h	Adds QSGW driver parameters to DriverParams.
driver/driver.cpp	Initializes and formats new QSGW driver parameters.
driver/CMakeLists.txt	Adds tasks/qsgw.cpp to driver build.
docs/user_guide/runtime_parameters.yml	Documents the new experimental QSGW runtime parameters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.