# xiaoxun-gong/deeph-e3 architecture

> Architecture diagram of the GitHub repository xiaoxun-gong/deeph-e3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiaoxun-gong/deeph-e3
- Repository: https://github.com/xiaoxun-gong/deeph-e3

## Overview

DeepH-E3 predicts electronic-structure Hamiltonians from material structures. The principal workflow converts DFT data into crystal graphs, trains an E(3)-equivariant model, then evaluates structures to produce predicted Hamiltonians; overlap data can support inference for large structures. Separate capabilities include target analysis, OpenMX preprocessing, and sparse band-structure calculation and visualization. The graph follows the README and source-index references; some CLI-to-kernel and downstream-tool wiring is not shown in the excerpts, so those links are marked unverified or omitted.

Main entry points: [`deephe3/kernel.py`](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/kernel.py) (Training and inference), [`deephe3/model.py`](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/model.py) (Equivariant network), [`deephe3/data.py`](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/data.py) (Dataset processing), [`deephe3-preprocess.py`](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-preprocess.py) (Preprocess CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Model workflow"]
  node_preprocess_cli["Preprocess CLI"]
  node_train_cli["Train CLI<br/>[deephe3-train.py]"]
  node_eval_cli["Evaluation CLI<br/>[deephe3-eval.py]"]
  node_config["Config parsing<br/>[parse_configs.py]"]
  node_kernel["Training and inference<br/>[kernel.py]"]
  node_utils["Training utilities<br/>[utils.py]"]
end

subgraph group_engine["Equivariant engine"]
  node_model["Equivariant network<br/>[model.py]"]
  node_tensor["Tensor operations<br/>[e3modules.py]"]
  node_basis["Radial and angular bases<br/>[basis_utils.py]"]
  node_cutoff["Distance cutoff<br/>[cutoffs.py]"]
  node_radial["Bessel basis<br/>[radial_basis.py]"]
  node_tp["Tensor-product paths<br/>[tp_utils.py]"]
  node_gaussian["Gaussian basis<br/>[acsf.py]"]
end

subgraph group_io["Data preparation"]
  node_preprocess["OpenMX parser<br/>[process_data.py]"]
  node_dataset["Dataset processing<br/>[data.py]"]
  node_graph["Crystal graph<br/>[graph.py]"]
  node_lattice["Lattice neighbors<br/>[lattice.py]"]
end

subgraph group_analysis["Analysis tools"]
  node_analyze_cli["Analyze CLI<br/>[deephe3-analyze.py]"]
  node_target_cli["Target analysis"]
  node_analyzer["Result analyzer<br/>[analyzer.py]"]
  node_sparse["Sparse band calculation<br/>[sparse_calc.jl]"]
  node_sparse_pardis["Pardiso band calculation"]
  node_visual["Band visualization<br/>[plot_band.py]"]
  node_visual_compare["Band comparison<br/>[compare_bands.py]"]
end

node_dft(("DFT data"))
node_overlap["Overlap data"]
node_hamiltonian["Predicted Hamiltonians"]

node_dft -->|"provides input"| node_preprocess_cli
node_preprocess_cli -.->|"converts data"| node_preprocess
node_preprocess_cli -.->|"prepares dataset"| node_dataset
node_train_cli -.->|"reads config"| node_config
node_eval_cli -.->|"reads config"| node_config
node_preprocess_cli -.->|"reads config"| node_config
node_dataset -->|"builds graphs"| node_graph
node_graph -->|"finds neighbors"| node_lattice
node_kernel -->|"loads data"| node_dataset
node_kernel -->|"uses graphs"| node_graph
node_kernel -->|"loads model"| node_model
node_kernel -->|"uses config"| node_config
node_kernel -->|"registers constructor"| node_tensor
node_dataset -->|"decomposes targets"| node_tensor
node_model -->|"uses operations"| node_tensor
node_model -->|"uses cutoff"| node_cutoff
node_model -->|"uses basis"| node_radial
node_model -->|"checks paths"| node_tp
node_model -->|"uses basis"| node_gaussian
node_dataset -->|"processes targets"| node_utils
node_kernel -->|"uses utilities"| node_utils
node_analyze_cli -.->|"runs analysis"| node_analyzer
node_analyzer -->|"analyzes results"| node_kernel
node_target_cli -.->|"analyzes targets"| node_utils
node_eval_cli -->|"reads for inference"| node_overlap
node_eval_cli -->|"produces predictions"| node_hamiltonian
node_hamiltonian -->|"supports diagonalization"| node_sparse
node_hamiltonian -.->|"supports diagonalization"| node_sparse_pardis
node_sparse -.->|"yields band data"| node_visual
node_visual -.->|"compares bands"| node_visual_compare

click node_preprocess_cli "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-preprocess.py"
click node_preprocess "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/process_data_tools/process_data.py"
click node_train_cli "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-train.py"
click node_eval_cli "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-eval.py"
click node_analyze_cli "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-analyze.py"
click node_target_cli "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-target_analysis.py"
click node_config "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/parse_configs.py"
click node_dataset "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/data.py"
click node_graph "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/graph.py"
click node_lattice "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_pymatgen/lattice.py"
click node_kernel "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/kernel.py"
click node_model "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/model.py"
click node_tensor "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/e3modules.py"
click node_basis "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_dimenet/basis_utils.py"
click node_cutoff "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/cutoffs.py"
click node_radial "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/radial_basis.py"
click node_tp "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/tp_utils.py"
click node_gaussian "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_schnetpack/acsf.py"
click node_utils "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/utils.py"
click node_analyzer "https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/analyzer.py"
click node_sparse "https://github.com/xiaoxun-gong/deeph-e3/blob/main/inference_tools/sparse_calc.jl"
click node_sparse_pardis "https://github.com/xiaoxun-gong/deeph-e3/blob/main/inference_tools/sparse_calc_pardis.jl"
click node_visual "https://github.com/xiaoxun-gong/deeph-e3/blob/main/visual_tools/plot_band.py"
click node_visual_compare "https://github.com/xiaoxun-gong/deeph-e3/blob/main/visual_tools/compare_bands.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_preprocess_cli,node_train_cli,node_eval_cli,node_config,node_kernel,node_utils toneBlue
class node_model,node_tensor,node_basis,node_cutoff,node_radial,node_tp,node_gaussian toneAmber
class node_preprocess,node_dataset,node_graph,node_lattice toneMint
class node_analyze_cli,node_target_cli,node_analyzer,node_sparse,node_sparse_pardis,node_visual,node_visual_compare toneRose
class node_dft,node_overlap,node_hamiltonian toneIndigo
```

## Components

### Model workflow

- [Preprocess CLI](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-preprocess.py): `deephe3-preprocess.py`
- [Train CLI](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-train.py): `deephe3-train.py`
- [Evaluation CLI](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-eval.py): `deephe3-eval.py`
- [Config parsing](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/parse_configs.py): `deephe3/parse_configs.py`
- [Training and inference](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/kernel.py): `deephe3/kernel.py`
- [Training utilities](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/utils.py): `deephe3/utils.py`

### Equivariant engine

- [Equivariant network](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/model.py): `deephe3/model.py`
- [Tensor operations](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/e3modules.py): `deephe3/e3modules.py`
- [Radial and angular bases](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_dimenet/basis_utils.py): `deephe3/from_dimenet/basis_utils.py`
- [Distance cutoff](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/cutoffs.py): `deephe3/from_nequip/cutoffs.py`
- [Bessel basis](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/radial_basis.py): `deephe3/from_nequip/radial_basis.py`
- [Tensor-product paths](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_nequip/tp_utils.py): `deephe3/from_nequip/tp_utils.py`
- [Gaussian basis](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_schnetpack/acsf.py): `deephe3/from_schnetpack/acsf.py`

### Data preparation

- [OpenMX parser](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/process_data_tools/process_data.py): `deephe3/process_data_tools/process_data.py`
- [Dataset processing](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/data.py): `deephe3/data.py`
- [Crystal graph](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/graph.py): `deephe3/graph.py`
- [Lattice neighbors](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/from_pymatgen/lattice.py): `deephe3/from_pymatgen/lattice.py`

### Analysis tools

- [Analyze CLI](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-analyze.py): `deephe3-analyze.py`
- [Target analysis](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3-target_analysis.py): `deephe3-target_analysis.py`
- [Result analyzer](https://github.com/xiaoxun-gong/deeph-e3/blob/main/deephe3/analyzer.py): `deephe3/analyzer.py`
- [Sparse band calculation](https://github.com/xiaoxun-gong/deeph-e3/blob/main/inference_tools/sparse_calc.jl): `inference_tools/sparse_calc.jl`
- [Pardiso band calculation](https://github.com/xiaoxun-gong/deeph-e3/blob/main/inference_tools/sparse_calc_pardis.jl): `inference_tools/sparse_calc_pardis.jl`
- [Band visualization](https://github.com/xiaoxun-gong/deeph-e3/blob/main/visual_tools/plot_band.py): `visual_tools/plot_band.py`
- [Band comparison](https://github.com/xiaoxun-gong/deeph-e3/blob/main/visual_tools/compare_bands.py): `visual_tools/compare_bands.py`

### Other components

- **DFT data**
- **Overlap data**
- **Predicted Hamiltonians**

## Connections

- DFT data → Preprocess CLI: provides input (evidence: `README.md`)
- Preprocess CLI → OpenMX parser: converts data
- Preprocess CLI → Dataset processing: prepares dataset
- Train CLI → Config parsing: reads config
- Evaluation CLI → Config parsing: reads config
- Preprocess CLI → Config parsing: reads config
- Dataset processing → Crystal graph: builds graphs (evidence: `deephe3/data.py`)
- Crystal graph → Lattice neighbors: finds neighbors (evidence: `deephe3/graph.py`)
- Training and inference → Dataset processing: loads data (evidence: `deephe3/kernel.py`)
- Training and inference → Crystal graph: uses graphs (evidence: `deephe3/kernel.py`)
- Training and inference → Equivariant network: loads model (evidence: `deephe3/kernel.py`)
- Training and inference → Config parsing: uses config (evidence: `deephe3/kernel.py`)
- Training and inference → Tensor operations: registers constructor (evidence: `deephe3/kernel.py`)
- Dataset processing → Tensor operations: decomposes targets (evidence: `deephe3/data.py`)
- Equivariant network → Tensor operations: uses operations (evidence: `deephe3/model.py`)
- Equivariant network → Distance cutoff: uses cutoff (evidence: `deephe3/model.py`)
- Equivariant network → Bessel basis: uses basis (evidence: `deephe3/model.py`)
- Equivariant network → Tensor-product paths: checks paths (evidence: `deephe3/model.py`)
- Equivariant network → Gaussian basis: uses basis (evidence: `deephe3/model.py`)
- Dataset processing → Training utilities: processes targets (evidence: `deephe3/data.py`)
- Training and inference → Training utilities: uses utilities (evidence: `deephe3/kernel.py`)
- Analyze CLI → Result analyzer: runs analysis
- Result analyzer → Training and inference: analyzes results (evidence: `deephe3/analyzer.py`)
- Target analysis → Training utilities: analyzes targets
- Evaluation CLI → Overlap data: reads for inference (evidence: `README.md`)
- Evaluation CLI → Predicted Hamiltonians: produces predictions (evidence: `README.md`)
- Predicted Hamiltonians → Sparse band calculation: supports diagonalization (evidence: `README.md`)
- Predicted Hamiltonians → Pardiso band calculation: supports diagonalization
- Sparse band calculation → Band visualization: yields band data
- Band visualization → Band comparison: compares bands
