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 without any manual text wrangling.

Report a Bug | Request a Feature

---

Key features

• Parse SCF, DOS, and BSF output files with a single function call (parse_go, parse_dos, parse_spc)
• Spin-resolved DOS with direct access via spin_up, spin_down, get_component(), and select()
• Bloch Spectral Function intensity matrix with k-path high-symmetry labels
• Export any result to a pandas DataFrame for downstream analysis
• Built-in Matplotlib plotting for DOS, SCF convergence, and the Bloch spectral function
• Command-line interface for quick summaries and JSON export
• Generate AkaiKKR input files from scratch or from any parsed result with InputFile, or parse existing ones back with from_file()/from_string()
• Fully typed: all models are frozen, immutable Python dataclass objects

---

Quickstart

SCFDOSSPCPlottingCLIInput

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} μB")

for prop in scf.atomic_properties:
    print(f"  {prop.element:<4s}  charge={prop.total_charge:.3f}  m={prop.spin_moment:.4f} μB")

from akaitools import parse_dos

dos = parse_dos("dos.out")

# Spin-resolved access
for comp in dos.spin_up:
    print(f"Component {comp.component_index} [{comp.label}] ↑: {len(comp.energy)} points")

# Direct lookup by component index and spin
fe_up = dos.get_component(1, "up")
print(f"Energy range: {fe_up.energy[0]:.3f} – {fe_up.energy[-1]:.3f} Ry")
print(f"d-DOS max   : {fe_up.d.max():.4f} states/Ry/cell")

# Export to pandas
df = dos.to_dataframe()
print(df.head())

from akaitools import parse_spc

# *_up.spc / *_dn.spc are located automatically next to the log file
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}")   # (n_energy, n_kpoints)
    print(f"k-labels : {bsf.kmesh.high_symmetry_indices}")

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")

# SCF convergence
plot_convergence(scf, field="rms_error").savefig("convergence.png", dpi=150)

# Total + d-orbital DOS, energy in eV
plot_dos(dos, ef=0.0, orbitals=["total", "d"], energy_unit="eV").savefig("dos.png", dpi=150)

# Component totals plus system total on the same axes
plot_dos(dos, orbitals=["total"], system_total=True, ef=0.0).savefig("dos_overlay.png", dpi=150)

# Bloch spectral function, energy in eV
plot_bsf(spc, energy_unit="eV").savefig("bsf.png", dpi=150)

# Summarise an SCF output
akaitools go  calculation.out

# Summarise a DOS output, filtered to component 1
akaitools dos dos.out -c 1

# Summarise a BSF output
akaitools spc calculation.spc

# JSON output (pipe-friendly)
akaitools go calculation.out --json | jq .atomic_properties

# Plot the Bloch spectral function directly, no Python required
akaitools plot bsf calculation.spc --energy-unit eV -o bsf.png

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

# Build from scratch
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")

# Reconstruct from a parsed result and switch to DOS mode
scf = parse_go("calculation.out")
InputFile.from_result(scf, mode="dos").write("dos.in")

---

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},
}