In-memory Python interface to FHI-aims

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.

For the most comprehensive usage documentation, please visit https://docs.deeph-pack.com/aimspy/en/latest/.

---

• Core Features
• Runtime Environment
  • Install Intel OneAPI Toolchain
• Quick Start
  • Installation
  • Basic Usage
• Citation
• Application Scenarios
• Contributing
• License
• Support & Contact

Core Features

• Bundled FHI-aims Patch: Patch FHI-aims with a single command aimspy patch applies, uninstalls, and lists versioned patches against an FHI-aims source tree. No manual code editing required.

• In-Memory SCF: Run FHI-aims SCF calculations directly from Python. Hamiltonian, overlap, energy, and forces are returned as native Python objects, ready for analysis or downstream processing.

• DeepH Export: 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. Forces and total energy can optionally be exported to force.h5 (MD-style format) for MD training data.

• Warmstart: 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.

• Pluggable Matrix Sources: 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/.

• Real-Space Grid Data Capture: Export converged density, Kohn-Sham potential, and grid geometry for post-processing and analysis. Includes vdW potential when enabled in FHI-aims.

• NAO Radial Basis Capture: Export the complete cubic-spline representation of all numerical atomic-orbital radial basis functions (u(r), kinetic, derivative) during init(), and build reusable per-element basis.h5 basis libraries for offline inspection and plotting (aimspy viz-basis).

Runtime Environment

AimsPy requires a patched libaims.so built with an MPI-enabled Fortran compiler and a BLAS/LAPACK math library. The tested configuration uses Intel OneAPI.

Install Intel OneAPI Toolchain

Download from the Intel OneAPI Toolkit page.

Required components:

• Intel Fortran compiler (ifx / mpiifx)
• Intel C/C++ compiler (icx / icpx)
• Intel MKL (includes BLAS, LAPACK, ScaLAPACK, BLACS)
• Intel MPI (mpiifx is the MPI Fortran wrapper)

After installation, set up the environment:

source /opt/intel/oneapi/setvars.sh

Note: Other MPI distributions and math libraries (e.g. OpenMPI + OpenBLAS) can also be used, as long as they support building FHI-aims and mpi4py. The key requirement is that mpi4py and libaims.so use the same MPI backend — see Installation & Setup for details.

Quick Start

Installation

Publish version:

pip install aimspy

Development version:

pip install git+https://github.com/kYangLi/aimspy

Plotting helpers (aimspy viz-basis / aimspy viz-grid and the aimspy.viz / aimspy.viz_basis modules) additionally require matplotlib (and scipy for contour mode); install them with:

pip install aimspy[viz]

AimsPy loads a patched libaims.so at runtime. To patch an FHI-aims source tree:

cd /path/to/FHI-aims        # clean checkout, e.g. on branch `dev`
aimspy patch                 # applies the latest bundled diff

Common variants:

aimspy patch /path/to/FHI-aims             # patch a specific tree
aimspy patch -v v0.1.0 /path/to/FHI-aims   # use a specific patch version
aimspy patch --check /path/to/FHI-aims     # dry-run
aimspy patch --uninstall /path/to/FHI-aims # reverse the detected patch
aimspy patch --list                        # show bundled versions

Prerequisites: a clean FHI-aims checkout on the patch's base branch. FHI-aims itself is not distributed with AimsPy. Users must obtain its source code independently from the aims team.

Note: The current patch supports FHI-aims versions 250822 and 250822_1 only. Other versions are not compatible. Patches for additional FHI-aims versions will be released in the future.

Note: AimsPy loads libaims.so via ctypes at runtime, so FHI-aims must be built as a shared library (-DBUILD_SHARED_LIBS=ON). For detailed setup (uv environment, building libaims.so, environment variables), see Installation & Setup for full build instructions.

Basic Usage

Three core workflows:

1. Baseline SCF: run a standard FHI-aims SCF calculation and extract results as Python objects.
2. DeepH export: run SCF and export matrices to the DeepH on-disk format for training data generation.
3. DeepH warmstart: inject a pre-trained Hamiltonian and converge SCF in several iterations.

