# Parameters

This page explains the driver knobs that most users will actually touch. It is
not a replacement for source docstrings; it is a map from physical intent to the
keyword names used by the code.

The safest first run is to leave defaults alone and change only `densities`,
`temperature`, and `out_dir` or `ir_file`. Grid, SCF, and Davidson controls are
there for convergence studies, not for making a difficult point look nicer.

(parameters-physical-inputs)=
## Physical inputs

| Keyword | Used by | Meaning |
| --- | --- | --- |
| `densities` | all drivers | Spin-summed carrier density in $\mathrm{cm}^{-3}$, or `"default"` for the built-in scan. |
| `temperature` | all drivers | Temperature in K. Drivers convert it to $\beta$ in $\mathrm{Hartree}^{-1}$. |
| `params` | all drivers | `STOParams` object containing the lattice constant, effective mass, dielectric constants, and phonon scale. |

The sparse-IR radial drivers use atomic units internally:

$$
\varepsilon(k) = \frac{k^2}{2m_{\mathrm{eff}}},
\qquad
n = \frac{k_{\mathrm{F}}^3}{3\pi^2}.
$$

`TakadaProjection` is the exception: its projected dense formulas use
eV/Angstrom units and the dimensionless variable
$x = \xi / E_{\mathrm{F}}$.

For phonon dispersion, `omega_t_disp_cm_a2` is the legacy single-pole
linear-frequency TO dispersion.  Multipole phonons use the separate opt-in
`phonon_to_omega2_disp_cm2_a2` field for TO squared-frequency dispersion; LO
zeros stay fixed and the q-independent multipole baseline is unchanged when
that field is empty.  For multipole modes that need a finite-q regularization,
`phonon_to_omega2_cap_cm2` supplies optional squared-frequency caps while
preserving the small-q slope.

(parameters-sparse-ir-caches)=
## Sparse-IR and caches

| Keyword | Default | Meaning |
| --- | --- | --- |
| `lamb` | `1.0e9` | Sparse-IR cutoff $\Lambda = \beta \omega_{\mathrm{max}}$. |
| `ir_tol` | `1.0e-14` | Sparse-IR basis tolerance. |
| `ir_file` | `None` | Optional HDF5 cache path for sparse-IR arrays. |
| `save_ir` | `True` | Save a generated IR cache. |
| `cache_transforms` | `True` | Precontract common transform matrices for repeated use. |

Use a separate cache per temperature and `lamb` value. {ref}`Example 08
<example-08>` does this under its output directory because a temperature scan
needs multiple IR grids.

(parameters-momentum-grids)=
## Momentum grids

| Keyword | Default | Meaning |
| --- | --- | --- |
| `nq` | `500` | Target size of the q grid. |
| `n_2kf_min` | `101` | Minimum local resolution near the Kohn feature around $2k_{\mathrm{F}}$. |
| `kgrid_n_left`, `kgrid_n_right` | `200`, `200` | Active k-grid resolution around the Fermi surface. |
| `kgrid_n_shell_min`, `kgrid_n_shell_max` | `50`, `5000` | Bounds for the Fermi-shell portion of the k grid. |
| `kmax_factor`, `kmax_lo_factor`, `qmax_factor` | `4.0`, `2.0`, `2.0` | Domain-size factors used to cover radial convolutions. |

```{figure} _static/kq_grid_schematic.png
:alt: Actual active k and q grid point distributions generated by migdal.grid for a medium-density example.
:width: 100%

This representative grid is generated directly from `migdal.grid` for
$n=10^{20}\,\mathrm{cm}^{-3}$ and $T=1\,\mathrm{K}$, with axes normalized by
$k_{\mathrm{F}}$. With the default point budgets this setup gives $N_k=566$ and
$N_q=500$; each rug mark is an actual grid point. The active $k$ grid
concentrates points in the narrow thermal shell around $k_{\mathrm{F}}$, which is why the
figure includes a zoom inset. The $q$ grid protects the region around $2k_{\mathrm{F}}$,
where the Lindhard polarization has its Kohn-feature structure, and then
extends far enough to cover the radial convolution domain. The detailed
Lindhard construction and RPA sign convention are explained in
{ref}`fixed-W0 polarization <theory-fixed-w0-polarization>` and
{ref}`the RPA sign convention <theory-rpa-sign-convention>`.
```

If a smoke run fails its particle-number check, first increase the grid. Relax
`n0_check_atol` only when you deliberately want a control-flow test rather than
a physics result.

(parameters-interaction-diagonal-averages)=
## Interaction and diagonal cell averages

