Environment Configuration and Installation

Python Environment

HamGNN framework recommends using Python 3.9 and depends on the following key Python libraries:

• numpy == 1.21.2

• PyTorch == 1.11.0

• PyTorch Geometric == 2.0.4

• pytorch_lightning == 1.5.10

• e3nn == 0.5.0

• pymatgen == 2022.3.7

• tensorboard == 2.8.0

• tqdm

• scipy == 1.7.3

• yaml

• lmdb (required for HamGNN v2.1+, used for LMDB dataset format support)

Third-party DFT Tool Support

OpenMX

• OpenMX: HamGNN requires tight-binding Hamiltonians generated by OpenMX. Users should be familiar with basic OpenMX parameter settings and usage. It can be downloaded from the OpenMX official website.

• openmx_postprocess: This is a modified version of OpenMX used to parse and compute overlap matrices and other Hamiltonian matrices. It stores computational data in a binary file named overlap.scfout.

• read_openmx: This is a binary executable used to export matrices from the overlap.scfout file to HS.json.

SIESTA/HONPAS

• honpas_1.2_H0: This is a modified version of HONPAS used to parse and compute overlap matrices and non-self-consistent Hamiltonian matrices H0, similar to the openmx_postprocess tool. The output is a binary file (overlap.HSX) containing Hamiltonian data.

• hsxdump: This is a binary executable that generates Hamiltonian intermediate files, essential for converting HONPAS output to HamGNN-readable format.

ABACUS

• abacus_postprocess: A tool used to export Hamiltonian matrices H0.

Compiling openmx_postprocess and read_openmx

To install openmx_postprocess:

1. First, install the GSL library.

2. Modify the makefile in the openmx_postprocess directory:

   • Set GSL_lib to the path of the GSL library.

   • Set GSL_include to the include path of GSL.

   • Set MKLROOT to the Intel MKL path.

   • Set CMPLR_ROOT to the Intel compiler path.

After modifying the makefile, run make to generate the executables: openmx_postprocess and read_openmx.

HamGNN Installation Steps

Step One: Install Conda Environment

To avoid dependency library version conflicts, it is recommended to use one of the following two methods:

Method 1: Using Pre-built Environment (Recommended)

1. Download the pre-built HamGNN Conda environment (ML.tar.gz) from Zenodo

2. Extract it to the envs folder under your Conda installation directory:

   tar -xzvf ML.tar.gz -C $HOME/miniconda3/envs/
   

3. Activate the environment:

   conda activate ML
   

   Note

   For HamGNN v2.1+ Users: Starting from v2.1, HamGNN requires the lmdb library for LMDB dataset format support (enables faster I/O for large datasets). The pre-built environment from Zenodo may not include it. Install it manually after activating:

   pip install lmdb
   

Method 2: Create Environment Using Configuration File

1. Create an environment using the YAML configuration file provided by HamGNN:

   conda env create -f ./HamGNN.yaml
   

   Note

   lmdb will be installed automatically when using Method 2.

2. Install additional PyTorch Geometric dependencies (versions must match PyTorch):

   pip install torch-scatter==2.1.2+pt25cu121 torch-sparse==0.6.18+pt25cu121 -f https://data.pyg.org/whl/torch-2.5.1+cu121.html
   

   Note

   The version numbers in the link need to match your actual PyTorch and CUDA versions

Step Two: Source Installation of HamGNN

1. Clone the HamGNN repository:

   git clone https://github.com/QuantumLab-ZY/HamGNN.git
   

2. Enter the HamGNN directory and execute the installation:

   cd HamGNN
   python setup.py install
   

3. Verify successful installation:

   python -c "import hamgnn; print('HamGNN installed successfully')"
   

4. To upgrade HamGNN version, first uninstall the old version:

   pip uninstall HamGNN
   

   Make sure files in the site-packages directory (such as HamGNN-x.x.x-py3.9.egg/HamGNN) have been completely removed, then reinstall the new version.