Track: Track2; Team name: TripleA; Model: TopoU-Net

[amiiiza]

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. (refer to comment below)
• My PR follows PEP8 guidelines. (refer to comment below)
• 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.

Description

This PR implements TopoU-Net -- "TopoU-Net: A U-Net Architecture for Topological Domains" (arXiv:2605.10091) -- as a Track 2 (TNN) submission for the TDL Challenge 2026.

TopoU-Net is a U-shaped encoder–decoder over the ranked cells of a combinatorial complex. Given an increasing encoder rank path S = (s_0 < … < s_L), the encoder transports cochains upward along incidence matrices, a bottleneck map is applied at rank s_L, and the decoder transports features back down, merging encoder and decoder states at matched ranks through skip connections. Rank traversal replaces spatial scale: the rank path is the central architectural hyperparameter.

Provenance. No official implementation of the paper has been released (checked July 2026). The implementation follows the paper's equations directly, and every docstring cites the specific section it implements:

• Incidence-convolution transports T↑(H) = σ(B̄ᵀ H W↑), T↓(G) = σ(B̄ G W↓) -- §3.2, §3.5
• Encoder/decoder recursion with within-rank refinements Φ, Ψ (pointwise MLPs, the canonical choice) and bottleneck Ω -- Definition 3.3, §3.5
• Additive skip merge D_{s_i} = σ((E_{s_i} + D̃_{s_i}) W^m_i), with a use_skip flag reproducing the no-skip ablation -- §3.5, §4.6.3
• Degree-normalized incidence option (aggr_norm) --§3.2
• Direct incidence B_{s_i,s_{i+1}} for rank-skipping path steps, realized as the binarized product of consecutive incidence matrices -- §3.5
• Rank structure: nodes / edges / triangles-as-maximal-3-cliques / optional single global rank-3 cell incident to all triangles -- §4, Appendix B.4
• Shared hidden dimension across ranks and dropout inside refinements -- Appendix B.4

Permutation equivariance (Proposition 3.5) and structural compatibility of the decoder states (Proposition 3.4) are covered by dedicated unit tests.

Model variants (one config per rank path, per challenge rules)

Config	Encoder rank path	Full U traversal	Paper usage
combinatorial/topounet (default)	[0, 1, 2]	0→1→2→1→0	graph classification, general
combinatorial/topounet_edge	[0, 1]	0→1→0	homophilic graphs (minimal baseline, §4.6.4)
combinatorial/topounet_global	[0, 1, 2, 3]	0→1→2→3→2→1→0	heterophilic graphs (global bottleneck, §4)

All variants share the same backbone class; only encoder_rank_path and the lifting's complex_dim / add_global_cell differ.

What is contributed

New modules

• Backbone -- topobench/nn/backbones/combinatorial/topounet.py
TopoUNet(torch.nn.Module); auto-discovered by ModelExportsManager. Takes per-rank cochains and the consecutive sparse incidence matrices B_{r-1,r} that TopoBench already computes. Handles empty ranks gracefully (e.g. triangle-free graphs), in which case the skip connections carry the signal -- mirroring the paper's motivation for skips under severe bottleneck compression (Proposition 3.6).

• Lifting -- topobench/transforms/liftings/graph2combinatorial/triangle_global_cc.py
GraphTriangleGlobalCC: nodes (rank 0), edges (rank 1), triangles as maximal 3-cliques (rank 2, §4), and optionally a single global rank-3 cell incident to all triangles (Appendix B.4), realized as the all-nodes set so that B_{2,3} is a column of ones. The global cell is only added when triangles exist, which keeps active ranks consecutive as required by TopoBench's connectivity extraction. Reusable by any future combinatorial model.

• Wrapper -- topobench/nn/wrappers/combinatorial/topounet_wrapper.py
  Thin AbstractWrapper subclass routing x_0 and incidence_1..incidence_{s_L} into the backbone and exposing the decoder states of every path rank to the readout.

Reused TopoBench components (no modification needed)

• AllCellFeatureEncoder (rank 0 only -- per Definition 3.3, TopoU-Net consumes a single input cochain at rank s_0; higher-rank states are computed by the encoder itself)
• ProjectionSum feature lifting, NoReadOut readout (the decoder already returns the signal to rank 0; graph-level tasks use global mean pooling per §4.2)
• TopoBench's combinatorial-complex connectivity extraction and sparse block-diagonal batching

Configs

• configs/model/combinatorial/topounet{,_edge,_global}.yaml -- full TBModel composition (feature_encoder / backbone / backbone_wrapper / readout)
• configs/transforms/liftings/graph2combinatorial/topounet_cc{,_edge,_global}.yaml -- lifting parameters per variant
• configs/transforms/model_defaults/topounet{,_edge,_global}.yaml -- attach the correct lifting automatically whenever the model is run on a graph dataset (same mechanism as nsd/hopse)

Faithfulness notes (allowed modifications)

• Higher-rank input features are seeded by TopoBench's standard ProjectionSum (sum over the boundary via |Bᵀ|); the paper initializes the global cell by mean pooling of triangle features (App. B.4). With aggr_norm: true the backbone's own transports average over incident cells, matching the paper's normalized-incidence option (§3.2). These seeded features are not consumed by the backbone (Definition 3.3 takes input only at rank s_0).
• Linear maps use a bias term (standard practice; preserves permutation equivariance, verified by test).
• Triangles are enumerated as maximal cliques of size 3 (nx.find_cliques), literally following "triangles as maximal 3-cliques" (§4) and matching the convention of the existing GraphTriangleInducedCC lifting.

Testing

• test/nn/backbones/combinatorial/test_topounet.py -- 12 tests: forward shapes for all three rank paths (Prop. 3.4), permutation equivariance (Prop. 3.5), no-skip ablation (§4.6.3), degree normalization, direct-incidence rank skipping (§3.5), empty-rank handling, input validation, repr.
• test/nn/wrappers/combinatorial/test_topounet_wrapper.py -- wrapper output contract, with and without residual connections.
• test/transforms/liftings/graph2combinatorial/test_triangle_global_cc.py -- triangle cells, global-cell incidence (all-ones B_{2,3}), triangle-free graphs, edge-only complex, feature lifting.
• Coverage: 100 % on all three new source files (17 tests, all passing).
• test/pipeline/test_pipeline.py filled in with graph/MUTAG × all three variants -- full training pipeline passes end-to-end.
• ruff and numpydoc validation pass on all new files.

Evaluation

• 2026_tdl_challenge/run_evaluation.ipynb run on combinatorial/topounet; the generated results.json is included in this PR.

Reproducing

# unit tests
pytest test/nn/backbones/combinatorial/test_topounet.py \
       test/nn/wrappers/combinatorial/test_topounet_wrapper.py \
       test/transforms/liftings/graph2combinatorial/test_triangle_global_cc.py

# pipeline test
pytest test/pipeline/test_pipeline.py

# single run
python -m topobench model=combinatorial/topounet dataset=graph/MUTAG

---

[cursor]

Bugbot is not enabled for this team, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cursor]

Bugbot is not enabled for this team, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.