<p align="center"> <img height="130" src="logo/logo.png"/> </p>

🚀 HamGNN v2.1 Now Available!

Getting Started with HamGNN: Online Documentation

Table of Contents

• 1. Introduction to HamGNN
• 2. Environment Configuration Requirements
  • Python Environment
  • Third-party DFT Tool Support
  • Compiling openmx_postprocess and read_openmx
• 3. HamGNN Installation Steps
  • Step One: Install Conda Environment
  • Step Two: Install HamGNN from Source
• 4. Construction Method for graph_data.npz Files
  • General Process
  • OpenMX Process
  • SIESTA/HONPAS Process
  • ABACUS Process
• 5. Model Training Process
  • Training Mode Classification
  • Training Commands
  • Key Configuration Item Descriptions
  • Training Monitoring
• 6. Model Prediction Operations
  • Preparation Before Prediction
  • Execute Prediction
  • Output Results
• 7. Band Structure Calculation
  • Operation Process
  • Band Calculation for Large Systems
• 8. Introduction to and Usage of Uni-HamGNN Universal Model
  • Model Introduction
  • Input Requirements
  • Usage Process
  • Output Results
• 9. HamGNN Parameter Details
  • setup (Basic Settings)
  • dataset_params (Dataset Parameters)
  • losses_metrics (Loss Functions and Evaluation Metrics)
  • optim_params (Optimizer Parameters)
  • output_nets.HamGNN_out (Output Network Parameters)
  • representation_nets.HamGNN_pre (Representation Network Parameters)
  • Parameter Adjustment Recommendations
• References
• Code contributors
• Project leaders

1. Introduction to HamGNN

HamGNN (Hamiltonian Graph Neural Network) is an E(3) equivariant graph neural network framework designed specifically for quantum materials simulation. Its core functionality is to train and predict ab initio tight-binding Hamiltonians, which are fundamental quantum mechanical operators describing the electronic structure of materials.

Key features of HamGNN include:

• Support for a wide range of physical scenarios: Applicable to molecules, solids, and multi-dimensional material systems with Spin-Orbit Coupling (SOC) effects, capable of handling structures from zero to three dimensions.
• Compatibility with multiple DFT software: Supports integration with mainstream density functional theory software based on Numerical Atomic Orbitals (NAO), including OpenMX, SIESTA/HONPAS, and ABACUS.
• Theoretical foundation: Employs a graph neural network architecture with E(3) rotational and translational equivariance, ensuring the predicted Hamiltonian matrices satisfy fundamental physical symmetries.
• High fidelity: Capable of approximating density functional theory (DFT) calculation results with high precision, while maintaining good cross-material structure prediction capabilities.
• Computational efficiency: Significantly improves computational efficiency for large-scale systems (such as systems containing thousands of atoms) compared to traditional DFT methods.

HamGNN's application domains primarily focus on high-throughput material design and discovery, large-scale electronic structure calculations, and quantum material property predictions, providing an efficient research tool for materials science, condensed matter physics, and computational chemistry.

According to recent research advances, HamGNN has been extended to a universal model called Uni-HamGNN, which can predict spin-orbit coupling effects across the periodic table without the need for retraining for new material systems, significantly accelerating the discovery and design process of quantum materials.

2. Environment Configuration Requirements

Python Environment

The HamGNN framework recommends 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

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 methods. Available for download from OpenMX official website.
• openmx_postprocess: This is a modified version of OpenMX used to parse calculated 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 calculated overlap matrices and non-self-consistent Hamiltonian matrices H0, similar to the openmx_postprocess tool. The output is a binary file containing Hamiltonian data (overlap.HSX).
• hsxdump: This is a binary executable that generates intermediate Hamiltonian 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, execute make to generate the executable programs: openmx_postprocess and read_openmx.

3. HamGNN Installation Steps

Step One: Install Conda Environment

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

Method 1: Use Pre-built Environment (Recommended)

1. Download the pre-built HamGNN Conda environment (ML.tar.gz) from Zenodo
2. Extract it to the envs folder in your Conda installation directory:

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

3. Activate the environment:

   conda activate ML
   

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
   

Step Two: Install HamGNN from Source

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 that the installation was successful:

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

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

   pip uninstall HamGNN
   

   Ensure that related 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.

4. Construction Method for graph_data.npz Files

graph_data.npz is the core input format for HamGNN, containing material structure information and Hamiltonian matrix data. Below is an introduction to its construction method.

General Process

Regardless of which DFT software is used, the basic process for constructing graph_data.npz is as follows:

1. Structure File Conversion: Convert material structure files (such as POSCAR, CIF) to the input format of the corresponding DFT software
2. Non-self-consistent Hamiltonian Calculation: Use post-processing tools to generate files containing non-self-consistent Hamiltonian H0 (matrices that do not depend on self-consistent charge density, such as kinetic energy matrices)
3. DFT Calculation (optional): Run a complete DFT calculation to obtain the true Hamiltonian (needed for training set construction, can be skipped for pure prediction)
4. Data Packaging: Call the adapted graph_data_gen script to package the structure and Hamiltonian matrix data into graph_data.npz

OpenMX Process

1. Structure Conversion: Edit the poscar2openmx.yaml configuration file, set appropriate paths and DFT parameters (for non-SOC data, set scf.SpinPolarization: Off and scf.SpinOrbit.Coupling: off; for SOC data, set scf.SpinPolarization: nc and scf.SpinOrbit.Coupling: on):

   system_name: 'Si'
   poscar_path: "/path/to/poscar/*.vasp" # Path to POSCAR or CIF files
   filepath: '/path/to/save/dat/file' # Directory to save OpenMX files
   basic_command: |+  # OpenMX calculation parameters
     #