Public API#

This page lists the public driver surface. It is intentionally short: the drivers are the supported user API, while internal radial kernels are implementation modules. The main convolution formulas are summarized in Radial convolution and source docstrings.

The stable user-facing surface is the driver layer: the top-level drivers G0W0, GW0, ScGW, and TakadaProjection; the model parameter object migdal.model.STOParams; and the result rows returned by those drivers. The radial kernels, SCF helpers, and sparse-IR cache builders are implementation modules unless a page explicitly describes them as a command-line tool.

Driver pattern#

The main drivers follow a PySCF-like pattern:

from migdal import G0W0

drv = G0W0(densities=[1.0e20], temperature=1.0, verbose=4)
row = drv.kernel()
print(row.lam, row.gap_converged)

Use kernel() for one density point, scan() for a density list, scan_temp() for a fixed-density temperature list, run() for set(...).scan(...) style chaining, and write(path) for CSV output after a run.

For keyword meanings and defaults, see Physical inputs and the later parameter tables. For result fields and CSV interpretation, see In-memory rows and CSV columns.

Main drivers#

G0W0: fixed G0 and fixed W0. It supports pi0_mode="finite_T", "0K", or "GG".
GW0: self-consistent normal-state G with fixed W0. It adds SCF controls such as scf_conv_tol, scf_damp, and allow_unconverged.
ScGW: self-consistent normal-state G and W. It adds polarization and tail controls such as n_tail, pi_imag_policy, and sigma_tail_policy.
TakadaProjection: dense projected Takada comparison. It uses eV/Angstrom units internally, unlike the sparse-IR radial drivers.

Common sparse-IR driver keywords include:

densities        density list in cm^-3, or "default"
temperature      temperature in K
params           STOParams object, or the built-in STO-like defaults
lamb             sparse-IR lambda cutoff parameter
ir_file          optional sparse-IR cache path
nq               q-grid size target
q_interp_mode    "q_singular" or "legacy"
diag_average     "auto", 0, or 1
max_memory       per-rank memory limit in MB
verbose          PySCF-style logging level

The sparse-IR drivers also accept gap-solver keywords through the shared GapConfig, such as davidson_tol, davidson_max_cycle, precond, and return_gap_function.

Common methods:

set(**kwargs)    update driver attributes and return self
build()          build or load sparse-IR data
kernel(n_cm3)    run one density point
scan(densities)  run a density scan
scan_temp(temperatures, n_cm3)  run a fixed-density temperature scan
run(...)         apply optional updates, then scan
write(path)      write CSV output after kernel/scan

Model parameters#

STOParams stores the SrTiO3-like one-band model constants used by the public drivers.

from migdal.model import STOParams

Field	Meaning
`a_ang`	Cubic lattice constant in Angstrom.
`m_eff`	Effective mass in electron-mass units.
`eps_inf`, `eps_0`	High-frequency and static dielectric constants.
`omega_t0_cm`	Zone-center transverse optical phonon energy in \(\mathrm{cm}^{-1}\).
`omega_t_disp_cm_a2`	Optional single-pole linear-frequency transverse-mode dispersion coefficient.
`phonon_to_poles_cm`, `phonon_lo_zeros_cm`	Optional multipole phonon representation in \(\mathrm{cm}^{-1}\).
`phonon_to_omega2_disp_cm2_a2`	Optional multipole TO squared-frequency dispersion coefficients.
`phonon_to_omega2_cap_cm2`	Optional multipole TO squared-frequency caps; use `math.inf` for uncapped modes.

Derived properties such as a_bohr, band_a_ha_bohr2, omega_t_ha, and omega_l_ha handle unit conversion for the radial drivers. Grid sizing uses phonon_grid_ha(params), which equals omega_l_ha for the single-pole model and the largest supplied TO/LO feature for a multipole model.

When both multipole tuples are provided, they must have the same positive length and satisfy the generalized Lyddane-Sachs-Teller endpoint condition \(\prod_j(\omega_{\mathrm{LO},j}/\omega_{\mathrm{TO},j})^2 = \epsilon_0/\epsilon_\infty\). The multipole representation is q-independent unless phonon_to_omega2_disp_cm2_a2 is supplied. Finite phonon_to_omega2_cap_cm2 entries replace the uncapped parabola by a smooth large-q saturation that keeps the same small-q slope and stays below the matching LO zero. The legacy omega_t_disp_cm_a2 field cannot be combined with multipole phonons.

Result conventions#

G0W0, GW0, and ScGW return PointResult rows. The key fields are:

Field	Meaning
`n_cm3`	Requested spin-summed density in \(\mathrm{cm}^{-3}\).
`temperature_K`	Temperature used for this row in K.
`lam`	Reported pairing eigenvalue.
`gap_converged`	Davidson gap-solver convergence flag.
`scf_converged`	Normal-state SCF flag, or `None` for `G0W0`.
`mu`, `mu0`	Chemical potentials in Hartree; CSV writes `mu_Ha` and `mu0_Ha`.
`n_bohr3`, `n_re`	Requested and reconstructed densities in \(\mathrm{Bohr}^{-3}\).
`nk`, `nq`	Active momentum-grid sizes.
`gap`	`GapResult` with eigenvalue, convergence, cycles, matvecs, and active-frequency diagnostics.
`denom`	RPA denominator diagnostics for the screened interaction.

TakadaProjection returns TakadaResult rows with eps_F_eV, k_F_A (\(\mathrm{Angstrom}^{-1}\)), and a kernel symmetry diagnostic. Its text output writes the same momentum as k_F_Angstrom_inv.

Field	Meaning
`n_cm3`	Requested density in \(\mathrm{cm}^{-3}\).
`lam`	Largest dense projected pairing eigenvalue.
`eps_F_eV`	Fermi energy in eV.
`k_F_A`	Fermi momentum in \(\mathrm{Angstrom}^{-1}\).
`symmetry_error`	Maximum dense-kernel symmetry error after symmetrization checks.

Minimal program#

from migdal import G0W0

drv = G0W0(
    densities=[1.0e20, 3.0e19],
    temperature=1.0,
    verbose=4,
)
rows = drv.scan()
drv.write("/tmp/migdal-g0w0.csv")

for row in rows:
    print(row.n_cm3, row.lam, row.gap_converged)

For GW0 and scGW, also inspect row.scf_converged before interpreting row.lam.