| Keyword | Default / choices | Meaning |
| --- | --- | --- |
| `q_interp_mode` | **`"q_singular"`** \| `"legacy"` | Default `"q_singular"` splits the Coulomb-like $A/q^2$ head before radial integration; this is the production path for long-range interactions and requires diagonal cell averages. `"legacy"` keeps the older piecewise-linear $W(q)$ primitive, mainly for regression checks, old-result comparison, or isolating interpolation effects. |
| `diag_average` | **`"auto"`** \| `1` \| `0` | Default `"auto"` turns diagonal cell averages on when `q_interp_mode="q_singular"` requires them; in legacy mode it follows the historical no-truncation rule. Use `1` to force averages and `0` only for controlled legacy or truncated diagnostics; `q_singular` rejects disabled averages. |
| `diag_ncell` | `12` | Quadrature cells for diagonal averages when a quadrature path is used. |
| `diag_average_mode` | **`"auto"`** \| `"analytic"` \| `"gauss"` | Default `"auto"` resolves to the analytic diagonal-cell formula for `q_singular` primitives and to Gauss quadrature otherwise. Use `"analytic"` explicitly for `q_singular` backend checks; use `"gauss"` for quadrature comparisons. |
| `pi0_mode` | **`"finite_T"`** \| `"0K"` \| `"GG"` | Default `"finite_T"` builds fixed $W_0$ with the finite-temperature Lindhard polarization. `"0K"` uses the zero-temperature Lindhard formula, while `"GG"` builds the bubble numerically from $G_0(\tau)G_0(\beta-\tau)$; this option is only for `G0W0` and `GW0` because `ScGW` updates $\Pi$ self-consistently. |
| `denom_policy` | **`"sign_regularize"`** \| `"legacy_clip"` \| `"fail"` \| `"none"` | Default `"sign_regularize"` only repairs denominators smaller than `denom_min`, preserving the local real sign or complex phase when possible. `"fail"` raises on such rows, `"legacy_clip"` replaces small denominators by a positive floor, and `"none"` leaves the denominator untouched. |
| `denom_min` | `1.0e-10` | Minimum denominator scale used by regularizing policies. |
| `q_singular_head_policy` | **`"pi_head"`** \| `"fit_w"` | Default `"pi_head"` estimates the screened low-q head from the analytic polarization head. `"fit_w"` instead fits $q^2 W$ from sampled low-q rows and is mainly a diagnostic for the singular-head construction. |

In `q_singular` mode, diagonal cell averages are mathematically required for
the exact diagonal radial block. The average changes only that self-cell
quadrature block; it does not change the interaction definition. The table
lists public driver choices; a lower-level `"provided"` head policy exists for
callers that supply their own singular coefficient, but the public radial
drivers reject it.

(parameters-normal-state-scf)=
## Normal-state SCF controls

`GW0` solves `G` self-consistently with fixed `W0`. `ScGW` solves `G`, rebuilds
the polarization bubble, and updates `W`.

| Keyword | Common default / choices | Meaning |
| --- | --- | --- |
| `scf_conv_tol` | `1.0e-6` | Max-norm tolerance for the gauge-invariant $\Sigma-\mu$ residual. |
| `scf_max_cycle` | `300` | Maximum normal-state SCF cycles. |
| `scf_damp` | `0.98` | SCF damping/mixing control. `0.98` means mixing 2% new vector per cycle. |
| `scf_diis_space` | `8` | DIIS history size. |
| `scf_diis_start_cycle` | `0` | First cycle where DIIS may be used. |
| `scf_continuation_max_dex` | `1.0` | Maximum density-step size for restart-enabled continuation scans. |
| `scf_mu_bracket` | **`"nearest_positive"`** \| `"extreme"` | Default `"nearest_positive"` chooses the closest positive-slope bracket around the current chemical-potential estimate. `"extreme"` uses the outer scan bracket and is a fallback for difficult density solves, but it is less local. |
| `scf_fs_pin` | `True` | Pin the Fermi-surface self-energy gauge when enabled. |
| `scf_high_freq_density` | `True` | Use the high-frequency corrected density formula in the SCF chemical-potential solve. Set to `False` only for direct $-2G(\beta^-)$ endpoint comparisons. |
| `allow_unconverged` | `False` | Permit an unconverged SCF row to continue to the gap solve. |

Disk checkpoints for the normal-state SCF loop are available through the Python
driver API for `GW0` and `ScGW`:

| Keyword | Default | Meaning |
| --- | --- | --- |
| `scf_chkfile` | `None` | HDF5 path for writing the latest SCF cycle state. Under MPI, only rank 0 writes. |
| `scf_restart_chkfile` | `None` | HDF5 path to load as the initial SCF guess for a later `kernel()` or `scan()` call. |

The checkpoint stores the restart seed for the normal-state SCF loop: `sigma`,
`mu`, the optional Fermi-surface pin shift, the active k grid, the Matsubara
grid, and basic diagnostics. It does not serialize DIIS history, the gap solve,
or the derived scGW `W`/polarization tables. Use it to resume the same
GW0/scGW method on the same temperature and grid after an interruption. In a
density scan with `scan(restart=True)`, the file can seed the first point; once
the scan has an in-memory continuation seed, that seed takes precedence.

`ScGW` also has polarization and tail controls. Keep these defaults for
tutorial runs unless you are doing a specific stability audit.

