Command-line options for `lmf` / `lmfa` / `lmchk` (and friends)

Cmdline argument structure (the minimum)

The Fortran binaries accept four token forms. Anything else aborts at startup with a one-line hint. All parsing lives in SRC/subroutines/m_cmdopt_registry.f90 (option table + typo / retired-syntax check) and SRC/subroutines/m_toml_override.f90 (TOML override application).

Form	Meaning	Where it goes
`<sname>`	positional, the ctrlg file extension	`m_ext::sname`
`ctrlg.<sname>.toml`	positional, the full TOML filename (e.g. after TAB completion)	`m_ext::sname`
`--ctrlg:<dotted.path>=<value>`	runtime TOML override (applied in memory; file untouched)	`m_toml_override`
`--<flag>`	registered cmdopt0 — presence bool	`c0_<flag>` in `m_cmdopt_registry`
`--<flag>=<value>`	registered cmdopt2 — typed value	`c2_<flag>` in `m_cmdopt_registry`

The two positional forms are equivalent: lmf nio and lmf ctrlg.nio.toml both end up with sname='nio'. m_ext_init rejects anything in between -- ctrlg.nio (no .toml suffix) and ctrl.nio (the legacy text format) abort at startup with a hint pointing at the two canonical forms (and at Legacy2toml.py for the latter).

A single argument-validation pass runs at startup (m_cmdopt_registry::validate_arglist, called from m_args::m_setargs). It aborts on:

any --<word> / -<word> that is not in the cmdopt0 table;
any --<word>=<value> whose bare prefix is not in the cmdopt2 table;
any of the retired forms below (with a per-form migration hint).

Adding a new option is one line each in m_cmdopt_registry.f90: declare c0_<name> (or c2_<name>) and add a matching call set0('--<name>', c0_<name>, narg, arglist) (resp. get2('--<name>', outs, narg, arglist)) in the relevant load_*_registry subroutine. The typo-detection table is built as a side effect — there is no parallel "known-flag list" to keep in sync.

This page is the catalogue of registered options. It is regenerated by searching grep -E "call set0\('--|get2\('--" SRC/subroutines/m_cmdopt_registry.f90, so any flag added/removed in the source flips here automatically.

How to read the table

Flags are cmdopt0 (no value): write them verbatim, e.g. --writeham.
Key=value are cmdopt2: always include =, e.g. --jobgw=1. Unrecognised --<word>=<value> aborts with a typo hint.
TOML override lives in a different namespace: --ctrlg:<dotted.path>=<value> (handled in m_toml_override.f90). It does not appear in this table.
Most flags work in lmf (and lmf --jobgw=… which acts as the GW driver). lmfa / lmchk honour the few that apply to the atomic-program / structure-check phases — they are explicitly marked below.

Retired (now abort with migration hint)

These used to be cmdopt0 / cmdopt2 shortcuts that overrode a TOML key directly. They are gone and any of these on the cmdline triggers an abort + one-line hint pointing at the canonical --ctrlg:<path>=<value> form.

Retired form	Replacement
`--pr=N` / `--pr N` / `-pr N`	`--ctrlg:verbose=N`
`--time=N[,M]`	`--ctrlg:time=[N,M]`
`--phispinsym` (cmdline flag)	`--ctrlg:ham.phispinsym=true`
`-v<name>=<value>` (legacy `%const`)	`--ctrlg:<dotted.path>=<value>`
`-v[<path>]=<value>` (older bracketed)	`--ctrlg:<dotted.path>=<value>`
`--[<path>]=<value>` (intermediate)	`--ctrlg:<dotted.path>=<value>`
`--<a.b.c>=<value>` (intermediate dotted)	`--ctrlg:<a.b.c>=<value>`
`--toml.<path>=<value>` (intermediate)	`--ctrlg:<path>=<value>`
`-emin=` / `-emax=` / `-ndos=` (single dash, legacy)	`--emin=` / `--emax=` / `--ndos=`
`-EfermiShifteV=` (single dash, legacy)	`--EfermiShifteV=`
`--terse` / `-terse` (lmchk overlap-table)	dropped — use `--ctrlg:verbose=N` (N≤40)
`--no-iactiv` (legacy lmfa flag)	dropped — silently ignored before, now aborts