Baseline SCF on a prepared work_dir (must contain the FHI-aims required input files control.in + geometry.in):

from mpi4py import MPI
from aimspy import Calculator, CalculatorConfig

comm = MPI.COMM_WORLD
rank = comm.rank

config = CalculatorConfig(lib_path="/path/to/libaims.so")
with Calculator(config) as calc:
    calc.do(comm=comm, work_dir="./MoS2")
    if rank == 0:
      H = calc.hamiltonian     # AimspyMatrix (block-sparse, Hartree, rank-0 only)
    E = calc.energy          # float (Hartree)

Run with MPI:

mpiexec -np 8 python script.py

Note: Matrix extraction and injection (e.g. warmstart, overlap/H0 capture) require a periodic system with use_local_index = .false. in control.in. Forward SCF works with any system type. For isolated molecules, use a large periodic cell with vacuum. See the examples.

DeepH export export converged matrices to DeepH format:

from mpi4py import MPI
from aimspy import Calculator, CalculatorConfig
from aimspy import DeepHData

comm = MPI.COMM_WORLD
rank = comm.rank

config = CalculatorConfig(
    lib_path="/path/to/libaims.so",
    capture_initial_hamiltonian=True,  # capture free-atom H0
)
with Calculator(config) as calc:
    calc.do(comm=comm, work_dir="./MoS2")

    # Export H, S, H0 to DeepH on-disk format
    if rank == 0:
      dd = DeepHData.from_aimspy(
          calc.structure,
          hamiltonian=calc.hamiltonian,
          overlap=calc.overlap,
          initial_hamiltonian=calc.initial_hamiltonian,
      )
      dd.save("deeph_out/")

Optionally export forces and total energy to force.h5 (MD-style format):

if rank == 0:
    dd = DeepHData.from_aimspy(
        calc.structure,
        hamiltonian=calc.hamiltonian,
        overlap=calc.overlap,
        initial_hamiltonian=calc.initial_hamiltonian,
        force=calc.forces,    # (n_atoms, 3) eV/Å, aims order
        energy=calc.energy,   # Hartree, auto-converted to eV
    )
    dd.save("deeph_out/")    # writes force.h5 alongside H/S/H0

Note: For the DeepH on-disk data format specification (POSCAR, info.json, .h5 files), see DeepH-dock Key Concepts.

DeepH warmstart inject a pre-trained Hamiltonian as the initial guess:

from mpi4py import MPI
from aimspy import Calculator, CalculatorConfig, Strategy
from aimspy import DeepHData

data = DeepHData.from_directory("deeph_out/")
config = CalculatorConfig(lib_path="/path/to/libaims.so")
calc = Calculator(config)
calc.modify_init_ham(source=data, strategy=Strategy.REPLACE)
calc.do(comm=MPI.COMM_WORLD, work_dir="./MoS2")

Grid data capture export converged density and potentials on the real-space integration grid:

from mpi4py import MPI
from aimspy import Calculator, CalculatorConfig

comm = MPI.COMM_WORLD
rank = comm.rank

config = CalculatorConfig(
    lib_path="/path/to/libaims.so",
    capture_grid_data=True,  # capture real-space grid data
)
with Calculator(config) as calc:
    calc.do(comm=comm, work_dir="./MoS2")
    if rank == 0:
        gd = calc.grid_data           # GridData object
        gd.save_npz("grid.npz")       # save for offline analysis
        print(f"delta_rho range: {gd.delta_rho.min():.3e} .. {gd.delta_rho.max():.3e}")

NAO radial basis capture export the full cubic-spline representation of the radial basis functions (u(r), kinetic, du/dr + log-grid parameters), then build an incremental basis.h5 library and plot it offline:

config = CalculatorConfig(
    lib_path="/path/to/libaims.so",
    capture_basis_data=True,  # export NAO radial basis splines
)
with Calculator(config) as calc:
    calc.do(comm=comm, work_dir="./MoS2")
    if rank == 0:
        bd = calc.basis_data
        u = bd.evaluate_u(0, [0.5, 1.0, 2.0])  # u(r) at r in bohr
        bd.save_h5("basis.h5", calc.info)      # element-per-group library

