Skip to content

2. Installation

In this part, we introduce how related packages for running DeepH@FHI-aims interface could be installed.

2.0. Prerequisites: Conda environment setup

Begin by configuring conda environment, an industry-standard package management system. For optimal performance, we officially recommend the following steps:

  • Install miniconda
  • Create python 3.13 environment with conda:
conda create -n deeph python=3.13
conda activate deeph

2.1. Installing FHI-aims for Atomic Simulation Interface (ASI) usage

The current DeepH@FHI-aims interface is built upon a dedicated Python package, Atomic Simulation Interface (ASI), which is responsible for extracting the electronic Hamiltonian from FHI-aims. ASI executes FHI-aims through Python calls, utilizing an FHI-aims build compiled as a shared library.

To compile FHI-aims as a shared library, you could simply add the following line in your initial_cache.cmake:

set(BUILD_SHARED_LIBS ON CACHE STRING "")

and compile as usual.

If the comilation succeeds, you'll see a library file such as libaims.240507.scalapack.mpi.so in your build directory. The current interface has been tested with FHI-aims' 240507 version.

2.2. Installing DeepH@FHI-aims interface

The DeepH@FHI-aims interface is available from the zenodo repository. For interface usage, you could only download and unzip the aims2DeepH.zip, which is much smaller than the demo dataset.

To facilitate DeepH@FHI-aims interface, several python packages are mandatory. The necessary versions of the key packages are:

  • python 3.9
  • asi4py 1.3.2
  • scalapack4py 0.0.7
  • h5py 3.11.0

Please note that:

  1. Remember to modify the "prefix" entry to the directory you want to install the anaconda environment.
  2. Most package versions are flexible, but it's highly recommended to use the specific asi4py version provided.
  3. You should create a Python environment called aims2deeph that is separate from the one used for DeepH training in the following section.
  4. For your convenience, we have attached an example aims2deeph.yaml, from which you may be able to setup the environment with a single command conda env create --name aims2deeph -f aims2deeph.yaml

CPU and GPU setups

Since FHI-aims typically runs on CPUs whereas DeepH training benefits from GPUs, it is often convenient to install the FHI-aims (and interface) components and the DeepH components on separate servers. In practice, you could generate datasets on CPU servers, transfer them to GPU servers, and then perform the training there.

Install DeepH-pack

Note

In the tutorial, we use a re-constructed DeepH-pack version to be released. Please do not confuse this with the current open-sourced DeepH-pack.

Important

In this step, you should create a new Python environment called deeph that is separate from the one used for data transformation (aims2deeph) in the previous section.

Once the package access petition is granted, you will receive a file named deepx-x.x.x+xxx-py3-none-any.whl. You can install the DeepH-pack into the deeph conda environment:

python -m pip install deepx-x.x.x+xxx-py3-none-any.whl

After the DeepH-pack is successfully installed, use the following command to configure the environment and you are ready to go. Note that, DeepH installs GPU-dependencies by default. If GPU hardware is unavailable, you may install the CPU environment to perform standard model training and inference.

# For GPU-like hardware
DEEPH-env --install
# For CPU hardware
DEEPH-env --install --cpu

We strongly recommend running DeepH on GPU/TPU/DCU hardware, as its core algorithms are optimized for GPU-like architectures.

Install DeepH-dock

DeepH-dock provides comprehensive APIs and post-processing utilities for DeepH-pack, including but not limited to material structure search/generation, dataset format conversion, dataset feature analysis, and electronic structure post-processing. This package is currently under active development and will be officially open-sourced upon completion. While deepx_dock is in beta stage, you can ask for the wheel installation package from the developers. Upon receiving it, you can install it as usual with pip:

python -m pip install deepx_dock-x.x.x-py3-none-any.whl

Note

During the DeepH-pack installation process, an internet connection is required. If your machine operates in an offline environment, you may transfer the environment using methods such as conda pack.

Note

You may have noticed that all DeepH installation packages are currently named deepx. This is deliberate, as we aim to prevent user confusion between this brand-new JAX-based public release version and previously developed experimental programs (such as DeepH-E3), whose packages are named deeph, upon future releases.