API Reference

Curated reference for the public interfaces (see unfolding/__init__.py).

CLI and TOML configuration

The unfolding console script exposes the same routes as the Python API. From an unpacked example bundle, run either the complete set of route flags or a TOML file as the only argument:

unfolding siesta --fdf data/si_sc.fdf --primitive data/si_prim.vasp \
    --unfold-mat -1 1 1 1 -1 1 1 1 -1 --special-points GXWGLX \
    --npts 300 --method ideal --output si_unfolded.png
unfolding --config unfold.toml

For the Python equivalent, pass explicit parameters to the adapter (shown on each example page), or load the same TOML file:

from unfolding import load_config, run
run(load_config("unfold.toml"))

unfolding --help lists routes; unfolding <route> --help lists that route’s flags and optional backend requirements. Paths in TOML are relative to the current working directory (the unpacked bundle root).

Consumer entry points

unfold_siesta(fdf=None, model=None, prim_atoms=None, unfold_sc_mat=None, spin="up", kpts=None, knames=None, xqpts=None, Xqpts=None, tol_r=0.04, orb_counts_prim=None, efermi=0.0, axis=None, output=None, ...)

One-call SIESTA LCAO unfolding. Parses fdf through HamiltonIO (or takes a pre-parsed model), builds the relabel map from prim_atoms/unfold_sc_mat, computes supercell eigenvalues and unfolded weights on kpts, and plots weight-coded bands (LCAOWeights-compatible). spin selects the spin channel of a collinear run.

unfold_abinit(wfk=None, unfold_sc_mat=None, kpts=None, *, data=None, knames=None, xqpts=None, Xqpts=None, spin=0, average_degenerate=None, resolve_degenerate=None, fermi_shift=True, axis=None, output=None, style="alpha", ...)

One-call ABINIT planewave unfolding. wfk is an ETSF netCDF WFK written with iomode 3 and full-G istwfk 1 storage, or data is a pre-parsed WFKData. unfold_sc_mat uses the row convention A_sc = M @ A_prim and kpts are primitive fractional coordinates. Eigenvalues cross the Hartree-to-eV boundary here; the default Fermi shift requires the WFK header. average_degenerate is an eV tolerance. resolve_degenerate (eV) eigen-assigns weights inside near-degenerate groups, restoring gauge-invariant branch weights when degenerate states are stored as unitary mixtures of their fold sectors. style accepts "alpha", "width", or "scatter" (per-point alpha; best for dense k-paths). Returns matplotlib Axes.

unfold_tb2j(source, unfold_sc_mat, qpts, knames=None, xqpts=None, Xqpts=None, spin_conf=None, degen_tolerance=1e-5, axis=None, output=None, style="alpha", ...)

One-call magnon downfolding from TB2J. source is a TB2J_results directory (with TB2J.pickle) or a configured TB2J Magnon; unfold_sc_mat uses the row convention A_sc = M @ A_prim (the magnetic cell onto the primitive chemical cell) and qpts are primitive fractional momenta. The collinear reference is the default (Q=0, αΊ‘ axis, moments from the pickle); spin_conf overrides the moments. Eigenvectors are converted from TB2J’s Cholesky frame to canonical BdG amplitudes before unfolding; energies plot in meV. Requires the tb2j extra. A thin CLI ships as unfolding-magnon (path + --unfold-mat + --kpath; the primitive cell is derived from the TB2J cell).

MagnonUnfolder(eigendata, unfold_sc_mat, tol_k=1e-6)

Backend-free magnon engine over MagnonEigenData (stored supercell momenta, positive-mode energies, canonical BdG wavefunctions (nk, nmode, 2*nmag), magnetic-atom fractional positions). compute(qpts, resolve_degenerate=...) returns MagnonWeights: the fold label is the requested primitive momentum itself; plain weights satisfy the per-mode sum rule over folds, and resolve_degenerate presents near-degenerate groups through their gauge-invariant group totals.

phonopy_unfold(sc_mat, unfold_sc_mat, force_constants, sposcar, qpts, qnames=None, xqpts=None, Xqpts=None)

Phonon supercell unfolding from phonopy FORCE_CONSTANTS: builds the supercell dynamical matrix, unfolds each mode onto the primitive q-path, and plots weight-coded phonon bands.

DDB_unfolder(dbname, sc_mat, kpath_bounds, knames, ...)

Unfolds phonon bands from an Abinit DDB (requires abipy + anaddb; external dependencies: abipy, nc_unfolder for netCDF DDBs).

Unfolder (deprecated)

Legacy generic Bloch-sum unfolding class. Superseded by LCAOUnfolder + RelabelMap (ADR-003); kept only for backward compatibility with old scripts.

Building blocks (LCAO path)

