AimsPy#
In-memory Python interface to FHI-aims via ctypes, for seamless integration with DeepX/DeepH-pack
AimsPy drives FHI-aims DFT calculations directly from Python — no subprocess, no file-staged I/O on hot paths — by loading a patched libaims.so via ctypes and exchanging matrices in memory through a callback framework. It is designed as the FHI-aims binding layer of the DeepH ecosystem, and the central enabler of warmstart SCF: injecting an externally-predicted Hamiltonian (e.g. from a DeepH-trained model) as the initial guess so that SCF converges rapidly in several iterations.
AimsPy also establishes a uniform in-memory representation of block-sparse real-space matrices — AimspyMatrix — that round-trips between FHI-aims’ internal CSR layout and the DeepH on-disk format with documented sign/parity conventions, making it equally useful as a standalone post-processing interface for FHI-aims users.
Features#
aimspy patch applies, uninstalls, and lists versioned patches against an FHI-aims source tree — no manual editing. No manual code editing required.
Run FHI-aims SCF calculations directly from Python — no subprocess, no file I/O on the critical path. Hamiltonian, overlap, energy, and forces are returned as native Python objects, ready for analysis or downstream processing.
Export converged Hamiltonian, overlap, and free-atom initial Hamiltonian to the DeepH on-disk format in a single pipeline — ideal for generating training data for DeepH models.
Provide a pre-trained Hamiltonian (e.g. from a DeepH model) as the initial guess, and SCF converges in several iterations instead of the usual 10+. Strategies — REPLACE, ADD, SCALE, CUSTOM — cover warmstart, correction (Delta-prediction), scaling, and custom transforms.
Use any Hamiltonian source for warmstart — the built-in DeepHData adapter reads DeepH-format data directly, and adding a new format is just one subpackage under aimspy/interface/.
Installation#
Install the latest release from PyPI:
pip install aimspy
AimsPy loads a patched libaims.so. To patch an FHI-aims source tree:
cd /path/to/FHI-aims
aimspy patch # applies the latest bundled diff
For detailed guidance including uv setup, patch variants, environment variables, and development installation, please refer to Installation & Setup.
Basic usage#
AimsPy is primarily a Python API. The most common entry point is the one-shot Calculator.do():
from mpi4py import MPI
from aimspy import Calculator, CalculatorConfig
config = CalculatorConfig(lib_path="/path/to/libaims.so")
with Calculator(config) as calc:
calc.do(comm=MPI.COMM_WORLD, work_dir="./MoS2")
H = calc.hamiltonian # AimspyMatrix (block-sparse, Hartree)
E = calc.energy # float (Hartree)
Run with MPI:
mpiexec -np 8 python script.py
The aimspy patch command-line tool manages the bundled FHI-aims patch:
aimspy patch --help
aimspy patch --list
aimspy patch --check /path/to/FHI-aims
For complete examples — baseline SCF, DeepH warmstart, DeepH export, and error recovery — see Basic Usage.
Citation#
Since AimsPy is part of the DeepH ecosystem and drives FHI-aims calculations, we recommend citing the following papers. Full details are on the Citation & License page.
1. DeepH-pack — the complete package featuring the latest implementation, methodology, and workflow of DeepH:
@article{li2026deeph,
title={DeepH-pack: A general-purpose neural network package for deep-learning electronic structure calculations},
author={Li, Yang and Wang, Yanzhen and Zhao, Boheng and Gong, Xiaoxun and Wang, Yuxiang and Tang, Zechen and Wang, Zixu and Yuan, Zilong and Li, Jialin and Sun, Minghui and Chen, Zezhou and Tao, Honggeng and Wu, Baochun and Yu, Yuhang and Li, He and da Jornada, Felipe H. and Duan, Wenhui and Xu, Yong },
journal={arXiv preprint arXiv:2601.02938},
year={2026}
}
2. DeepH-aims — the paper describing the DeepH–FHI-aims integration workflow (in publishing).
3. FHI-aims — the original FHI-aims paper, since AimsPy drives FHI-aims calculations: