abacus-librpa-gw

name	abacus-librpa-gw
description	ABACUS + LibRPA GW workflow guidance and static input checks. Use when planning, preparing, or validating GW runs, including SCF/DF/NSCF chaining, librpa.in consistency, and safe run-directory setup.

ABACUS + LibRPA GW

Execution order depends on system type:

• molecule: default to the short route SCF -> LibRPA unless the user explicitly needs extra band preparation; skip pyatb
• solid: SCF -> DF (pyatb_librpa_df) -> NSCF -> preprocess_abacus_for_librpa_band.py -> LibRPA

If the case uses a locally merged ABACUS checkout or locally patched helper scripts, also apply references/abacus-merge-compat.md.

Required Checks

• Verify nbands in both INPUT_scf and INPUT_nscf is equal to the basis-function count.
• Verify INPUT_scf and INPUT_nscf use the same nbands.
• Compute basis-function count from .orb files using angular-momentum degeneracy (s=1, p=3, d=5, f=7, ...), multiply by radial multiplicity, sum over all atoms in the primitive cell, and multiply by 2 when SOC is enabled.
• Cross-check the final nbands against NBASE in ABACUS output.
• Verify spin/SOC settings are aligned across files:
  • collinear spin without SOC -> nspin = 2, lspinorb = 0
  • noncollinear with SOC -> nspin = 4, lspinorb = 1
• Verify template-generated inputs using explicit lattice vectors set latname = user_defined_lattice.
• Verify old exx_use_ewald has been replaced by exx_singularity_correction = massidda.
• Verify get_diel.py uses matching nspin and the updated Fermi-energy parser.
• Verify preprocess_abacus_for_librpa_band.py matches the current wavefunction filename conventions and uses matching use_soc when applicable.
• Verify librpa.in uses matching use_soc = 0/1.
• Verify librpa.in is generated from the same ABACUS workflow chain.
• Verify the run is in a fresh directory to avoid stale-output contamination.
• If the run directory is created by copying an older case, keep only source inputs and workflow scripts; remove generated outputs such as OUT.ABACUS, band_out, coulomb_*, LibRPA*.out, librpa.d, time.json, and old GW_band_spin_* before submission.
• Prefer a user-curated server-side reference bundle when available.
• When generating a GW case from templates, materialize the route first with oh-my-librpa/scripts/materialize_gw_template.sh and treat .oh-my-librpa-route.env as the authoritative route record.
• Recognize the canonical file bundle from server examples:
  • INPUT, INPUT_scf, INPUT_nscf
  • KPT, KPT_scf, KPT_nscf
  • STRU, geometry.in, librpa.in
  • get_diel.py, perform.sh, preprocess_abacus_for_librpa_band.py, run_abacus.sh, output_librpa.py, plot_gw_band_paper.py
  • .orb, .abfs, .upf
• For server runs, prefer a materialized host profile (env.sh) with explicit python3_exec, executable paths, launcher paths, and any required .bashrc / conda activation steps instead of relying on implicit login-shell luck.
• For server Slurm submissions, probe the target server and partition for node shape before submission, then verify the batch script against those live facts. For 1 MPI rank/node, --cpus-per-task and OMP_NUM_THREADS should use the full discovered per-node core count, and --mem should use the full discovered per-node RealMemory in MB unless the user explicitly requests a smaller allocation.
• Build ABACUS and LibRPA against current abacusmodeling/LibRI and abacusmodeling/LibComm branch fix_status unless the user explicitly asks for an older dependency snapshot.
• For the current ABACUS/LibRPA master_ghj branches, default to reader-v1 handoff:
  • ABACUS SCF producer: out_librpa_reader_version 1
  • LibRPA reader: prefix_coul_full = v1_coulomb_full_iq_, prefix_coul_cut = v1_coulomb_cut_iq_, prefix_lri_coeff = v1_Cs_data_, prefix_lri_coeff_shrink = v1_Cs_shrinked_data_, prefix_shrink_sinvS = v1_shrink_sinvS_, fn_basis_wfc = basis_wfc_out, fn_basis_aux = basis_aux_out, and fn_basis_aux_shrink = basis_aux_shrink_out when use_shrink_abfs = t, version_coul_reader = 1, and version_lri_reader = 1
  • LibRPA GW defaults: use_cholesky_gw_wc = t, use_elpa_sqrt_coulomb = t, use_kpara_scf_eigvec = t, and libri_chi0_collect_max_bytes = 2147483648

