HopCP Interface

HopCP Interface#

Overview#

The HopCP Interface is a conversion utility that transforms DeepH-format Hamiltonian data into the PETSc (Portable, Extensible Toolkit for Scientific Computation) binary format. This format is designed for use with HopCP, a library developed by the DeepH team for processing ultra-large-scale sparse Hamiltonians, and is fully open-sourced now. PETSc is a powerful suite of data structures and routines for scalable scientific computations, particularly useful for large-scale sparse matrix operations in quantum chemistry and materials science applications.

Background and Motivation#

The DeepH & HopCP Ecosystem#

One of DeepH’s key innovations is its ability to predict Hamiltonians for ultra-large-scale structures through training on smaller configurations—scaling physical insights from nano to macro scales. However, obtaining the Hamiltonian is only the first step; transforming these quantum mechanical descriptions into practical material properties requires specialized computational tools.

HopCP was developed to address precisely this need. As a successor to the HopTB software package, HopCP leverages C++ with PETSc and SLEPc libraries to provide high-performance computational capabilities for processing ultra-large sparse Hamiltonians. This complete re-engineering enables efficient calculations of electronic, optical, and response properties at unprecedented scales.

Why PETSc?#

PETSc (Portable, Extensible Toolkit for Scientific Computation) provides:

  • Scalability: Efficient parallel processing for distributed-memory systems

  • Flexibility: Comprehensive linear algebra and eigenvalue solvers

  • Interoperability: Seamless integration with various scientific computing workflows

Installation#

Installing PETSc#

To install PETSc with the appropriate configuration for HopCP, use:

dock convert hopcp how-to-install-petsc

This command generates a customized installation template with optimal settings for Hamiltonian computations. The template includes:

  • Recommended compilation flags for maximum performance

  • Required dependency configurations

  • Platform-specific optimization settings

Example output:

[done] PETSc installation template created successfully!
Created: ./PETSc
Review the template and run: make

File Structure#

Input: DeepH Data Structure#

DeepH-format data should be organized in the following directory structure:

deeph_data/
├── data_directory_1/
│   ├── hamiltonians.h5    # Hamiltonian matrices in HDF5 format
│   ├── overlaps.h5        # Overlap matrices in HDF5 format
│   ├── info.json          # Structural and computational metadata
│   └── POSCAR             # Atomic structure information
├── data_directory_2/
│   └── ...
└── ...

Output: PETSc Data Structure#

The converter generates PETSc-compatible files with the following structure:

PETSc_data/
├── data_directory_1/
│   ├── HR.petsc           # Hamiltonian in realspace (PETSc binary)
│   ├── SR.petsc           # Overlap matrix in realspace (PETSc binary)
│   └── misc.toml          # Additional configuration and metadata
├── data_directory_2/
│   └── ...
└── ...

Command Line Interface#

Basic Conversion#

Convert DeepH format to PETSc format using:

dock convert hopcp from-deeph ./deeph_data /tmp/petsc_data -p 2

Example output:

Data: 2it [00:01,  1.06it/s]
[done] DeepH to PETSc conversion completed successfully!

Complete Command Line Options#

For detailed parameter information:

dock convert hopcp from-deeph -h

Usage: dock convert hopcp from-deeph [OPTIONS] DEEPH_DIR PETSC_DIR

  Convert DeepH h5 data files to PETSc format

Options:
  --ignore-S                  Do not export SR.petsc
  --ignore-H                  Do not export HR.petsc
  -p, --parallel-num INTEGER  The parallel processing number, -1 for using all of the cores.
                              [default: -1]
  -t, --tier-num INTEGER      The tier number of the source data, -1 for [deeph_dir], 0 for
                              <deeph_dir>/[data_dirs], 1 for <deeph_dir>/<tier1>/[data_dirs], etc.
                              [default: 0]
  --force                     Force to overwrite the existing files.
  -h, --help                  Show this message and exit.

Advanced Usage: Python Class API#

For programmatic access within Python scripts, you can use the DeepHtoPETScTranslator class:

from deepx_dock.convert.hopcp.translate_deeph_to_petsc import DeepHtoPETScTranslator

transfer = DeepHtoPETScTranslator(
    deeph_dir="./deeph_data",
    petsc_dir="/tmp/petsc_data",
    n_jobs=1,
)
transfer.transfer_all_deeph_to_petsc()

Data: 0it [00:00, ?it/s]

Integration with HopCP Workflow#

# Step 1: Convert DeepH data to PETSc format
dock convert hopcp from-deeph ./deeph_data ./petsc_data -p 2

# Step 2: Run HopCP calculations
/home/deeph/bin/hopcp config.toml

Best Practices#

For Optimal Performance#

  1. Pre-conversion: Validate DeepH data consistency before conversion

  2. Parallelization: Match -p parameter to available CPU cores

  3. Storage: Use high-speed storage (NVMe) for large datasets

  4. Verification: Always verify converted PETSc files before long computations

Data Management#

# Recommended directory structure
project/
    ├── deeph_data/          # Original DeepH datasets
    ├── petsc_data/          # Converted PETSc files
    └── hopcp_outputs/       # Computation results

Community and Support#

Getting Help#

Contributing#

We welcome contributions to enhance the Hopcp Interface:

  • Support for additional matrix formats

  • Performance optimizations

  • Extended metadata capabilities

Reporting Issues#

When reporting issues, please include:

  1. Conversion command and parameters used

  2. System specifications (CPU, memory, OS)

  3. Sample data or error logs

  4. PETSc version information

The HopCP Interface bridges the gap between DeepH’s predictive power and HopCP’s computational capabilities, enabling researchers to translate quantum mechanical insights into practical material properties at unprecedented scales. This integration represents a significant advancement in high-throughput computational materials science.

Contents