| Keyword | Default / choices | Meaning |
| --- | --- | --- |
| `n_tail` | `100` | Minimum number of passive k points in the separate polarization integration tail. |
| `sigma_tail_policy` | **`"exchange_static"`** \| `"exchange_t0"` \| `"zero"` | Default `"exchange_static"` fills the passive tail with a finite-temperature static-exchange estimate. `"exchange_t0"` uses the $T=0$ exchange expression, while `"zero"` leaves the passive tail empty apart from the gauge shift. |
| `pi_imag_policy` | **`"warn"`** \| `"fail"` | Default `"warn"` logs imaginary-part diagnostics in the polarization bubble and continues. `"fail"` turns the same diagnostic into an exception for stricter audits. |
| `pi_positive_policy` | **`"warn"`** \| `"fail"` | Default `"warn"` reports positive real entries of $\Pi$ above tolerance and continues. `"fail"` stops the row when that sign diagnostic is violated. |
| `pi_positive_action` | **`"keep"`** \| `"zero_small"` | Default `"keep"` leaves small positive $\Pi$ entries unchanged after diagnostics. `"zero_small"` zeros only positive entries below `pi_positive_tol`. |
| `pi_low_q_policy` | **`"asymptotic"`** \| `"none"` | Default `"asymptotic"` continues the low-q polarization using the expected small-q behavior before building $W$. `"none"` uses the sampled values directly. |
| `q_low_factor`, `q_static_low_factor` | `2.0e-2`, `None` | Low-q continuation thresholds in units of $k_{\mathrm{F}}$. `q_static_low_factor=None` reuses `q_low_factor`. |
| `allow_no_pi_tail` | `False` | Permit a run without a passive polarization tail. This is mainly for controlled tests, not production-style scGW scans. |

With the default `pi_low_q_policy="asymptotic"`, finite bosonic frequencies are
continued as $\Pi(q,\mathrm{i}\nu_n)\propto q^2$ below
$q_{\mathrm{low}} k_{\mathrm{F}}$, where $q_{\mathrm{low}}$ is
`q_low_factor`; the static component is held at its reference low-q value below
$q_{\mathrm{static,low}} k_{\mathrm{F}}$, with $q_{\mathrm{static,low}}$ set by
`q_static_low_factor`. The detailed formulas are in
{ref}`scGW low-q continuation <theory-scgw-low-q-continuation>`.

The table above lists driver constructor defaults. Some scripts in the
{ref}`recommended example order <examples-recommended-order>` choose more
conservative defaults for long scans, especially continuation step sizes and
scGW cycle limits. Use `python examples/<name>/run.py --help` when you need the
script-level defaults.

Advanced debug-only gap options `check_precond` and `check_precond_nsamples` are
available through the Python driver kwargs but are not part of the common package
CLI. The package CLI exposes `scf_high_freq_density` only indirectly for scGW:
`--legacy-scf-density` switches scGW to the direct endpoint density convention.
The package CLI `--restart` option controls in-memory scan continuation; disk
SCF checkpoint paths are currently Python driver keywords.

(parameters-gap-solver)=
## Gap solver

The radial gap problem is solved by PySCF's Davidson solver. Driver keyword
arguments are passed through to `GapConfig`.

| Keyword | Default / choices | Meaning |
| --- | --- | --- |
| `truncate` | `False` | Restrict the active Matsubara window. |
| `wcut` | driver-derived | Frequency cutoff when truncation is enabled. |
| `precond` | **`"even_diag"`** \| `"ones"` | Default `"even_diag"` uses the even-frequency diagonal estimate as the Davidson preconditioner. `"ones"` is an identity preconditioner, useful mostly for debugging whether the preconditioner is affecting convergence. |
| `cache` | **`"auto"`** \| `"off"` | Default `"auto"` materializes radial matvec geometry when the memory policy allows it. `"off"` streams the geometry instead, which can be slower but is useful for memory audits. |
| `davidson_tol` | `1.0e-6` | Davidson convergence tolerance. |
| `davidson_max_cycle` | `300` | Maximum Davidson cycles. |
| `davidson_max_space` | `20` | Davidson subspace limit. |
| `nroots` | `1` | Number of Davidson roots requested from the gap solver. Keep `1` unless you are explicitly comparing leading and subleading gap channels. |
| `return_gap_function` | `False` | Return the full scaled gap function for diagnostics. |

The reported pairing strength is

$$
\lambda = -\operatorname{Re}(\eta_{\mathrm{selected}}),
$$

where $\eta_{\mathrm{selected}}$ is the selected raw Davidson eigenvalue.

(parameters-takada-controls)=
## Takada projection controls

`TakadaProjection` is separate from the sparse-IR radial drivers. Its main
controls are the dense angular grid, the dimensionless energy grid, and the
kernel symmetry check.

| Keyword | Default | Meaning |
| --- | --- | --- |
| `n_q`, `n_theta` | `20`, `12` | Quadrature sizes for the projected dense kernel. |
| `x_core`, `x_max` | `1.0e-5`, `1.0e3` | Inner and outer limits for the dimensionless energy grid. |
| `n_neg`, `n_pos` | `48`, `52` | Occupied and unoccupied energy-grid counts. |
| `max_symmetry_error` | `1.0e-10` | Maximum allowed projected-kernel symmetry error. |