Default librpa.in Preset for GW

For GW requests, set:

• task = g0w0_band
• nfreq = 16
• option_dielect_func = 3
• replace_w_head = t
• For the tested molecular short route, override with replace_w_head = f
• prefix_coul_full = v1_coulomb_full_iq_
• prefix_coul_cut = v1_coulomb_cut_iq_
• prefix_lri_coeff = v1_Cs_data_
• prefix_lri_coeff_shrink = v1_Cs_shrinked_data_ when use_shrink_abfs = t
• prefix_shrink_sinvS = v1_shrink_sinvS_ when use_shrink_abfs = t
• fn_basis_wfc = basis_wfc_out when use_shrink_abfs = t
• fn_basis_aux = basis_aux_out when use_shrink_abfs = t
• fn_basis_aux_shrink = basis_aux_shrink_out when use_shrink_abfs = t
• version_coul_reader = 1
• version_lri_reader = 1
• use_scalapack_gw_wc = t
• use_cholesky_gw_wc = t
• use_elpa_sqrt_coulomb = t
• use_scalapack_ecrpa = t
• parallel_routing = libri
• vq_threshold = 0
• sqrt_coulomb_threshold = 0
• use_fullcoul_exx = t
• use_kpara_scf_eigvec = t
• libri_chi0_collect_max_bytes = 2147483648
• output_gw_sigc_mat_rf = f
• Only set output_gw_sigc_mat_rf = t when the user explicitly asks to open NSCF band continuation
• libri_chi0_threshold_C = 1e-4
• libri_chi0_threshold_G = 1e-5
• libri_exx_threshold_V = 1e-1
• libri_exx_threshold_C = 1e-4
• libri_exx_threshold_D = 1e-4
• libri_g0w0_threshold_C = 1e-5
• libri_g0w0_threshold_G = 1e-5
• libri_g0w0_threshold_Wc = 1e-6

NBANDS Counting Rule

Use the .orb filenames to determine basis count:

• degeneracy by angular momentum: s=1, p=3, d=5, f=7, ...
• multiply each channel by its radial multiplicity in the filename
• sum over all atoms in the primitive cell
• if SOC is enabled, multiply the final total by 2
• set the result as nbands in both INPUT_scf and INPUT_nscf
• verify the result against ABACUS NBASE

Example:

• Ni_gga_10au_100Ry_6s3p3d2f.orb -> 6*1 + 3*3 + 3*5 + 2*7 = 44 per Ni
• 3 Ni atoms -> 3 * 44 = 132
• for the full NiI2 primitive cell the total is 264 without SOC
• with SOC -> 264 * 2 = 528
• therefore set nbands = 528 for the SOC NiI2 case

Spin and SOC Branches

Use the following alignment for spin-sensitive GW workflows:

• Collinear spin, no SOC:

  • INPUT: nspin = 2, lspinorb = 0
  • get_diel.py: set matching nspin and use_soc = False
  • preprocess_abacus_for_librpa_band.py: set use_soc = False
  • librpa.in: set use_soc = 0

• Noncollinear with SOC:

  • INPUT: nspin = 4, lspinorb = 1
  • get_diel.py: set matching nspin and use_soc = True
  • preprocess_abacus_for_librpa_band.py: set use_soc = True
  • librpa.in: set use_soc = 1