Common (lmf / lmfa / lmchk)

Option	Type	Effect	Used in
`--help`	flag	Print Usage banner + link to this page, then exit	`m_ext.f90`
`--debug`	flag	Global debug printout	many
`--show_time`	flag	Print `hambl` timing	`hambl.f90:41`
`--fullstdo`	flag	All ranks write to stdout (default: master only)	`m_MPItk.f90`

SCF / electronic structure (lmf core)

Option	Type	Effect	Used in
`--etot`	flag	Total-energy diagnostics on	`m_lmfinit.f90:652`
`--vbmonly`	flag	Print approximate VBM/CBM relative to vacuum and exit	`main_lmf.f90:115`
`--getq`	flag	Output channel-resolved occupation Q	`main_lmf.f90:119`
`--v0fix`	flag	Freeze the spherical potential V₀ during SCF	`m_lmfinit.f90:186`
`--noinv`	flag	Disable inversion symmetry in BZ sampling	`m_lmfinit.f90:541`
`--nosym`	flag	Disable spatial symmetry (forces no-symmetry SCF)	`m_lmfinit.f90:537`
`--nosymdm`	flag	No symmetry on the LDA+U density matrix	various
`--shorten`	flag	Shorten lattice vectors (`lmchk` action)	`lmaux.f90:75`
`--slat`	flag	Print Ewald shorted lattice (`lmchk`)	`lmaux.f90:96`
`--afsym`	flag	Use AF (Shubnikov) symmetry; halves the BZ sampling	`m_qplist.f90`
`--onesp`	flag	Force `nspxx=1` even when `nsp=2`	`m_qplist.f90:94`
`--avoidgamma`	flag	Skip Γ-point in q sampling	various

Quit-points (debugging / staged runs)

Option	Effect
`--quit=show`	Stop after `--show` echo
`--quit=ham`	Stop after `m_hamindex_init`
`--quit=mkpot`	Stop after `m_mkpot` (potential build)
`--quit=dmat`	Stop after first density-matrix construction
`--quit=band`	Stop after the band loop (no density update)
`--quitecore`	Stop after core treatment

Bands / DOS / Fermi surface

Option	Type	Effect	Used in
`--band`	flag	Compute eigenvalues along `syml.<sname>` (band plot)	`m_lmfinit.f90:661`
`--fullmesh`	flag	Full BZ mesh; used by Fermi surface / PROCAR / boltztrap	`m_qplist.f90:54`
`--fermisurface`	flag	Fermi surface mode (Xcrysden `.xsf`)	`m_bndfp.f90:128`
`--mkprocar`	flag	Emit PROCAR (atomic/orbital projected weights)	`m_bndfp.f90:185`
`--writepdos`	flag	Write `pdos.*` files	`main_lmf.f90:64`
`--dos` / `--pdos` / `--tdos`	flag	DOS / partial DOS / total DOS	`m_lmfinit.f90:264`
`--tdostetf`	flag	Disable tetrahedron for `--tdos` (use Methfessel–Paxton instead)	`m_bndfp.f90:283`
`--wdsawada`	flag	Sawada-style simple DOS output, then exit	`main_lmf.f90:71`
`--eigen-at-k`	flag	Write eigenvalues at user-supplied k	`m_qplist.f90:125`
`--writeeigen`	flag	Same as `--eigen-at-k` (alias)	`m_bndfp.f90:129`
`--allband`	flag	Output all bands at every k	`m_bandcal.f90`
`--boltztrap`	flag	Write `BoltzTraP` input on a full mesh	`m_bndfp.f90:224`
`--cls`	flag	Core-level spectroscopy weights (see `m_clsmode.f90`)	`m_bndfp.f90:157`
`--corehole`	flag	Core-hole calculation	various
`--gs`	flag	Use plain Gram–Schmidt (not the modified variant)	various

GW driver and friends (`lmf --jobgw=…`, `gwsc` internals)

