Track: Track2; Team name: topolab; Model: HMC

[uiharu-kazari]

HMC — Combinatorial Complex Attention Neural Network (Track 2)

Checklist

• My pull request has a clear and explanatory title.
• My pull request passes the Linting test.
• I added appropriate unit tests and I made sure the code passes all unit tests.
• My PR follows PEP8 guidelines.
• My code is properly documented, using numpy docs conventions, and I made sure the documentation renders properly.
• I linked to issues and PRs that are relevant to this PR. (none applicable — challenge submission)

Description

Paper: Hajij et al., Topological Deep Learning: Going Beyond Graph Data (arXiv:2206.00606) — Definitions 31–33 and the HMC architecture of Figure 35(b). Reference implementation: TopoModelX (HBS/HBNS/HMC).

What this PR adds

• Backbone topobench/nn/backbones/combinatorial/hmc.py — higher-order attention message passing on combinatorial complexes: HBS (intra-rank attention, Definition 32, with multi-hop m_hop support) and HBNS (inter-rank attention with forward/reverse directions, Definition 33), composed into HMCLayer/HMC following Figure 35(b) (9 attention blocks over two message-passing levels). Attention is computed only on the nonzero entries of coalesced sparse tensors — no dense N×N materialization. Docstrings cite the paper's definitions and equations throughout.
• Numerical parity with the reference: a state-dict-transfer test asserts agreement with TopoModelX's HMC within atol=1e-5. Two deliberate, documented deviations fix latent defects in the reference: (1) the HBNS reverse-attention weight split is taken at the target_out_channels boundary (the reference splits at source_out_channels, which is incorrect for unequal channels — covered by a regression test); (2) sparse_row_norm guards zero rows instead of producing NaNs.
• Wrapper topobench/nn/wrappers/combinatorial/hmc_wrapper.py routes the pipeline's incidence/adjacency/coadjacency matrices into the backbone.
• Configs (one per significant variant): configs/model/combinatorial/hmc.yaml (softmax attention normalization, the TopoModelX network default) and hmc_row_norm_attention.yaml (plain row normalization, the TopoModelX block default). out_channels: 64 states explicitly the width the challenge harness enforces.
• Tests — 29 backbone tests plus a wrapper test, 100% line coverage of both modules: manual dense recomputation of two-hop m_hop, manual unequal-channel HBNS computation pinning the reverse-split boundary, exact-value zero-row-guard tests, the TopoModelX equivalence test, gradient-flow, empty-rank-2 edge case, and invalid-argument handling.
• Pipeline test test/pipeline/test_pipeline.py registers both configs (end-to-end training on MUTAG).
• Official benchmark 2026_tdl_challenge/run_evaluation.ipynb (only the MODEL_CONFIG line changed, protected-cell hash intact) and the auto-generated outputs/2026-07-25_16-09-07/results.json: the full 72-run grid (12 regimes × 2 tasks × 3 seeds), no non-finite values. Headline in-distribution means: community-detection accuracy 0.4596, triangle-counting MSE/triangles 0.4843.
• Supplementary analysis 2026_tdl_challenge/analysis_hmc.ipynb — decomposes the full 12×12 transfer matrices: community detection is governed by the evaluation regime (difficulty, not failed transfer), triangle counting by the training regime (scale miscalibration under distribution shift, readable only on a log scale).

Known upstream limitation (disclosure)

Under TopoBench's combinatorial lifting, batch.coadjacency_2 is structurally all-zero: get_combinatorial_complex_connectivity requests coadjacency_matrix(1, 2), which TopoNetX rejects (rank must be greater than via_rank), and the fallback substitutes a zero matrix. Consequently the 2-cell intra-rank attention block of Figure 35(b) receives no messages in any benchmark run — for this and, we believe, every combinatorial-domain submission. The root cause is in upstream topobench/data/utils/utils.py (outside the allowed submission file set, so this PR does not modify it); computing coadjacency_matrix(2, 1) there would activate the block. We flag it for the organizers' attention.

Measured impact (Aug 2): we implemented the reconstruction in our own wrapper on a side branch and re-ran the full official 72-run grid with the block active. Performance is statistically unchanged (community detection 0.4596 → 0.4591; triangle counting MSE/triangles 0.4843 → 0.4918), so this PR keeps the baseline wrapper and results — the inactive block is an architectural-faithfulness issue, not a performance confound, and the committed results remain exactly reproducible from the submitted code.

Issue

No linked issue — this is a TDL Challenge 2026 submission (Track 2).

Additional context

• Team: topolab (registration form submitted with this PR's ID).
• Could a maintainer please tag this PR with track-2-tnn? (No triage rights.)

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB