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

---

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

# Export to pandas
df = spc.to_dataframe()  # columns: energy_Ry, k, spin, intensity

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