AimsPy ====== .. div:: sd-text-left sd-font-italic *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 ^^^^^^^^ .. grid:: .. grid-item:: :columns: 12 12 12 6 .. card:: Bundled FHI-aims Patch :class-card: sd-border-0 :shadow: none :class-title: sd-fs-5 .. div:: sd-font-normal ``aimspy patch`` applies, uninstalls, and lists versioned patches against an FHI-aims source tree — no manual editing. No manual code editing required. .. grid-item:: :columns: 12 12 12 6 .. card:: In-Memory SCF :class-card: sd-border-0 :shadow: none :class-title: sd-fs-5 .. div:: sd-font-normal 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. .. grid-item:: :columns: 12 12 12 6 .. card:: DeepH Export :class-card: sd-border-0 :shadow: none :class-title: sd-fs-5 .. div:: sd-font-normal 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. .. grid-item:: :columns: 12 12 12 6 .. card:: Warmstart :class-card: sd-border-0 :shadow: none :class-title: sd-fs-5 .. div:: sd-font-normal 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. .. grid-item:: :columns: 12 12 12 6 .. card:: Pluggable Matrix Sources :class-card: sd-border-0 :shadow: none :class-title: sd-fs-5 .. div:: sd-font-normal 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: .. code-block:: bash pip install aimspy AimsPy loads a *patched* ``libaims.so``. To patch an FHI-aims source tree: .. code-block:: bash 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 <./installation_and_setup.html>`_. Basic usage ^^^^^^^^^^^ AimsPy is primarily a Python API. The most common entry point is the one-shot ``Calculator.do()``: .. code-block:: python 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: .. code-block:: bash mpiexec -np 8 python script.py The ``aimspy patch`` command-line tool manages the bundled FHI-aims patch: .. code-block:: bash 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 <./basic_usage.html>`_. 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 <./citation_and_license.html>`_ page. **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) `_ .. code-block:: bibtex @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: `Volker Blum, Ralf Gehrke, Felix Hanke, et al. Ab initio molecular simulations with numeric atom-centered orbitals. Computer Physics Communications 180(11), 2175-2196 (2009) `_ ---- .. toctree:: :hidden: :maxdepth: 1 installation_and_setup basic_usage cli key_concepts api_reference for_developers/index troubleshooting citation_and_license