Chemistry-aware, auditable sparsification of over-complete QMOF atomic graphs.
Code: https://github.com/MehrdadJalali-AI/Atomic_Black_Hole
Dataset: https://doi.org/10.5281/zenodo.20204816
Metal–organic frameworks (MOFs) in the Quantum MOF (QMOF) database are commonly represented as atomistic graphs: nodes are atoms and edges encode proximity or bonding relationships used for graph neural network (GNN) learning. A permissive distance-cutoff construction is standard for computational convenience, but it can yield over-complete graphs with many weak, redundant, or chemically uninformative edges.
Atomic Black Hole (ABH) and CrystalNN-aware ABH (CD-ABH) sparsify these graphs while aiming to preserve connectivity, covalent/coordination/metal–ligand interactions, and metal-center neighborhoods.
This GitHub repository provides source code, configuration files, plotting scripts, manuscript support materials, and lightweight metadata needed to reproduce the workflow. Large processed graph datasets are hosted on Zenodo, not in this repository (see Dataset access).
ABH is intra-MOF edge pruning, not dataset-level MOF subsampling. Sparsified outputs are QMOF-derived graph views—the crystal identity, composition, and target labels are unchanged; only the computational edge set is modified.
The large QMOF-derived sparsified graph-view datasets are not stored in this GitHub repository. They are available from Zenodo:
https://doi.org/10.5281/zenodo.20204816
The Zenodo record includes processed/sparsified graph views (PyTorch Geometric .pt bundles), fixed train/validation/test splits, edge-level audit logs, benchmark tables, runtime/memory summaries, checksums, and dataset documentation (README_dataset.md).
Raw QMOF structures are not redistributed in this repository or in the derived Zenodo package. Obtain raw QMOF data from the official QMOF source under its terms of use.
# Download the dataset package manually from Zenodo:
# https://doi.org/10.5281/zenodo.20204816
# After downloading and extracting:
cd ABH_QMOF_sparsified_graph_views
python scripts/verify_package.py
shasum -a 256 -c checksums/SHA256SUMS.txt # optional integrity checkSee also DATASET_CARD.md for a short dataset summary.
| Component | Location |
|---|---|
| Graph construction & QMOF loading | src/graphs/, src/data/ |
| ABH / CD-ABH sparsification | src/sparsification/ |
| Baseline pruning | src/sparsification/baselines.py |
| GNN backbones & benchmarks | src/models/, src/experiments/ |
| Experiment configs | configs/ |
| Plotting / figure scripts | src/plotting/ |
| Lightweight splits & manifests | data/splits/, data/processed/*.csv (no .pt in git) |
| Example benchmark tables | results/tables/ |
| Reproducibility reports | reports/ |
| Zenodo package builder (local) | zenodo_upload/ |
The Zenodo deposit (DOI 10.5281/zenodo.20204816) contains:
- Original over-complete distance-cutoff graph views (4.5 Å)
- ABH graph views at τ = 0.1, 0.2, 0.3
- CD-ABH graph views at τ = 0.1, 0.2, 0.3
- Baseline graph views (random, distance, and additional pruning baselines where bundled)
- Fixed splits for seeds 42, 52, 62, 72, 82
- Edge-level audit logs and metal-center preservation traces
- Benchmark tables (predictive performance, chemistry retention, screening, runtime/memory)
- Checksums and
README_dataset.md
Random-chemistry, distance-chemistry, and DropEdge results may appear in benchmark tables; some static .pt bundles are documented as optional/regenerable in the Zenodo package README.
| Term | Role |
|---|---|
| gravity | Retention signal for structurally important local anchors |
| bridge | Connectivity / bridge-preservation signal |
| chemistry | Protection of covalent, coordination, and metal–ligand contacts |
| CrystalNN | Local-structure support (CD-ABH) |
| redundancy | Penalty for weak or redundant cutoff-only edges |
git clone https://github.com/MehrdadJalali-AI/Atomic_Black_Hole.git
cd Atomic_Black_Hole
python -m venv .venv
source .venv/bin/activate # macOS / Linux
pip install -U pip
pip install -r requirements.txtConfigure local QMOF paths in configs/default.yaml if regenerating graphs from CIFs.
With Zenodo data (recommended): download and extract the dataset, then load .pt files as described in the Zenodo README_dataset.md.
Regenerate from QMOF (optional):
python src/experiments/run_smoke_test.py --config configs/smoke_test.yaml
python src/data/build_qmof_graphs.py --config configs/default.yaml --mode medium
python src/experiments/run_full_benchmark.py --config configs/benchmark_1000.yaml --mode quick --run-id my_runRegenerate figures from validated CSV tables:
export MANUSCRIPT_RUN_DIR=results/runs/run_1000_quick_fitfix_20260514_1129
python src/plotting/plot_main_figures.py
python src/plotting/plot_supplementary_figures.pyAtomic_Black_Hole/
├── README.md
├── DATASET_CARD.md
├── CITATION.cff
├── requirements.txt
├── configs/
├── data/
│ ├── splits/ # lightweight split CSVs (in git)
│ └── processed/ # *.csv manifests only in git; *.pt on Zenodo
├── src/
├── results/tables/
├── manuscript/
├── reports/
└── zenodo_upload/ # local builder for Zenodo package (optional)
If you use this work, please cite:
- The manuscript: Atomic Black Hole Sparsification for Chemistry-Aware Frugal Learning on QMOF Graphs (update venue/year when published).
- The dataset: https://doi.org/10.5281/zenodo.20204816
- The QMOF database: Rosen et al., Matter 4, 1578–1597 (2021).
See CITATION.cff for machine-readable metadata.
Source code: see LICENSE in the repository root when present.
Zenodo dataset: CC BY 4.0 (see Zenodo record).