System-Type Branches for GW

Molecule

• Set KPT to 1 1 1
• Treat gamma_only as route-aware rather than a universal hard rule
• Use official ABACUS input names from the ABACUS input reference
• Do not run pyatb, NSCF, or preprocess_abacus_for_librpa_band.py; the short molecular GW route is SCF -> LibRPA.
• Set replace_w_head = f
• Set use_input_exx_symmetry = f and use_input_gw_symmetry = f in librpa.in; do not require input symmetry sidecar files such as irreducible_sector.txt, symrot_R.txt, symrot_k.txt, or symrot_abf_k.txt. use_abacus_*_symmetry is only a legacy alias for old inputs.
• Keep output_gw_sigc_mat_rf = f
• For the tested smoke path molecule + GW + no NSCF + no pyatb + no shrink, materialize the dedicated route with oh-my-librpa/scripts/materialize_gw_template.sh --case-dir <case_dir> --system-type molecule --needs-nscf false --needs-pyatb false --use-shrink-abfs false
• Keep out_mat_xc 1, out_librpa_reader_version 1, exx_singularity_correction = massidda, exx_pca_threshold 1e-6, and exx_cs_inv_thr 1e-5
• Keep LibRPA reader-v1 prefixes and selectors: prefix_coul_full = v1_coulomb_full_iq_, prefix_coul_cut = v1_coulomb_cut_iq_, prefix_lri_coeff = v1_Cs_data_, version_coul_reader = 1, and version_lri_reader = 1
• Set exx_ccp_rmesh_times equal to rpa_ccp_rmesh_times for molecular GW; using a smaller EXX mesh can leave the Coulomb/EXX matrix coverage inconsistent for LibRPA.
• Do not enable out_chg, out_mat_r, or out_mat_hs2 for that short route
• Copy OUT.ABACUS/vxc_out.dat into the working directory as vxc_out before LibRPA
• Stop before LibRPA unless v1_coulomb_full_iq_*, v1_coulomb_cut_iq_*, v1_Cs_data_*, and KS_eigenvector_*.dat exist

Solid

• Ask the user how many k-points to use in KPT; default to 8 8 8
• Only enable output_gw_sigc_mat_rf = t when the user explicitly asks to open NSCF band continuation; for a materialized case, pass --enable-nscf-band-continuation true
• KPT_nscf must be provided by the user
• Materialize env.sh from a host profile before batch submission so python3_exec, abacus_work, librpa_work, and the MPI launcher are explicit
• If launcher or python behavior is uncertain on compute nodes, materialize and run a batch-node probe before the real job
• Prefer the updated get_diel.py and preprocess_abacus_for_librpa_band.py copies that match the merged ABACUS branch; do not fall back to stale helpers that assume only legacy EFERMI parsing or one fixed wavefunction filename pattern
• Do not mix up get_diel.py and output_librpa.py: keep parser/fallback fixes in get_diel.py, but do not turn its __main__ into an IBZ-only exporter for the current head/wing route
• After SCF, run pyatb to generate the pyatb_librpa_df directory
• Then run NSCF
• Then run preprocess_abacus_for_librpa_band.py
• Then run LibRPA

Periodic symmetry + head/wing safeguard