Option	Type	Effect	Used in
`--jobgw=0`	kv	`lmf` writes `__jobgw0` data for `qg4gw`	`main_lmf.f90:47`
`--jobgw=1`	kv	`lmf` produces the GW input (replaces legacy `lmfgw-MPIK`)	`main_lmf.f90:47`
`--writeham`	flag	Write `HamiltonianPMT.*` for downstream tools (mlo / writeham)	`main_lmf.f90:110`
`--writev0`	flag	Write V₀ (spherical part) on the radial mesh	`locpot.f90:354`
`--writesene`	flag	Write self-energy file `__sene.*` (debug)	`m_bndfp.f90`
`--wsig_fbz`	flag	Write `sigm` reshaped to the full BZ	`m_bndfp.f90:175`
`--use_sigm_fbz`	flag	Read `sigm_fbz` instead of the regular `sigm.*`	`m_bndfp.f90`
`--readQforGW`	flag	Read user-supplied q-vectors for `hsfp0_sc` / GW	`m_q0p.f90:168`
`--n1n2n3eps`	flag	Honour `n1n2n3eps` mesh in `qg4gw`/`mkqg` for ε/χ⁺⁻	`mkqg.f90`
`--job=N`	kv	Stage selector in `hbasfp0`, `hvccfp0`, `hsfp0_sc`, `qg4gw`, `heftet`. Range is per-binary; see `lmf-gw-driver-stages` in `gwsc.md`.	many
`--ntqxx`	flag	Limit number of QP states (debug)	various
`--cutuu=`	kv	Cut-off on `vc` matrix elements	`m_hsfp0_sc.f90`
`--Wtype=`	kv	Select W type (RPA, eps0, …) in `hsfp0_sc`	`m_hsfp0_sc.f90`
`--nww=`	kv	Number of frequency points in `hrcxq` / `hsfp0_sc`	`m_hsfp0_sc.f90`
`--nk=`	kv	k-parallel group size (overrides default of `mpi_size`)	`m_mpi.f90`
`--nb=`	kv	(Deprecated; b-parallel was removed.) Tolerated and ignored.	`main_hrcxq.f90`
`--keepwv`	flag	Keep W in memory for screening (auto-on with `--gpu`)	`hgw_combined`
`--qibzonly`	flag	Compute only IBZ q-points (skip auxiliary q₀)	various
`--geteta`	flag	Get η damping diagnostics for ε(q,ω)	various
`--interbandonly` / `--intrabandonly`	flag	Limit interband / intraband transitions in ε	various
`--testso`	flag	SO sanity test path	various
`--tetraw` / `--tetwtk`	flag	Tetrahedron-weight diagnostics	various

MLO / Wannier-replacement (`job_mlo`, `job_mloW`, `job_mlo_soc`)

Option	Type	Effect	Used in
`--mlo`	flag	MLO mode: emit `__cmlo.data` / `__cmlo.info` from the GW input	`m_HamPMT.f90:188`
`--cmlo`	flag	Use the MLO Hamiltonian path (`main_lmfham2`)	`main_lmfham2.f90:582`
`--mlog`	flag	MLO + GW combined output	various
`--mlo_ortho`	flag	Orthogonalize MLOs (no normalization)	`m_mlo_ham.f90`
`--mlo_orthonorm`	flag	Orthonormalize MLOs	`m_mlo_ham.f90`
`--mlo_diagnorm`	flag	Diagonal renormalization only	`m_mlo_ham.f90`
`--mlo_feb4`	flag	bcc Fe Fe-3d on-site `W` reference recipe (see `MLOsamples/README.md`)	`m_mlo_ham.f90`
`--mloahc`	flag	MLO + AHC (Anomalous Hall Conductivity)	various
`--AHCMAT`	flag	Write AHC matrix elements	various
`--UUMAT`	flag	Write `<u	u>` overlap matrix (debug)
`--dwnb=mlo` / `--dwnb=wan`	kv	Choose downfolding basis (MLO vs Wannier)	`m_procar.f90`
`--writedw`	flag	Default-on: write `dw` weights in `m_procar`	`m_procar.f90`
`--nowritedw`	flag	Suppress `dw` writing	`m_procar.f90`
`--socmatrix`	flag	Write SOC matrix (`__HamiltonianPMTsoc`)	`m_HamPMT.f90:109`
`--ahc`	flag	AHC variant	various

Density / potential I/O

