Command Line Interface

kapaow automatically installs the command kapaow. See kapaow --help for usage details.

kapaow

CLI for kapaow.

Usage

kapaow [OPTIONS] COMMAND [ARGS]...

Options

--version: Show the version and exit.

--debug: Enable debug mode.

-l, --log: Enable logging to kapaow.log.

animate

Generate a GIF showing PAOs under varying confinement.

Usage

kapaow animate [OPTIONS] UPF

Options

--frames-per-segment <frames_per_segment>: Number of frames per path segment.

--max-r-mid <max_r_mid>: Maximum midpoint of confining potential.

--min-r-mid <min_r_mid>: Minimum midpoint of confining potential.

--min-width <min_width>: Minimum half-width of confining potential.

--max-width <max_width>: Maximum half-width of confining potential.

--energy-shift-threshold <energy_shift_threshold>: Energy shift threshold in Ha; orbitals above this are plotted in red.

--add <add>

Add basis functions to the PAO basis (repeatable, e.g. –add subshell –add subshell).

Options:: subshell | polarization | s | p | d | f | g

-o, --output <output>: Save the output to this file.

Arguments

UPF: Required argument

benchmark

[experimental] Benchmark rival projectors by wannierizing a structure.

Runs wannierization (as a metal) for each rival projector .dat file and compares disentanglement difficulty, convergence, and Wannier function spreads.

CONFIG is a TOML file specifying the structure and projectors per element:

structure = "LiF.cif"

[Li]
"Optimal PAO" = "projectors/Li_optimal.dat"
"PseudoDojo"  = "projectors/Li_pseudodojo.dat"

[O]
"Standard" = "projectors/O.dat"

Example:

kapaow benchmark benchmark.toml

Usage

kapaow benchmark [OPTIONS] CONFIG

Options

-o, --output <output>: Working directory for benchmark outputs (default: tmp/benchmark/<config_stem>).

--symmetrize: Rotate projectors into a symmetry-adapted, bond-oriented basis (sp-n hybrids + non-bonding irrep orbitals) before use.

Arguments

CONFIG: Required argument

confine

Solve for PAOs under a confining potential, optionally adding orbitals.

If -o/–output is not provided, the .dat content is printed to stdout.

Examples:

kapaow confine Li.upf --add subshell --rc 8 --ri-factor 0.9
kapaow confine Li.upf --add subshell --add subshell

Usage

kapaow confine [OPTIONS] UPF

Options

--rc <rc>: Confinement radius.

--ri-factor <ri_factor>: Inner radius factor for the confining potential.

--add <add>

Add basis functions to the PAO basis (repeatable, e.g. –add subshell –add subshell).

Options:: subshell | polarization | s | p | d | f | g

-o, --output <output>: Output .dat file path (default: auto-generated from UPF name and parameters).

Arguments

UPF: Required argument

convert

Convert a pseudopotential file to Wannier90 .dat format.

INPUT_FILE is a UPF pseudopotential or an OpenMX .pao file. The format is detected from the file extension.

If -o/–output is not provided, the .dat content is printed to stdout.

Examples:

kapaow convert Li.upf
kapaow convert Li.upf -o Li.dat
kapaow convert Li8.0.pao --select sspd

Usage

kapaow convert [OPTIONS] INPUT_FILE

Options

--select <select_str>: Orbitals to extract from an OpenMX .pao file (e.g. ‘sspd’ for 2s, 1p, 1d). Only valid for .pao files.

-o, --output <output>: Output .dat file path (default: <stem>.dat).

Arguments

INPUT_FILE: Required argument

emit-ranks

Emit one .dat file per augmentation rank, by post-processing a single femdvr solve.

Usage

kapaow emit-ranks [OPTIONS] UPF

Options

--rc <rc>: Confinement radius (Bohr).

--rc-search-json <rc_search_json>: Read rc from a kapaow optimize rc JSON output.

