Configuration and Tuning

Overview

All gauNEGF default parameters live in gauNEGF.config. You can override them locally by passing them as arguments to contact setup functions (eta=, T=) or to SCF (tol=, damp=). This guide covers the parameters most likely to need tuning when optimizing convergence for your system.

Default Configuration

The table below lists the configuration constants that control convergence behavior. You need not change most of them; the defaults are conservative and appropriate for most DFT + NEGF calculations.

Tunable Configuration Parameters

Parameter

Default

Type

Purpose

SCF_DAMPING

0.02

float

Controls density matrix update aggressiveness in SCF

SCF_CONVERGENCE_TOL

1e-3

float

SCF convergence threshold (eV or a.u.)

SCF_MAX_CYCLES

100

int

Maximum number of SCF iterations before stopping

ETA

1e-5

float (eV)

Imaginary broadening for Green’s function

TEMPERATURE

0.0

float (K)

Temperature for Fermi-Dirac distribution in contacts

FERMI_CALCULATION_TOL

1e-3

float

Tolerance for Fermi energy search

FERMI_SEARCH_CYCLES

10

int

Maximum search cycles before returning Fermi energy

SURFACE_GREEN_CONVERGENCE

1e-5

float

Green’s function convergence tolerance for iterative inversion

ADAPTIVE_INTEGRATION_TOL

1e-4

float

Tolerance for adaptive energy integration

PULAY_MIXING_SIZE

4

int

Number of previous densities in Pulay mixing history

Fermi Search Method (fermiMethod)

The fermiMethod parameter controls the root-finding algorithm used to determine the Fermi energy during contact setup. This is passed to gauNEGF.scfE.NEGFE.setVoltage() to select how gauNEGF solves for the electron count.

Warning

For 1D contacts set up with atom indices only (no explicit tau/alpha/beta matrices), DO NOT specify a fermi energy in setVoltage or the electron count will become unphysical! Instead use defaults or set fermiMethod . Example: negf.setVoltage(0.0)

Fermi Search Algorithms

Method

Stability

Speed

When to use

'bisect'

Highest

Slow

Always safe; default fallback when others fail. Guaranteed convergence but requires many iterations.

'muller' (default)

High

Medium

Good general-purpose default. Overshoot unlikely, defaults to bisection upon failure.

'poly'

Medium

Medium-Fast

Recommended in production. Balances stability and speed with 3rd order polynomial fitting.

'secant'

Low

Fast

Best for highly coupled contacts, unstable for weak contacts. Defaults to bisection upon failure

'predict'

Lowest

Very fast

Stable only for weakly coupled contacts, uses previous guess upon failure (check warnings)

See Choosing a Contact Type for guidance on which contact type is appropriate, and 1D Chain Contacts in gauNEGF for detailed setup instructions.

SCF_DAMPING

The SCF_DAMPING parameter controls how aggressively the density matrix is updated each SCF iteration. It acts as a mixing coefficient: new density = (1 - damping) * old + damping * computed.

Default: 0.02

Tuning guidelines:

  • Recommended Range: 0.002 to 0.1, Anything outside of that range highly unstable

  • High Mixing (0.1) for saddle points Use if iterations seem “stuck”, try with or without pulay interpolation.

  • Low Mixing (0.002) for unstable systems Use when SCF oscillates or overshoots, increase nPulay if unstable

Production strategy:

For difficult systems, use a two-phase approach: run SCF with low mixing first to find the convergence basin, then switch to higher mixing to escape any saddle points.

# Phase 1: Can be unstable until contacts mixed into system
negf.updatePulay(10)
negf.SCF(conv=1e-3, damping=0.002, maxcycles=100)

# Phase 2: Ensure not in a saddle point
negf.updatePulay(4)
negf.SCF(conv=1e-3, damping=0.1, maxcycles=100)

ETA (Broadening Parameter)

The ETA parameter controls the imaginary part of the energy (eta: E -> E + i*eta) added to the Green’s function. This broadening stabilizes the inversion and smooths spectral features.

Default: 1e-5 eV

Typical overrides:

  • 1e-3 eV: Higher eta values can improve stability of 1D contacts especially at band edges

  • 1e-5 eV (default): Recommended for most production transport calculations. Provides sharp spectral resolution while maintaining good conditioning.

  • 1e-6 eV: Use for precise calculations to capture band edges exactly, may cause numerical issues if the Green’s function is poorly conditioned.