Option	Type	Effect	Used in
`--density`	flag	Write smoothed density to `xsf` / file (see `m_bndfp.f90:340`)	`m_bndfp.f90:340`
`--wrhomt`	flag	Write true MT density `rhoMT.<ib>` (debug)	`locpot.f90:189`
`--wpotmt`	flag	Write true MT potential `vtrue.<ib>`	`locpot.f90:335`
`--vesatom`	flag	Output `lmfa` electrostatic potential	`freeat.f90:31`
`--vesdat`	flag	Write the per-rank electrostatic data	`locpot.f90:263`
`--espot`	flag	Electrostatic-potential calculation	`m_bndfp.f90`
`--estaticall`	flag	Output full electrostatic potential	`m_bndfp.f90`
`--eszero`	flag	Set Madelung correction to zero (diagnostic)	various
`--novxc`	flag	Skip XC contribution (debug)	`locpot.f90:391`

Structure / symmetry (`lmchk` actions)

Option	Type	Effect	Used in
`--getwsr`	flag	Compute touching-MT radii; used by `ctrlgenToml.py`	`lmaux.f90:120`
`--kchk`	flag	Check whether the k-mesh is compatible with the space group	`bzmesh.f90:120`
`--ylmc`	flag	Print `Ylm` analysis	various

SOC

Option	Type	Effect	Used in
`--socmatrix`	flag	(see MLO section)	`m_HamPMT.f90:109`
`--skiphammsoc`	flag	Don't add the SOC term to `hamm` (perturbation path)	`m_bandcal.f90`
`--ctrlg:ham.phispinsym=true`	TOML	Spin-averaged radial wfns (formerly `--phispinsym`); set via TOML override or in `[ham]` of `ctrlg.<sname>.toml`.	`m_toml_override.f90`

GPU / linear-algebra knobs

Option	Type	Effect	Used in
`--gpu`	flag	Take the GPU code path (auto-grabs `/tmp/gpu.lock`)	`InstallAll.py`, `m_*.f90`
`--use_gemmul8`	flag	Use the GEMMul8 Ozaki-scheme matmul kernel	various
`--modifiedGS`	flag	Modified Gram–Schmidt orthogonalisation	various
`--diag=default` / `--diag=tridiag` / `--diag=chefsi`	kv	Diagonaliser selector (LAPACK default, tridiag, ChebFSI)	various

Post-processing helpers (`hmlo_ovlppair`, eps tools)

Option	Type	Effect	Used in
`--sp1=` / `--sp2=`	kv	spin selectors in `hmlo_ovlppair`	`hmlo_ovlppair.f90:20`
`--emin=` / `--emax=` / `--ndos=`	kv	DOS energy window / resolution	various
`--EfermiShifteV=`	kv	Shift `EF` (eV) before DOS / spectrum	various

Diagnostic / debug-only flags

These exist for development and are unlikely to be useful in production runs. Behaviour is not guaranteed to be stable.

--debugbndfp, --debugpwmat, --debugsugw, --debugzmel, --zmel0, --normcheck, --showdmat, --x0test, --q2q1test, --cvK:, --skip_qvalcheck, --skipbstruxinit, --skipCPHI, --skipGS, --skiphammsoc, --skip1d / --skip2nd / --skip2ndd / --skip2ndp / --skip2nds, --skipd / --skipf / --skiplo (all currently dead code in m_HamPMT.f90), --wanatom.

Run-time TOML overrides (`--ctrlg:<path>=<value>`)

The only accepted override syntax is --ctrlg:<dotted.path>=<value>. Values are TOML-typed (bool lowercase true/false, strings quoted, arrays in [...]); bare identifiers are auto-quoted so shell quote-stripping is forgiving.

bash

lmf si --ctrlg:bz.nkabc=[8,8,8] --ctrlg:ham.scaledsigma=0.8
lmf si --ctrlg:ham.so=1 --ctrlg:ham.nspin=2          # SOC as perturbation
lmf si --ctrlg:ham.phispinsym=true                   # bool lowercase
lmf si --ctrlg:verbose=50 --ctrlg:time=[5,5]         # top-level keys
lmf si --ctrlg:spec.1.r=2.5                          # override SPEC[1].r
lmf si --ctrlg:symgrp=find                           # bare identifier auto-quoted