--ri-factor <ri_factor>: Inner radius factor for the confinement potential. If omitted, read from –rc-search-json (when given), else falls back to kapaow’s DEFAULT_RI_FACTOR_MAX.

--max-rank <max_rank>: Cap the number of extra orbitals (ranks) emitted.

-o, --output-dir <output_dir>

Directory to write .dat and .json output files.

Default:: PosixPath('.')

Arguments

UPF: Required argument

optimize

Optimize PAO parameters.

Usage

kapaow optimize [OPTIONS] COMMAND [ARGS]...

projectability

[experimental] Optimize PAOs to maximise their projectability via Bayesian optimization.

Usage

kapaow optimize projectability [OPTIONS] UPF

Options

--add <add>

Add basis functions to the PAO basis (repeatable, e.g. –add subshell –add subshell).

Options:: subshell | polarization | s | p | d | f | g

Arguments

UPF: Required argument

rc

Bisect over rc to find the smallest value satisfying an energy-shift threshold.

Usage

kapaow optimize rc [OPTIONS] UPF

Options

--ri-factor <ri_factor>

Fixed inner radius factor.

Default:: 0.95

--threshold <threshold>: Required Maximum allowed energy shift in Ha.

--rc-min <rc_min>: Lower bound of the rc bracket.

--rc-max <rc_max>: Upper bound of the rc bracket.

--tol <tol>

Absolute tolerance on rc at which to stop bisecting.

Default:: 0.05

--json <json_path>: Save the search result to this JSON file (default: tmp/optimize/rc_search/<upf_stem>.json).

--add <add>

Add basis functions to the PAO basis (repeatable, e.g. –add subshell –add subshell).

Options:: subshell | polarization | s | p | d | f | g

Arguments

UPF: Required argument

spread

Optimize PAO spread by scanning rc and ri_factor, producing a Pareto front.

Usage

kapaow optimize spread [OPTIONS] UPF

Options

--rc <rc>: Confinement radii to scan (can be specified multiple times).

--ri-factor <ri_factor>: Inner radius factors to scan (can be specified multiple times).

-o, --output <output>: Save the Pareto plot to this file.

--loglog: Use log-log axes.

--logy: Use log scale for the y-axis only.

--json <json_path>: Save the grid data to a JSON file.

--add <add>

Add basis functions to the PAO basis (repeatable, e.g. –add subshell –add subshell).

Options:: subshell | polarization | s | p | d | f | g

Arguments

UPF: Required argument

plot

Plot PAO-related data.

Usage

kapaow plot [OPTIONS] COMMAND [ARGS]...

compare-gauge-matrices

[experimental] Compare A_mn^k and U_mn^k matrices across different PAO choices.

Computes the projection matrix A and its unitary polar factor U (from SVD) for each PAO set defined in the TOML config, then prints a Cartesian product table of pairwise distances. The distance metric is the square root of the BZ-averaged squared Frobenius norm of the difference.

CONFIG_FILE uses the same [[Element]] syntax as compare-projectability.

Example:

kapaow plot compare-gauge-matrices LiF_projectability_comparison.toml

Usage

kapaow plot compare-gauge-matrices [OPTIONS] CONFIG_FILE

Options

--working-dir <working_dir>: Working directory (default: tmp/matrix_comparison/<config_stem>).

--num-bands <num_bands>: Manual override for the number of bands in the DFT calculation.

Arguments

CONFIG_FILE: Required argument

compare-projectability

[experimental] Compare total projectability across different basis sets.

CONFIG_FILE is a TOML file where elements can have multiple entries (using [[Element]] syntax) to define comparison sets. Example:

b: structure = “LiF.cif”
b: [[Li]] openmx = true rc = 8.0 label = “OpenMX rc=8”
b: [[Li]] upf = “Li.upf” rc = 15.0 label = “UPF rc=15”
b: [F] upf = “F.upf” rc = 15.0

