NESTOR is a unified, Python-based framework for computing and analyzing the electronic susceptibility (Lindhard χ) and Fermi-surface nesting functions (EF-JDOS) in crystalline materials.
It bridges first-principles DFT data from electronic structure codes such as VASP and Quantum ESPRESSO (QE) to reveal charge-density-wave (CDW), spin-density-wave (SDW), and van-Hove–related instabilities.

NESTOR provides a comprehensive workflow for evaluating and visualizing both static (ω → 0) and dynamic (ω > 0) susceptibilities χ(q, ω), with full control over Fermi smearing, temperature, and broadening.
The toolkit enables form-factor-resolved decomposition (TOTAL / INTRA / INTER) and chemical-potential-shift (saddle-point) analysis — allowing you to track and interpret instability trends across q-space.

• 🧩 Compute both static (χ(q, 0)) and dynamic (χ(q, ω → 0)) susceptibilities on uniform 2D/3D q-grids, with finite-T smearing and η-broadening.
• ⚛️ Include band-resolved form factors
  (|⟨ψ_{k+q}| e^{i q·r} |ψ_k⟩|²) from VASP (WAVECAR) or QE (wfc.dat)* with INTRA/INTER separation
• 🧮 Extract χ(q) along high-symmetry paths
• 🧠 Saddle-point mode: compare χ(q) at μ = E_F and μ = E_F + Δ to reveal van-Hove/CDW tendencies
• 🔍 Automated peak detection and q* (maximum) identification for Re[χ], Im[χ], |χ|
• 🗺️ Publication-quality 2D contours and 3D surfaces, with optional interpolation
• ⚙️ Parallel execution with interpolation fallback near Brillouin-zone edges

• Features
• Theory (short)
• Supported DFT inputs: VASP & QE
• Installation
• Key Commands
• Quick start
• CLI reference
• Input file (lindhard.inp)
• Energy-window harmonization
• Outputs
• How results are normalized & units
• Tips, performance, and common pitfalls
• Examples
• Changelog
• Citation
• Authors
• License
• Acknowledgments
• Further reading

• VASP or QE band structures and (optionally) wavefunctions
• 2D or 3D systems with correct area/volume normalization
• Static and dynamic $\chi(\mathbf{q},\omega)$ with configurable $\omega$-grid
• EF-JDOS / nesting with either Gaussian or thermal windows
• Form factors (on/off) multiplying the Lindhard kernel (requires WAVECAR or QE .save/ wavefunctions)
• High-symmetry path and uniform q-grid support
• Parallelism with --nprocs
• Single “smart” energy half-window --ev_window (harmonizes older knobs)
• Configuration by CLI and/or INI (lindhard.inp) with command-line override

$$ \chi(\mathbf{q},\omega) = -\frac{e^{2}}{V_d}\sum_{\mathbf{k},n,m}\sum_{s} \frac{f_{n\mathbf{k}s}-f_{m,\mathbf{k}+\mathbf{q},s}} {\varepsilon_{n\mathbf{k}s}-\varepsilon_{m,\mathbf{k}+\mathbf{q},s}+\hbar\omega+i\eta} \big| \langle \psi_{n\mathbf{k}s} | e^{i\mathbf{q}\cdot\mathbf{r}} | \psi_{m,\mathbf{k}+\mathbf{q},s}\rangle \big|^{2}_{\text{(optional)}} $$

• Prefactor & sign: the code uses $-e^2/V_d$, where $V_d$ is area (2D) or volume (3D).
• Spin: the code sums over spin $s$. There is no fixed factor 2; non-spin-polarized cases effectively yield a factor $\approx 2$ via the spin sum.
• Occupations $f$: from file or Fermi–Dirac $f(\varepsilon;\mu,T)$ using the global $E_F$ and $T$.
• Broadening: $\eta$ is a small positive broadening (in eV); $\omega=0$ gives the static limit.
• Form-factor (optional): if enabled, the plane-wave matrix element $|\langle \psi|e^{i\mathbf{q}\cdot\mathbf{r}}|\psi\rangle|^{2}$ is included; otherwise it is effectively set to 1.