The path mirrors the TOML structure (section.key / section.<idx>.key for arrays-of-tables, 1-indexed). Applied overrides are logged on rank 0. See toml_migration for the full spec.

When this page goes stale

If the source has a flag this page doesn't list (or vice versa), trust the source. Refresh with:

bash

grep -rEoh "cmdopt[02]\('[-][^']+'" \
     SRC/subroutines/ SRC/main/ | sort -u

and reconcile by hand. We deliberately do not auto-generate this page because the categorical grouping and the prose notes are the value; a flat alphabetical dump is what grep already gives you.

Tab completion (bash)

InstallAll.py ships a bash-completion script that knows about both the cmdopt registry and the TOML override syntax. After installation:

lmf <TAB> (or lmfa, lmchk) -> offers every ctrlg.<sname>.toml in the current directory as the positional <sname>.
lmf nio --w<TAB> -> the cmdopt0/cmdopt2 names that start with --w (--writedw, --writeham, --writepdos, ...).
lmf nio --ctrlg:<TAB> (or any prefix like --ctrlg:bz.) -> the dotted-path keys that actually exist in the cwd's ctrlg.<sname>.toml. [[spec]] / [[site]] arrays expand into spec.1.r, spec.2.r, ... automatically.
Trailing space is suppressed for --ctrlg: and any cmdopt2 (so --ct<TAB> becomes --ctrlg: with the cursor still on the colon, ready for bz.nkabc=...).

The completion has two data sources, each with a different freshness:

Completion target	Source	When it updates
`--ctrlg:<dotted.path>`	the cwd's `ctrlg.<sname>.toml` parsed live by `python3` (tomllib) at every TAB	always reflects the on-disk TOML
`--<flag>` / `--<flag>=`	`BINDIR/ecalj_cmdopts.list` (dumped by `lmf --listcmdopt` during `InstallAll.py`)	refreshed on every `./InstallAll.py` run

The mapping mirrors the parser:

A ctrlg.*.toml key only appears as a completion if it really exists in that file — so a TAB-completed --ctrlg: path never triggers the "key not found in target section" abort from m_toml_override.
A --<flag> only appears if it is registered in m_cmdopt_registry::load_cmdopt0_registry / load_cmdopt2_registry — so a TAB-completed flag never triggers the "unknown option" abort from validate_arglist.

Both ~/bin/ecalj_complete.bash and ~/bin/ecalj_cmdopts.list are written by InstallAll.py; a guarded [ -f .../ecalj_complete.bash ] && source ... line is appended once to ~/.bashrc. To opt out, run InstallAll.py --no-bashrc; to disable later, delete the # >>> ecalj bash completion ... <<< block from ~/.bashrc.

The lmf --listcmdopt entry point (added together with the completion plumbing) dumps every registered cmdopt0 / cmdopt2 name on stdout, one per line, with a trailing = on cmdopt2 entries so the completion script can distinguish them from bare flags:

text

$ lmf --listcmdopt | head -5
--AHCMAT
--UUMAT
--afsym
--ahc
--allband
$ lmf --listcmdopt | grep '=$' | head -3
--jobgw=
--job=
--nb=

Use the same --listcmdopt to generate completion data for any external scripting that needs to know the registry contents at install time.

Command-line options for lmf / lmfa / lmchk (and friends) ​

Cmdline argument structure (the minimum) ​

How to read the table ​

Retired (now abort with migration hint) ​

Common (lmf / lmfa / lmchk) ​

SCF / electronic structure (lmf core) ​

Quit-points (debugging / staged runs) ​

Bands / DOS / Fermi surface ​

GW driver and friends (lmf --jobgw=…, gwsc internals) ​

MLO / Wannier-replacement (job_mlo, job_mloW, job_mlo_soc) ​

Density / potential I/O ​

Structure / symmetry (lmchk actions) ​

SOC ​

GPU / linear-algebra knobs ​

Post-processing helpers (hmlo_ovlppair, eps tools) ​

Diagnostic / debug-only flags ​

Run-time TOML overrides (--ctrlg:<path>=<value>) ​

When this page goes stale ​

Tab completion (bash) ​