RelabelMap.from_atoms(sc_atoms, prim_atoms, unfold_sc_mat, tol_r=0.04, orb_counts_sc=None, orb_counts_prim=None)

Index map from supercell-orbital indices to primitive-orbital translations: determines the orbital translation matrix (sc-orbital -> prim-orbital + lattice translation) used by the unfolding Gram. orb_counts_* may be given explicitly; otherwise they are inferred from the ASE atoms (element -> orbital table).

HamiltonIOModel(model)

Adapter exposing a HamiltonIO-parsed Hamiltonian (.HS_and_eigen, .SR, .HR, .atoms) to the unfolder.

LCAOUnfolder(model, relabel_map, ndim3=1)

.compute(kpoints, method="ring") -> LCAOWeights with LCAOWeights(kpoints, eigenvalues, weights). method="ring" (default) is the exact supercell-torus projection (Parseval over the folded grid); method="ideal" reproduces the standard Popescu-Zunger / Lee weight at generic momenta and requires multi-shell (k-sampled) archives.

spinor module

Spinor (nspinor=2) variant: RelabelMapSpinor.from_atoms, HamiltonIOModelSpinor, LCAOUnfolderSpinor (story 010).

Building blocks (planewave WFK path)

HamiltonIO.abinit.read_wfk(path) -> WFKData

Reads ABINIT 9/10 ETSF netCDF WFKs through the optional netCDF4 dependency. It trims each padded plane-wave and band axis before storing immutable per-k arrays; only full-G istwfk == 1 complex storage is accepted.

WFKData

A HamiltonIO record retaining row-oriented WFK rprimd, codvsn, per-k istwfk, and Hartree Fermi energy. Pass it to unfold_abinit(data=...); for direct PWUnfolder use PWEigenData(data.kpoints, data.gvecs, data.coefficients, data.eigenvalues).

unfold_abinit_paw(supercell, primitive, datasets, matrix, spin=0, resolve_degenerate=None)

HamiltonIO.abinit.read_paw_wfk parses netCDF WFK and matching JTH XML data. The adapter embeds primitive reference bands into the supercell reciprocal basis and evaluates the PAW overlap metric. Returns PAW weights, pseudo-only coset fractions, Hartree energies, and per-band PAW norm residuals. The optional degeneracy tolerance is in Hartree. Scalar full-G WFKs only; a PAW WFK is rejected by the norm-conserving unfold_abinit shortcut.

unfold_vasp_paw(supercell, primitive, potcar, matrix, spin=0, resolve_degenerate=None)

HamiltonIO.vasp.read_wavecar parses full-sphere scalar WAVECARs; read_potcar_paw parses the caller-supplied licensed POTCAR. Accepts parsed data or (WAVECAR, POSCAR) pairs. Returns PAW reference-band weights, pseudo fractions and eV energies. The optional degeneracy tolerance is in eV. VASP gamma-half and spinor WAVECARs are not supported; private POTCAR files must never be redistributed.

PWEigenData, PWUnfolder(eigendata, unfold_sc_mat), and PWWeights

Backend-free reciprocal-coset unfolding. PWEigenData carries variable per-k G bases and coefficients shaped (nspin, nband, nspinor, npw); PWUnfolder.compute(kpoints, spin=0) returns PWWeights with the spinor axis traced. PWWeights.average_degenerate(tol_e) groups in its current energy unit, and .plot(...) produces the shared weight-coded plot.

Unfolded-band datasets

save_dataset(result, path, *, route, provenance=None, fermi_energy=None, energy_reference=None, energy_unit="eV")

Serialize any engine result (an object with kpoints, eigenvalues or energies, and weights) to a versioned JSON document (unfolding.dataset/1): plain nested lists, NaN weights written as null, optional fold/supercell k-points, Fermi level, energy unit and a small provenance record. Stable byte-for-byte on re-save.

plot_dataset(dataset, *, ax=None, style="alpha", ylabel=None, x=None, spin="both", fermi_at_zero=None, overlay=None, overlay_shift=None, overlay_orientation=None, ...)

Render a parsed dataset through the shared weight-coding. Pass your own ax for subplot composition; overlay draws primitive reference bands (a second dataset or (x, energies) arrays) shifted by the explicit overlay_shift β€” alignment between runs is a physical decision, never inferred. Square (x, energies) arrays require an explicit overlay_orientation="kpoints_first" or "bands_first". The default Fermi alignment follows the JSON energy_reference marker and avoids double-shifting routes whose energies are already E_F-relative.

Plotting

plotphon.plot_band_weight(kslist, ekslist, wkslist, xticks, ylabel=..., ypad=..., ...)

Weight-coded band plot used by all adapters: scatter-coloured bands with x ticks at high-symmetry points.