$$ \xi(\mathbf{q}) \propto \sum_{\mathbf{k},n,m} \omega\big(\varepsilon_{n\mathbf{k}}-\mu\big); \omega\big(\mu-\varepsilon_{m,\mathbf{k}+\mathbf{q}}\big) \Big[ \big|\langle \psi_{n\mathbf{k}}|e^{i\mathbf{q}\cdot\mathbf{r}}|\psi_{m,\mathbf{k}+\mathbf{q}}\rangle\big|^{2}\Big]_{\text{(optional)}} $$

with window choices:

• Thermal: $\omega(E)= -\partial f/\partial E$ at $(\mu,T)$ (enabled via --jdos_thermal).
• Gaussian: $\omega(E)=\exp[-E^{2}/(2\sigma^{2})]$ with $\sigma \sim \eta$ (tunable).
• Constant-energy JDOS: the code also supports $E=\mu+\Delta$ slices (e.g., $\Delta=0,\pm$ meV).

Notes: $\mu$ is the Fermi level; optional overlap weighting uses the same plane-wave matrix element as in $\chi$. Normalization constants are handled internally for plotting/export.

Both codes are supported symmetrically:

• Bands / eigenvalues: EIGENVAL
• Wavefunctions (optional; needed for --include_ff): WAVECAR
• Structure: POSCAR or other --struct_file formats supported by ASE
• High-symmetry path (optional for path/dynamic plots): KPOINTS.hsp

Run a dense NSCF to produce EIGENVAL (and WAVECAR if form factors are requested).

• Bands / eigenvalues & occupations: read from a QE .save/ folder
• Wavefunctions (optional; needed for --include_ff): from the same prefix.save/
• Structure: can be read from .save/ or supplied via --struct_file
• High-symmetry path (optional for path/dynamic plots): KPOINTS.hsp

Pass the QE prefix via --wavefxn si to refer to si.save/ (do not include .save). If omitted, the first *.save/ in the working directory is used.

Install NESTOR directly from PyPI — all dependencies are installed automatically.

pip install -U nestors

git clone https://github.com/<your-org-or-username>/nestor.git
cd NESTOR
python -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -e .

🧩 Key Command-Line Options

nestors \
  --code VASP \
  --eigenval ./EIGENVAL \
  --dim 2 \
  --num_qpoints 80 \
  --eta 0.02

nestors \
  --code QE \
  --wavefxn si      # uses si.save/
  --dim 3 \
  --num_qpoints 60 \
  --eta 0.03

nestors \
  --code VASP \
  --eigenval ./EIGENVAL \
  --jdos \
  --dim 2 \
  --num_qpoints 120 \
  --eta 0.02

nestors \
  --code QE \
  --wavefxn si \
  --dynamic --omega_min 0.0 --omega_max 0.5 --num_omegas 200 \
  --selected_q_labels "Γ,M,K" \
  --eta 0.02

nestors \
  --code VASP \
  --eigenval ./EIGENVAL \
  --wavefxn ./WAVECAR \
  --include_ff \
  --dim 3 --num_qpoints 64 \
  --eta 0.02

Run python nestors -h for the up-to-date help.

You can place a lindhard.inp file in the run directory. It is an INI file with a [LINDHARD] section. CLI options override INI values.

Example (VASP, static (\chi), EF-JDOS with Gaussian window):

[LINDHARD]
code = VASP
struct_file = POSCAR
eigenval = EIGENVAL
wavefxn = WAVECAR
dim = 2

num_qpoints = 120
eta = 0.02
output_prefix = nbse2_2d

# smart energy half-window (eV). If omitted, it's chosen automatically.
ev_window = 0.5

# occupations, mu, temperature
occ_source = dft
temperature = 50.0
mu_override =

