Workflows#

This page gives a runnable path through the code. Start small, inspect the output, and only then spend time on dense curves.

A useful mental model is:

Step	Question	Artifact to trust first
Environment check	Do the IR transforms and kernels run?	Small serial output directory.
Smoke radial point	Does the radial control flow complete?	CSV plus convergence flags.
Density curve	Is the physical trend stable across density?	CSV; figures for visual inspection.
SCF comparison	Does self-consistency change the result?	`scf_converged`, `scf_res_sigma`, then `lambda`.
Tc scan	Where does \(\lambda(T)\) cross 1?	`lambda_vs_temperature.csv`, then `tc_vs_density.csv`.

Choose a method#

Method	Use it when	First example
`G0W0`	You want a fixed noninteracting `G0` and fixed screened `W0`.	03_g0w0_takada_curve
`GW0`	You want a self-consistent normal-state `G` with fixed `W0`.	04_g0w0_gw0_scgw_curve
`ScGW`	You want both `G` and `W` updated in the normal-state loop.	04_g0w0_gw0_scgw_curve
`TakadaProjection`	You want the dense projected comparison in eV/Angstrom units.	03_g0w0_takada_curve

For a new setup, verify G0W0 first. It exercises the radial interaction and gap solver without adding the normal-state SCF loop.

1. Check the environment#

Run the serial sparse-IR round trip:

python examples/01_ir_noninteracting_gf/run.py --out-dir /tmp/migdal-example01

Success means the sparse-IR transforms work for a known

\[ G_0(k,\mathrm{i}\omega_n)= \frac{1}{\mathrm{i}\omega_n-(\varepsilon_k-\mu)}. \]

It does not validate a production radial calculation.

2. Run a small radial point#

Use the quickstart smoke command:

mpirun -n 2 python examples/03_g0w0_takada_curve/run.py \
  --n-density 2 \
  --nq 40 \
  --k-left 20 \
  --k-right 20 \
  --k-shell-min 8 \
  --k-shell-max 80 \
  --out-dir /tmp/migdal-example03-smoke

This is a control-flow check. If it writes CSV files and figures, move to the default grids before interpreting the numbers.

3. Compare pairing-eigenvalue curves#

Run Example 03 for the first full comparison:

mpirun -n 2 python examples/03_g0w0_takada_curve/run.py \
  --out-dir /tmp/migdal-example03

Read the text report first, then the CSV files. The figure gives the trend; the CSV gives the data you should cite.

4. Add self-consistency#

Run Example 04 when the fixed-W0 curve is understood:

mpirun -n 2 python examples/04_g0w0_gw0_scgw_curve/run.py \
  --out-dir /tmp/migdal-example04

For every GW0 or scGW row, check scf_converged before using lambda. Some tutorial scripts keep unconverged rows so the plot can show where the method becomes difficult.

5. Inspect interactions and gap functions#

Use Example 06 and Example 07 when a curve looks surprising:

mpirun -n 2 python examples/06_g0w0_w_gap_diagnostics/run.py \
  --out-dir /tmp/migdal-example06

mpirun -n 2 python examples/07_gw0_scgw_w_gap_diagnostics/run.py \
  --out-dir /tmp/migdal-example07

These scripts write q-averaged interaction data and gap-function lines. They are better for diagnosis than for a first tutorial.

6. Estimate Tc#

Example 08 uses same-density cooling restarts for GW0/scGW and interpolates the crossing:

OMP_NUM_THREADS=2 mpirun -n 2 -bind-to core:2 -map-by core:2 \
  python examples/08_tc_vs_density/run.py \
  --out-dir /tmp/migdal-example08

Use lambda_vs_temperature.csv to audit which rows entered the Tc interpolation, then use tc_vs_density.csv for the final summary.

The cooling restart is deliberately more careful than copying a previous self-energy array. A converged GW0/scGW row stores the gauge-invariant combination \(X=\Sigma-\mu\), remaps its sparse-IR coefficients to the next temperature, rescales the IR normalization, interpolates the k grid when needed, and then re-applies the Fermi-surface pin if that gauge is enabled. This requires the same sparse-IR lambda, the same fermionic nw, and matching reduced Matsubara points. If a restarted row fails and retry is enabled, the script tries that temperature once more from a cold start and records the event in cooling_restart_log.csv.

For interrupted same-temperature GW0/scGW jobs, the Python driver keywords scf_chkfile and scf_restart_chkfile provide a lighter disk checkpoint for the normal-state SCF seed. This is separate from the temperature-remapped restart above: the disk checkpoint is intended to resume the same method, temperature, and grid, not to bridge a cooling step.

Reading order after a run#

Text report: what was asked and which settings were used.
CSV: machine-readable data and convergence flags.
Figure: visual trend and obvious outliers.
CSV columns and quick trust checklist: field meanings and row-level sanity checks.
Troubleshooting: convergence, grid, cache, and denominator diagnostics when a row fails the checklist.