Trade-off: Higher ETA speeds convergence and broadens spectral features; lower ETA gives sharper spectra but requires better conditioning. For production transport calculations, use the default (1e-5) unless specifically tuning spectral resolution.

Pass locally:

# Set ETA for 1D contact
negf.setContact1D([[1,2,3],[4,5,6]], eta=1e-3)

# Set ETA for Bethe contact
negf.setContactBethe([[1,2,3],[4,5,6]], eta=1e-5)

TEMPERATURE

The TEMPERATURE parameter controls thermal broadening in the contacts. It does not directly affect the device Hamiltonian, only the Fermi-Dirac distribution in the contact self-energy.

Default: 0.0 K (zero temperature, sharp Fermi cutoff)

Common values:

  • 0.0 K (default): Zero-temperature transport. Sharp electron/hole cutoff at the Fermi energy. Appropriate for single-point transmission calculations and most DFT+NEGF workflows.

  • 300 K: Room temperature. Adds thermal broadening (kT ~ 0.026 eV); electrons and holes leak slightly across the Fermi energy. Use for finite-temperature transport or to model thermal effects.

Pass locally:

# Set temperature for 1D contact
negf.setContact1D([[1,2,3],[4,5,6]], T=300)

# Set temperature for Bethe contact
negf.setContactBethe([[1,2,3],[4,5,6]], T=300)

Fermi Energy Search Tolerances

Two tolerances control Fermi energy accuracy:

FERMI_CALCULATION_TOL (default 1e-3):

Relative tolerance for the electron count during Fermi search. Convergence is achieved when |N_computed - N_target| < FERMI_CALCULATION_TOL. Loosen to 1e-2 if Fermi search oscillates; tighten to 1e-4 for strict charge neutrality.

FERMI_SEARCH_CYCLES (default 10):

Maximum number of root-finding iterations before returning. If the solver does not converge within this limit, gauNEGF returns the best estimate and logs a warning. Increase to 20-30 for difficult systems; decrease to 5 if Fermi search is a bottleneck.

Surface Green’s Function Convergence

SURFACE_GREEN_CONVERGENCE (default 1e-5):

Convergence threshold for the iterative inversion that builds the contact surface Green’s function. The default is the lowest safe value: going below 1e-5 can produce numerical instability in the contour integration and is not recommended. Going above 1e-5 (e.g. 1e-4) speeds up contact setup at the cost of slightly less accurate self-energies, which is useful for exploratory runs or initial convergence sweeps.

Integration Tolerances

ADAPTIVE_INTEGRATION_TOL (default 1e-4):

Tolerance for adaptive energy integration in density matrix calculations. Set as a threshold for the maximum error (element-wise) in the density matrix. NOTE: should be below SCF convergence criteria

Integration Methods: Complex Contour vs Real-Axis

For hands-on comparison of gauNEGF integration approaches, see examples/IntegralDemo.ipynb – a step-by-step notebook designed to run on a compute node and illustrate the trade-offs between complex contour integration and real-axis energy integration.

Workflow: Tuning Convergence

Step 1: Start with defaults.

Most systems converge with factory settings. Run SCF and check the convergence history.

Step 2: If SCF oscillates or diverges:

  • Tighten mixing to lower value: negf.SCF(conv=1e-3, damping=0.005)

  • Adjust Pulay mixing value if unstable: negf.updatePulay(9)

  • Check that contacts are physically reasonable (see Choosing a Contact Type)

Step 3: If SCF is very slow:

  • Use two-phase approach: higher mixing (0.1) then lower (0.01)

  • Increase ETA in initial runs: negf.setContact1D([[1,2],[5,6]], eta=1e-3)

  • Use closed shell spin for initial runs, then add spin degrees of freedom later

Step 4: If Fermi search fails or gives non-physical electrons:

  • Turn on fermi search in initial runs - fermi energy setpoint may be near orbital energies

  • Explicitly set fermiMethod in setVoltage: negf.setVoltage(0.0, fermiMethod='muller')

  • Add a finite temperature to smooth out integration: negf.setContact1D([[1,2],[5,6]], T=300)

  • Otherwise revert back to bisection (fermiMethod='bisect') if all else fails

See Also