# EF-JDOS controls
jdos = true
jdos_offsets_ev = -0.1, 0.0, 0.1
energy_window_sigmas = 4.0

# interpolation / path
interpolate = true
interpolation_points = 300
points_per_segment = 100
hsp_file = KPOINTS.hsp

# optional
include_ff = false
nprocs = 8

Example (QE, dynamic (\chi(\mathbf{q},\omega)) with form factors):

[LINDHARD]
code = QE
wavefxn = si          ; will use si.save/
dim = 3

dynamic = true
omega_min = 0.00
omega_max = 0.50
num_omegas = 200
selected_q_labels = Γ, X, M, Γ

eta = 0.02
temperature = 300.0
occ_source = fermi
mu_override =        ; leave blank for auto

include_ff = true    ; needs wavefunctions
num_qpoints = 64
output_prefix = si_dyn

• run_YYYY-mm-dd_HHMMSS.log – full log (also mirrored to console).
• Grids: lindhard_sp_{real,imag,abs}.csv and *.png (2D & 3D variants).
• Path plots: *_sp.png for Real/Imag/|χ| along the HSP path.
• Dynamic: *_sp_q_(qx,qy,qz)_omega_{Real,Imag,Abs}.png.
• Peak summaries: *_qmax.txt with (q*_x, q*_y, value).
• If you use move_plots_to_folder(), they’ll be collected under Lplots/.

A single half-window (--ev_window) drives both:

1. Wavefunction / coefficient reads (e.g., from VASP WAVECAR or QE .save/)
2. Band preselection for EF-JDOS / (\chi) near (\mu)

If you omit --ev_window, the code chooses automatically: [ \text{ev_window} = \max\big(4 k_B T,\ \text{energy_window_sigmas}\times\eta,\ \text{legacy overrides}\big), ] with a practical floor (larger if --include_ff is enabled). Legacy knobs --window_ev and --band_window_ev are deprecated and only used if you explicitly set them (INI/CLI).

All files are prefixed by --output_prefix (default: lindhard).

• <prefix>_chi_real.npy/.csv — Real part
• <prefix>_chi_imag.npy/.csv — Imag part
• <prefix>_chi_abs.npy/.csv — Magnitude
• <prefix>_chi_heatmap.pdf/png — Heatmap
• <prefix>_path_chi.csv — Along high-symmetry path (if provided)

• <prefix>_chiw_<label>.npy/.csv — Per selected q-label vs (\omega)
• <prefix>_chiw_<label>.pdf/png — Plots per label
• <prefix>_chiw_grid.h5 (optional) — Grid data cube if enabled in code

• <prefix>_jdos.npy/.csv — EF-JDOS values on the q-grid
• <prefix>_jdos_heatmap.pdf/png — Heatmap
• <prefix>_jdos_offsets.csv — If multiple energy offsets were requested

• <prefix>_fermi_surface.* — Fermi surface plot/data when --fermi_surface
• Logs: run.log (depending on your logger settings)

• Energies ((\epsilon,\ \eta,\ \omega)) are in eV.
• q is in reciprocal-lattice units unless otherwise noted.
• Normalization uses area (2D) or volume (3D), from the input structure.
• A spin-degeneracy factor 2 is included by default.
• Temperature T is in K; (k_B T) internally converted to eV.

• Converge the DFT and use dense k-meshes for accurate nesting.

• Form factors (--include_ff) significantly increase I/O (need wavefunctions). Use a sensible --ev_window to avoid reading unnecessary bands.

• Temperature & occupations:

  • --occ_source dft: use occupations stored by the DFT code (common for NSCF).
  • --occ_source fermi: recompute occupations from (--mu, --temperature).

• Dynamic runs: ensure --num_omegas and ([\omega_{\min},\omega_{\max}]) resolve features; (\eta) controls smoothing.

• Interpolation helps visualization along paths but does not replace a dense NSCF.