aimspy viz-basis basis.h5 -o figures/   # offline plotting, no libaims needed

For more information on deferred source, overlap capture, error recovery, and the full API, see Basic Usage and API Reference.

Citation

Since AimsPy is part of the DeepH ecosystem and drives FHI-aims calculations, we recommend citing the following papers:

1. DeepH-pack — the complete package featuring the latest implementation, methodology, and workflow of DeepH:

Yang Li, Yanzhen Wang, Boheng Zhao, et al. DeepH-pack: A general-purpose neural network package for deep-learning electronic structure calculations. arXiv:2601.02938 (2026)

@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):

[Authors]. [Title]. [Journal], in publishing.

3. FHI-aims — the original FHI-aims paper, since AimsPy drives FHI-aims calculations:

Volker Blum, Ralf Gehrke, Felix Hanke, Paula Havu, Ville Havu, Xinguo Ren, Karsten Reuter, Matthias Scheffler. Ab initio molecular simulations with numeric atom-centered orbitals. Computer Physics Communications 180(11), 2175–2196 (2009)

@article{BLUM20092175,
    title = {Ab initio molecular simulations with numeric atom-centered orbitals},
    journal = {Computer Physics Communications},
    volume = {180},
    number = {11},
    pages = {2175--2196},
    year = {2009},
    issn = {0010-4655},
    doi = {https://doi.org/10.1016/j.cpc.2009.06.022},
    url = {https://www.sciencedirect.com/science/article/pii/S0010465509002033},
    author = {Volker Blum and Ralf Gehrke and Felix Hanke and Paula Havu and Ville Havu and Xinguo Ren and Karsten Reuter and Matthias Scheffler},
    keywords = {molecular simulations, Density-functional theory, Atom-centered basis functions, Hartree--Fock, MP2, O(N) DFT, self-energy}
}

Application Scenarios

• DeepH Training Data Generation: Run baseline SCF and export to the DeepH on-disk format (POSCAR + info.json + .h5) in a single pipeline.
• DeepH Warmstart: Inject a pre-trained DeepH Hamiltonian as the initial guess and converge SCF in several iterations, enabling rapid downstream property evaluation.
• FHI-aims Post-Processing: Extract converged Hamiltonian, overlap, and free-atom H_init matrices in the standard AimspyMatrix format for analysis or conversion.
• Electronic Structure Analysis: Extract converged density and potentials on the real-space grid for bonding analysis, charge transfer visualization, and potential landscape plotting.
• Method Development: Prototype new initial-guess strategies via the Strategy.CUSTOM hook, or plug in alternative DFT backends by implementing the ExternalMatrixSource protocol.

Contributing

We welcome contributions from the community! AimsPy is built with a layered architecture (public API → callback framework → ctypes binding → FHI-aims patch), and extension points are deliberately narrow and well-documented.

Common contribution targets:

• New external matrix sources implement the ExternalMatrixSource protocol in a new subpackage under aimspy/interface/<your_format>/.
• New callback hook points follow the extension contract documented in the Development Guide.
• New modification strategies extend the Strategy enum and the _apply_strategy dispatcher.

For the complete development workflow, code style, testing requirements, and pull request process, see the Development Guide and Collaboration Guide.

make install    # create .venv, install editable with dev deps
make test       # run unit tests (pytest -v)
make lint       # ruff check + black --check
make build      # build sdist + wheel

License

This project is licensed under GPL-3.0-or-later. See the LICENSE file for details.

FHI-aims itself is not distributed with AimsPy and remains under its own licence agreement with the aims team. Users must obtain FHI-aims source code independently.

Support & Contact

• 📖 Documentation: https://docs.deeph-pack.com/aimspy/en/latest/
• 🐛 Issue Reporting: GitHub Issues

---

AimsPy is the FHI-aims binding layer of the DeepH ecosystem, aiming to promote openness and reproducibility in computational materials science research.