akaitools

akaitools parses output files from AkaiKKR, a Korringa-Kohn-Rostoker (KKR) Green's function code for electronic structure calculations. It turns raw text output into structured, fully typed Python objects and can generate new AkaiKKR input files from scratch or from parsed results.

Report a Bug | Request a Feature | Documentation

Key features

• Parse SCF, DOS, and SPC/BSF outputs with parse_go(), parse_dos(), and parse_spc()
• Access spin-resolved DOS through spin_up, spin_down, get_component(), and select()
• Read Bloch spectral function matrices with automatic spectral-data discovery and high-symmetry k-point labels
• Work with frozen dataclass models backed by NumPy arrays, with eV conversion helpers on energy-bearing fields
• Export DOS and SCF iteration data to pandas with .to_dataframe()
• Generate Matplotlib figures for DOS, SCF convergence, and BSF with akaitools.plotting
• Inspect files from the terminal with akaitools go|dos|spc, or plot them directly with akaitools plot dos|scf|bsf
• Build AkaiKKR inputs programmatically with InputFile, including CPA alloys, multi-site structures, and SPC KPath / KPoint definitions, or parse existing .in files back with from_file()/from_string()

Installation

# Recommended
uv add akaitools

# pip
pip install akaitools

# Latest from GitHub
pip install git+https://github.com/dogusariturk/akaitools.git

For CLI-only use: install akaitools as a standalone tool available globally, without adding it to a project:

uv tool install akaitools

Or run one-off commands without installing:

uvx akaitools go calculation.out
uvx akaitools dos dos.out --json

Quickstart

SCF output

Use parse_go to parse a self-consistent field output file. The result contains the full convergence history, per-atom electronic and magnetic properties, and crystal structure information.

from akaitools import parse_go

scf = parse_go("calculation.out")

print(f"Converged   : {scf.converged}")
print(f"Iterations  : {len(scf.iterations)}")
print(f"Total energy: {scf.iterations[-1].total_energy:.8f} Ry")
print(f"Moment      : {scf.iterations[-1].moment:.4f} uB")

df = scf.to_dataframe()  # columns: neu, moment, total_energy_Ry, total_energy_eV, rms_error

DOS output

Use parse_dos to parse a density of states output file. Components can be accessed by index and spin with get_component, or filtered by element, site type, or label with select.

from akaitools import parse_dos

dos = parse_dos("dos.out")

for comp in dos.spin_up:
    print(f"Component {comp.component_index} [{comp.label}] up: {len(comp.energy)} points")

fe_up = dos.get_component(1, "up")
print(f"Energy range: {fe_up.energy[0]:.3f} to {fe_up.energy[-1]:.3f} Ry")
print(f"d-DOS max   : {fe_up.d.max():.4f} states/Ry/cell")

x_up = dos.select(symbol="X", spin="up")
df = dos.to_dataframe()

SPC output

Use parse_spc to parse a Bloch Spectral Function output. The *_up.spc and *_dn.spc data files are located automatically next to the log file, or can be provided explicitly via data_up and data_down.

from akaitools import parse_spc

spc = parse_spc("calculation.spc")

if spc.spectral_up is not None and spc.spectral_up.data is not None:
    bsf = spc.spectral_up
    print(f"BSF shape: {bsf.data.shape}")
    print(f"k-labels : {bsf.kmesh.high_symmetry_indices}")

parse_spc() auto-locates *_up.spc and *_dn.spc next to the log file. Use base_dir, data_up, or data_down to override the discovery logic when needed.

Plotting

akaitools.plotting provides ready-made Matplotlib figures for the most common visualizations. All functions return a Figure object for further customization before saving.

from akaitools import parse_dos, parse_go, parse_spc
from akaitools.plotting import plot_bsf, plot_convergence, plot_dos

scf = parse_go("calculation.out")
dos = parse_dos("dos.out")
spc = parse_spc("calculation.spc")

plot_convergence(scf, field="rms_error").savefig("convergence.png")
plot_dos(dos, orbitals=["total", "d"], energy_unit="eV").savefig("dos.png")
plot_dos(dos, orbitals=["total"]).savefig("dos_overlay.png")
plot_bsf(spc, energy_unit="eV").savefig("bsf.png")

CLI

The akaitools command provides quick summaries of output files without writing any Python. Use --json for machine-readable output.

akaitools go calculation.out                          # summarize SCF output
akaitools go calculation.out --json                   # output as JSON
akaitools dos dos.out -c 1                            # DOS summary for component 1
akaitools spc calculation.spc --base-dir /path/to/run # SPC summary

Plots are also available as akaitools plot subcommands, without writing any Python:

akaitools plot dos dos.out --orbitals total,d --energy-unit eV -o dos.png
akaitools plot scf calculation.out --field total_energy_ev -o convergence.png
akaitools plot bsf calculation.spc --base-dir /path/to/run --energy-unit eV -o bsf.png

Input generation

Use InputFile to write a new AkaiKKR input file from scratch. All parameters have sensible defaults; only mode, data_file, bravais, a, atom_types, and positions are required.

from akaitools import InputFile, KPath, KPoint, parse_go
from akaitools.models import AtomicComponent, AtomPosition, AtomType

fe = InputFile(
    mode="go",
    data_file="data/fe",
    bravais="bcc",
    a=5.27,
    atom_types=[
        AtomType(
            name="Fe",
            rmt=0.0,
            field=0.0,
            lmxtyp=2,
            components=[AtomicComponent(anclr=26.0, conc=1.0)],
        )
    ],
    positions=[AtomPosition(x=0.0, y=0.0, z=0.0, atom_type="Fe")],
)
fe.write("fe.in")

scf = parse_go("calculation.out")
InputFile.from_result(scf, mode="dos").write("dos.in")

kpath = KPath(
    nkpts=300,
    points=[
        KPoint("0", "0", "0", label="G"),
        KPoint("0", "1", "0", label="H"),
        KPoint("1/2", "1/2", "0", label="N"),
    ],
)
InputFile.from_result(scf, mode="spc", kpath=kpath).write("spc.in")

License

This project is licensed under the GNU GPLv3 License. See LICENSE.

Citation

If you use akaitools in your research, please cite the following:

Sarıtürk, D., & Arróyave, R. (2026). akaitools: A Python package for parsing and analyzing AkaiKKR electronic structure calculations. arXiv. https://doi.org/10.48550/arXiv.2606.18399

Sarıtürk, D. (2026). akaitools. Zenodo. https://doi.org/10.5281/zenodo.19874850

BibTeX:

@misc{sariturk_2026_arxiv,
  author    = {Sarıtürk, Doğuhan and Arróyave, Raymundo},
  title     = {{akaitools}: A {Python} Package for Parsing and Analyzing {AkaiKKR} Electronic Structure Calculations},
  year      = 2026,
  publisher = {arXiv},
  doi       = {10.48550/arXiv.2606.18399},
  url       = {https://doi.org/10.48550/arXiv.2606.18399},
}

@software{sariturk_2026_19874850,
  author    = {Sarıtürk, Doğuhan},
  title     = {akaitools},
  year      = 2026,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19874850},
  url       = {https://doi.org/10.5281/zenodo.19874850},
}