• 2D vs 3D: set --dim correctly; normalization changes.

• Parallelism: use --nprocs to speed up k/q loops.

• High-symmetry path file (KPOINTS.hsp) example format:

  Γ   0.0 0.0 0.0
  X   0.5 0.0 0.0
  M   0.5 0.5 0.0
  Γ   0.0 0.0 0.0
  

  Unicode Γ is supported.

 nestors \
  --code VASP \
  --eigenval EIGENVAL \
  --dim 2 \
  --num_qpoints 100 \
  --eta 0.015 \
  --temperature 150.0 \
  --output_prefix nbse2_static

If --ev_window is omitted, it will be set by (\max(4k_BT,\ \text{energy_window_sigmas}\times\eta)) (with safe floors).

nestors \
  --code QE \
  --wavefxn si \
  --dim 3 \
  --jdos --jdos_thermal \
  --eta 0.02 \
  --temperature 300 \
  --num_qpoints 80 \
  --output_prefix si_jdos_T

nestors \
  --code VASP \
  --eigenval EIGENVAL \
  --wavefxn WAVECAR \
  --include_ff \
  --dynamic --omega_min 0.0 --omega_max 0.4 --num_omegas 160 \
  --selected_q_labels "Γ,M,K,Γ" \
  --eta 0.02 \
  --output_prefix dyn_ff

nestors \
  --code VASP --dim 2 \
  --eigenval EIGENVAL --struct_file POSCAR \
  --num_qpoints 101 --eta 0.02 \
  --auto_saddle \
  --temperature 50 --occ_source fermi \
  --output_prefix chi_autoSP

nestors \
  --code QE \
  --dim 3 \
  --eigenval ./calc/data-file-schema.xml \
  --struct_file cif \
  --include_ff --wavefxn si \
  --num_qpoints 60 --eta 0.03 \
  --temperature 100 --occ_source fermi \
  --output_prefix chi_q_QE_ff

nestors --input_file lindhard.inp --num_qpoints 96 --eta 0.03

Speed tips: add -j 8 to use 8 processes; add --quiet to hide progress bars.

• Single smart window --ev_window harmonizes legacy --window_ev and --band_window_ev.
• Explicit VASP & QE parity in I/O handling and documentation.
• Added temperature, mu, and occupation-source controls to README and examples.

• Normalization and units reviewed (2D area / 3D volume).
• EF-JDOS windows clarified; optional thermal window added.

• Initial public release: static/dynamic (\chi), EF-JDOS, path plotting.

If you use NESTOR in your research, please acknowledge and cite the software as:

   @article{Ekuma2025NESTOR,
   author       = {Nwaogbo, Chidiebere and Ekuma, Chinedu Ekuma},
  title         = {NESTOR: An Open-Source Computational Toolkit for Electronic Instabilities},
  year          = {2025},
  volume        = {XX},
  number        = {XX},
  journal       = {Computer Physics Communication},
  doi           = {10.5281/XXX}
}

You may also cite the repository directly:

GitHub Repository: https://github.com/gmp007/NESTOR

Chinedu Ekuma — Department of Physics, Lehigh University, Bethlehem PA, USA
📧 [email protected] | [email protected]

Contributors: Chidiebere Nwaogbo

MIT (see LICENSE)

• Community tools and literature on CDWs and electron response.
• ASE for structure I/O.
• U.S. Department of Energy, Office of Science, Basic Energy Sciences, under award DE-SC0024099 (code development) and the U.S. National Science Foundation award NSF DMR-2202101 (modeling instabilities).

• N. W. Ashcroft & N. D. Mermin, Solid State Physics
• Lindhard, J., On the Properties of a Gas of Charged Particles, Kongelige Danske Videnskabernes Selskab, Matematisk-Fysiske Meddelelser, 28 (8), 1954.

If you have questions or run into issues, please open a GitHub issue with your command line, INI file (if used), and a short description of your DFT inputs (code, k-mesh, smearing, etc.).