akaitools: A Python package for parsing and analyzing AkaiKKR electronic structure calculations

The paper introduces **akaitools**, a Python package designed to parse, structure, and analyze unstructured output from AkaiKKR electronic structure calculations, thereby enabling systematic, high-throughput studies of disordered alloys through features like dataclass-based results, visualization tools, and automated input generation.

The Gist

Imagine you are a chef trying to read a recipe written in a language you don't speak, on a piece of paper that is stained, torn, and written in a messy, unstructured handwriting. That is what scientists face when they use a powerful computer program called AkaiKKR to study how atoms behave in metals and alloys.

AkaiKKR is like a super-smart, old-school calculator that can predict the magnetic and electronic properties of materials. It's been around for decades and is very good at its job. However, when it finishes its work, it spits out a massive, chaotic wall of plain text. There are no labels, no clear tables, and no way for other computer programs to "talk" to it. To get the data out, a scientist has to manually copy-paste numbers into a spreadsheet, which is slow, boring, and prone to human error.

Enter akaitools: The Digital Translator and Organizer

The paper introduces akaitools, a new Python package that acts like a digital translator and a super-organized librarian for this messy text.

Here is how it works, using some everyday analogies:

1. Turning Chaos into a Structured Library

Before akaitools, getting data from AkaiKKR was like trying to find a specific book in a library where all the books were thrown in a giant pile on the floor. You had to dig through them one by one.

• The Solution: akaitools takes that pile of messy text and instantly organizes it into a perfectly labeled, digital filing cabinet. It turns the unstructured text into neat, structured "data objects" (like digital folders) that computers can easily read, search, and understand.

2. The "Frozen" Blueprint

The paper mentions that the data is stored as "frozen dataclasses." Think of this like a cast-in-concrete blueprint.

• Once the data is read from the computer file, it is "frozen." No one can accidentally change the numbers later. This prevents "silent bugs" where a scientist might accidentally tweak a number and not realize it, leading to wrong conclusions. It ensures the data remains exactly as the original computer calculated it.

3. The Universal Adapter

The paper compares akaitools to older tools that were like specialized adapters that only worked for one specific plug and often broke the moment you tried to plug them in.

• akaitools is a universal adapter. It handles three different types of data (how the system converges, the density of states, and spectral functions) using a single, consistent system. It doesn't mix and match confusing formats; everything fits together perfectly.

4. The "No-Script" Dashboard

One of the coolest features is the Command-Line Interface (CLI).

• Imagine you have a dashboard on your car. You don't need to know how to build an engine or write code to check your speed or fuel level; you just look at the gauge.
• akaitools has a similar dashboard. A scientist can type a simple command (like akaitools summary file.txt) and get a quick report or a JSON file without writing a single line of complex code. It's like having a "one-click" summary button.

5. The Automated Assembly Line

The paper highlights that akaitools can also generate input files.

• Imagine you are baking cookies and need to test 50 different recipes with slightly different amounts of sugar. Instead of manually writing out 50 different recipe cards, akaitools is like a robot arm that reads your last result, automatically writes the next recipe card, and sets up the oven for the next batch. This allows scientists to run "high-throughput" studies, testing hundreds of material combinations automatically.

Why Does This Matter?

For years, AkaiKKR was a "black box." It did great work, but getting the results out was a manual, tedious chore that kept it out of modern, automated scientific workflows.

akaitools opens the door. It allows AkaiKKR to join the party with other modern tools. Now, scientists can build automated pipelines where the computer reads the output, analyzes it, and sets up the next experiment all by itself, without a human needing to manually copy-paste numbers from a text file. It turns a manual, error-prone process into a smooth, automated assembly line for discovering new materials.

Technical Summary

Technical Summary of akaitools

Problem Statement
The Korringa-Kohn-Rostoker (KKR) Green's function method, particularly the AkaiKKR implementation, is a standard tool for first-principles electronic structure calculations of substitutionally disordered alloys via the Coherent Potential Approximation (CPA). Despite its widespread use, AkaiKKR output is unstructured plain text lacking a programmatic interface. This forces users to rely on manual data extraction, rendering systematic or high-throughput studies impractical. Existing solutions, such as the official AkaiKKRPythonUtil, suffer from significant limitations: they return inconsistent data types (mixing scalars, lists, dicts, and DataFrames), couple parsing logic with figure generation (preventing data reuse without rendering), lack documentation and tutorials, are incompatible with modern Python environments, and have not been updated since 2023. Furthermore, other KKR post-processing tools (e.g., SPR-KKR, AiiDA-KKR) are designed for different codebases and cannot parse AkaiKKR output.

Methodology and Software Design
akaitools is a Python 3.10+ package designed to parse AkaiKKR output into structured, type-annotated Python objects. The software architecture is built upon four independent layers to ensure modularity and extensibility:

1. Parsers: Extract raw text from AkaiKKR output files.
2. Model Layer: Defines the data schema using frozen, type-annotated dataclass instances. This ensures immutability, preventing silent bugs caused by accidental modification of results during analysis workflows.
3. Utilities: A shared module containing constants (e.g., Rydberg-to-eV conversion) used by both the model properties and the plotting module, with neither layer depending on the other.
4. Plotting Module: Generates Matplotlib figures from model objects, operating independently of the parsing logic.

The package handles three primary output types:

• Self-Consistent Field (SCF) Results: Capturing convergence history and per-atom electronic/magnetic properties.
• Density of States (DOS): Spin-resolved, orbital-projected data for each CPA component.
• Bloch Spectral Functions: Data on user-defined k-point paths.

Key design features include the use of NumPy arrays for DOS and spectral data to support vectorized queries and zero-copy plotting. The package also includes a programmatic input file generator that validates inputs via typed classes, allowing for the creation of full calculation pipelines from input preparation to output analysis entirely within Python. A command-line interface (CLI) is provided for quick file summaries and JSON export without requiring Python scripting.

Key Contributions and Results
The package introduces a unified data model where all parsers return instances from a single hierarchy of frozen dataclasses, sharing base fields for crystal structure and metadata. This prevents the schema divergence seen in previous utilities.

• Robustness: The test suite comprises over 60 cases using real AkaiKKR output for Fe, Ni, NiFe alloys, GaAs, and Li, covering spin-polarized and non-spin-polarized calculations. The system raises explicit exceptions identifying the specific file and field upon parsing failure, rather than returning null values.
• Interoperability: Results are exported to Pandas DataFrames and JSON, facilitating integration with materials databases and machine-learning pipelines.
• Visualization: The built-in plotting module produces figures for DOS curves and SCF convergence, as demonstrated in the paper's figures for Fe, Ni, and GaAs.
• Documentation: Unlike its predecessors, akaitools ships with a documentation site, API reference, and tutorials, and is available on PyPI.

Significance
The paper positions akaitools as the first structured parser specifically designed for AkaiKKR output, addressing a gap that has excluded this method from multi-code high-throughput workflows common in modern materials science. By enabling automated pipelines for tasks such as CPA alloy composition screening, the package allows researchers to replace ad-hoc shell scripts with reproducible Python loops. The ability to export results to JSON allows for the portability of calculation data across environments, enabling analysis and database integration even without AkaiKKR installed. The authors assert that this tool is essential for leveraging AkaiKKR in high-throughput alloy design and for studying metallic magnetism, disordered alloys, and semiconductors in a systematic manner.