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

Resumo Técnico do akaitools

Definição do Problema
O método da função de Green de Korringa-Kohn-Rostoker (KKR), particularmente a implementação AkaiKKR, é uma ferramenta padrão para cálculos de estrutura eletrônica de primeira ordem de ligas com desordem substitucional via Aproximação de Potencial Coerente (CPA). Apesar de seu uso difundido, a saída do AkaiKKR é um texto puro não estruturado que carece de uma interface programática. Isso força os usuários a depender de extração manual de dados, tornando estudos sistemáticos ou de alto rendimento (high-throughput) impraticáveis. Soluções existentes, como o oficial AkaiKKRPythonUtil, sofrem de limitações significativas: retornam tipos de dados inconsistentes (misturando escalares, listas, dicionários e DataFrames), acoplam a lógica de parsing com a geração de figuras (impedindo o reuso de dados sem renderização), carecem de documentação e tutoriais, são incompatíveis com ambientes Python modernos e não são atualizadas desde 2023. Além disso, outras ferramentas de pós-processamento KKR (por exemplo, SPR-KKR, AiiDA-KKR) são projetadas para bases de código diferentes e não podem processar a saída do AkaiKKR.

Metodologia e Design de Software
akaitools é um pacote Python 3.10+ projetado para processar a saída do AkaiKKR em objetos Python estruturados e com tipagem anotada. A arquitetura do software é construída sobre quatro camadas independentes para garantir modularidade e extensibilidade:

1. Parsers (Analisadores): Extraem o texto bruto das saídas do AkáKKR.
2. Camada de Modelo (Model Layer): Define o esquema de dados usando instâncias de dataclass imutáveis e com tipagem anotada. Isso garante imutabilidade, prevenindo erros silenciosos causados pela modificação acidental de resultados durante fluxos de trabalho de análise.
3. Utilitários (Utilities): Um módulo compartilhado contendo constantes (por exemplo, conversão de Rydberg para eV) usadas tanto pelas propriedades do modelo quanto pelo módulo de plotagem, sem que uma camada dependa da outra.
4. Módulo de Plotagem (Plotting Module): Gera figuras Matplotlib a partir de objetos do modelo, operando independentemente da lógica de parsing.

O pacote lida com três tipos primários de saída:

• Resultados de Campo Autoconsistente (SCF): Capturando o histórico de convergência e propriedades eletrônicas/magnéticas por átomo.
• Densidade de Estados (DOS): Dados resolvidos em spin e projetados em orbitais para cada componente CPA.
• Funções Espectrais de Bloch: Dados em caminhos de pontos-k definidos pelo usuário.

As principais características de design incluem o uso de arrays NumPy para dados de DOS e espectrais para suportar consultas vetorizadas e plotagem de custo zero (zero-copy). O pacote também inclui um gerador de arquivos de entrada programático que valida entradas via classes tipadas, permitindo a criação de pipelines completos de cálculo, desde a preparação de entrada até a análise de saída, inteiramente dentro do Python. Uma interface de linha de comando (CLI) é fornecida para resumos rápidos de arquivos e exportação para JSON sem a necessidade de scripts Python.

Principais Contribuições e Resultados
O pacote introduz um modelo de dados unificado onde todos os parsers retornam instâncias de uma única hierarquia de dataclasses imutáveis, compartilhando campos base para estrutura cristalina e metadados. Isso evita a divergência de esquema vista em utilitários anteriores.

• Robustez: O conjunto de testes compreende mais de 60 casos usando saídas reais do AkaiKKR para ligas de Fe, Ni, NiFe, GaAs e Li, cobrindo cálculos polarizados em spin e não polarizados em spin. O sistema levanta exceções explícitas identificando o arquivo e o campo específicos em caso de falha de parsing, em vez de retornar valores nulos.
• Interoperabilidade: Os resultados são exportados para DataFrames do Pandas e JSON, facilitando a integração com bancos de dados de materiais e pipelines de aprendizado de máquina.
• Visualização: O módulo de plotagem integrado produz figuras para curvas de DOS e convergência de SCF, conforme demonstrado nas figuras do artigo para Fe, Ni e GaAs.
• Documentação: Diferente de seus predecessores, o akaitools possui um site de documentação, referência de API e tutoriais, e está disponível no PyPI.

Significância
O artigo posiciona o akaitools como o primeiro parser estruturado projetado especificamente para a saída do AkaiKKR, preenchendo uma lacuna que excluiu este método de fluxos de trabalho de alto rendimento comuns na ciência dos materiais moderna. Ao permitir pipelines automatizados para tarefas como triagem de composição de ligas CPA, o pacote permite que pesquisadores substituam scripts shell ad-hoc por loops Python reproduzíveis. A capacidade de exportar resultados para JSON permite a portabilidade dos dados de cálculo entre ambientes, possibilitando a análise e integração em bancos de dados mesmo sem o AkaiKKR instalado. Os autores afirmam que esta ferramenta é essencial para alavancar o AkaiKKR no design de ligas de alto rendimento e para o estudo sistemático de magnetismo metálico, ligas desordenadas e semicondutores.