Usage

kapaow plot compare-projectability [OPTIONS] CONFIG_FILE

Options

--working-dir <working_dir>: Working directory (default: tmp/proj_comparison/<config_stem>).

--emin <emin>: Minimum energy relative to Fermi level (eV).

--emax <emax>: Maximum energy relative to Fermi level (eV).

--num-bands <num_bands>: Manual override for the number of bands in the DFT calculation.

-o, --output <output>: Save the output to this file (default: <config_stem>.svg).

Arguments

CONFIG_FILE: Required argument

fat-bands

[experimental] Plot fat bands colored by projectability.

CONFIG_FILE is a TOML file specifying the structure and per-element pseudopotentials. Example:

b: structure = “LiF.cif”
b: [Li] upf = “Li.upf” rc = 15.0 ri_factor = 0.3 extension = “subshell”
b: [F] upf = “F.upf”

Usage

kapaow plot fat-bands [OPTIONS] CONFIG_FILE

Options

--working-dir <working_dir>: Working directory for intermediate files (default: tmp/fat_bands/<config_stem>).

--emin <emin>: Minimum energy relative to Fermi level (eV).

--emax <emax>: Maximum energy relative to Fermi level (eV).

--num-bands <num_bands>: Manual override for the number of bands in the DFT calculation.

--symmetrize: Rotate projectors into a symmetry-adapted, bond-oriented basis (sp-n hybrids + non-bonding irrep orbitals) before use.

-o, --output <output>: Save the output to this file (default: <config_stem>.svg).

Arguments

CONFIG_FILE: Required argument

optimize-trajectory

[experimental] Plot bands distance vs dis_proj_max from a Bayesian optimization run.

PK is the AiiDA PK of the Wannier90OptimizeWorkChain or its parent workgraph process node.

Usage

kapaow plot optimize-trajectory [OPTIONS] PK

Options

-o, --output <output>: Save the output to this file.

Arguments

PK: Required argument

paos

Plot the pseudoatomic orbitals stored in a Wannier90 .dat file.

Usage

kapaow plot paos [OPTIONS] [DAT]...

Options

-o, --output <output>: Save the output to this file.

Arguments

DAT: Optional argument(s)

periodic-table

Plot a periodic table colored by a PAO quality metric.

DIRECTORY contains per-element data files: optimizer log JSONs for –color-by projectability, Pareto front JSONs for –color-by spread, or rc-search JSONs for –color-by rc.

Usage

kapaow plot periodic-table [OPTIONS] DIRECTORY

Options

--color-by <color_by>

Required Metric to color the periodic table by.

Options:: projectability | spread | rc

--threshold <threshold>

Energy shift threshold in Ha (only used with –color-by spread).

Default:: 0.01

-o, --output <output>: Save the output to this file.

Arguments

DIRECTORY: Required argument

projectability-optimization

[experimental] Plot the results of a projectability optimization.

Usage

kapaow plot projectability-optimization [OPTIONS] LOG_FILE

Options

-o, --output <output>: Save the output to this file.

Arguments

LOG_FILE: Required argument

spread-optimization

Plot a spread optimization Pareto front from an existing JSON file.

Usage

kapaow plot spread-optimization [OPTIONS] JSON_FILE

Options

-o, --output <output>: Save the output to this file.

--loglog: Use log-log axes.

--logy: Use log scale for the y-axis only.

Arguments

JSON_FILE: Required argument

unshifted-vs-rc

[experimental] Plot cumulative fraction of elements below energy shift threshold vs rc.

GRID_DIRECTORY is a directory containing per-element grid JSON files.

Usage

kapaow plot unshifted-vs-rc [OPTIONS] GRID_DIRECTORY

Options

--threshold <threshold>

Energy shift threshold in Ha.

Default:: 0.01

-o, --output <output>: Save the output to this file.

Arguments

GRID_DIRECTORY: Required argument