• When replace_w_head = t, do not generate pyatb_librpa_df from IBZ k-points or star weights from legacy symmetry sidecars
• For this lane, pyatb_librpa_df must stay on the full regular k-grid
• Current LibRPA maps pyatb_librpa_df/k_path_info onto its active k-list; keep pyatb_librpa_df internally consistent and do not rewrite it into an IBZ/star-weighted payload by default
• Keep root stru_out, band_out, k_path_info, velocity_matrix, and KS_eigenvector_*.dat consistent with the same ABACUS run; current LibRPA rebuilds symmetry rotations from stru_out
• Never overwrite those root files with the full-BZ pyatb_librpa_df/* copies unless the user explicitly asks for a root-level replacement and understands the symmetry mismatch risk

Default Shrink Strategy

Use shrink by default for the generic periodic GW lane.

Do not force shrink onto the tested short molecular GW smoke route; that route uses use_shrink_abfs = f with exx_pca_threshold 1e-6.

Generic shrink lane:

• use_shrink_abfs = t
• rpa 1
• exx_pca_threshold 10
• shrink_abfs_pca_thr 1e-4
• shrink_lu_inv_thr 1e-3
• exx_cs_inv_thr 1e-5

Interpretation:

• shrink_abfs_pca_thr controls the size of the compressed auxiliary basis; default to 1e-4.
• shrink_lu_inv_thr is used to control inversion-error handling for the output sinvS; default to 1e-3.
• exx_pca_threshold = 10 means the large-basis path expects external input when shrink is enabled.
• When shrink is enabled, ABFS_ORBITAL in STRU must be specified by the user.
• If the user asks how to obtain or generate those files, load skills/abacus-librpa-abfs-orbital/.
• If the user provides .abfs files, use those filenames directly in ABFS_ORBITAL entries.
• Server examples include names such as Ga_str_4s4p3d2f2g_1e-4.abfs and As_str_4s4p3d2f2g_1e-4.abfs.

Stage Success Criteria

Use these generic checks for a full ABACUS + LibRPA GW chain.

Only LibRPA needs an explicit status judgment in the normal workflow. pyatb and preprocess are usually short and only need completion checks.

SCF success

• OUT.ABACUS/running_scf.log exists
• running_scf.log contains both Finish Time and Total Time
• OUT.ABACUS/ABACUS-CHARGE-DENSITY.restart exists and is non-empty

pyatb success

• pyatb_librpa_df/ exists
• pyatb_librpa_df/band_out exists
• pyatb_librpa_df/velocity_matrix exists
• at least one pyatb_librpa_df/KS_eigenvector_*.dat file exists

NSCF success

• OUT.ABACUS/running_nscf.log exists
• running_nscf.log contains both Finish Time and Total Time
• either OUT.ABACUS/eig.txt or OUT.ABACUS/eig_occ.txt exists and is non-empty

preprocess success

• band_kpath_info exists in the working directory
• at least one band_KS_* file exists
• at least one band_vxc* file exists

LibRPA success

• a rank-0 LibRPA output file exists, for example librpa_para_nprocs_*_myid_0.out or LibRPA*.out
• either the periodic GW outputs include at least one GW_band_spin_*.dat file and the rank-0 output contains Timer stop: total. or libRPA finished successfully
• or the molecular GW reader-v1 outputs band_out, vxc_out, v1_Cs_data_*, v1_coulomb_full_iq_*, and v1_coulomb_cut_iq_* exist and the rank-0 output contains libRPA finished successfully

LibRPA still running

• a rank-0 LibRPA output file exists, for example librpa_para_nprocs_*_myid_0.out or LibRPA*.out
• the rank-0 output does not yet contain Timer stop: total. or libRPA finished successfully
• the rank-0 output file is still growing

LibRPA failed

• there is no final Timer stop: total. or libRPA finished successfully marker
• and the rank-0 output file is no longer growing, or the output file is missing

Periodic GW Plotting

For periodic GW post-processing, prefer the bundled plot_gw_band_paper.py helper.

• Inputs: GW_band_spin_*, band_out, band_kpath_info, KPT_nscf
• Outputs: a paper-style PNG, a PDF, and a text summary
• Shift energies by the GW VBM
• Restrict CBM search to the first few conduction bands near the gap to avoid high-energy spurious roots contaminating the reported gap and the main figure

Output Requirement

For each recommendation, provide:

• why this change is needed
• what risk it addresses
• how to validate it with minimal cost
• call the installed report_stage.sh helper to update both task Markdown logs and send the user a short stage summary