Track: Track2; Team name: TJPaik; Model: TopNets

[TJPaik]

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

Adds a TDL Challenge 2026 Track 2 implementation for TopNets as model=combinatorial/topnets.

Reference:

• Paper: https://arxiv.org/pdf/2406.03164
• Code: https://github.com/Aalto-QuML/TopNets

Implementation details:

• adds a combinatorial-domain TopNets backbone using TopoBench GraphTriangleInducedCC lifting
• uses TuneWrapper and PropagateSignalDown so the submitted entrypoint is Track 2 (model_domain: combinatorial)
• uses a lightweight challenge config (hidden_channels=32, one TopNets layer/step) so the official 72-run grid is feasible
• keeps topobench/nn/backbones/graph/topnets.py as a private graph-neighborhood route helper used by the Track 2 combinatorial backbone, not as a submitted graph-model entrypoint
• removes the previous graph/topnets config entrypoint from the PR diff
• includes focused tests for proxy persistence pairs and inter-rank route feature initialization
• challenge notebook MODEL_CONFIG set to combinatorial/topnets

Validation:

• PYENV_VERSION=TDL python -m pytest test/nn/backbones/graph/test_topnets.py test/nn/backbones/combinatorial/test_topnets.py test/pipeline/test_pipeline.py -q -> 17 passed
• PYENV_VERSION=TDL python -m pytest test/pipeline/test_pipeline.py -q with baseline smoke models plus combinatorial/topnets -> 1 passed
• focused ruff on TopNets-touched files -> passed
• focused coverage run across TopNets graph route helper and combinatorial backbone -> completed locally
• official challenge sanity grid for model_config="combinatorial/topnets" -> all 24 configs passed

results.json status: committed at 2026_tdl_challenge/outputs/topnets/results.json with 72 completed challenge runs across train seeds 42, 43, and 44.

results.json provenance: generated from the checked-in 2026_tdl_challenge/utils.py helpers via CLI with model_config="combinatorial/topnets"; run_evaluation.ipynb now sets the same MODEL_CONFIG.

Issue

TDL Challenge 2026 Track 2 model submission for TopNets.

Additional context

Official results.json artifact is included in this PR.

This is a TopoBench Track 2 adaptation of TopNets, not an exact reproduction of the official TopNets experiment stack. It uses a portable learned-filtration proxy persistence path and a lightweight challenge config for the official 72-run grid.

Fidelity note

This submission is a TopoBench Track 2 adaptation of TopNets, not a drop-in reproduction of the upstream experiment stack. The reference TopNets graph-classification path uses the RePHINE/TOGL code path and compiled ph_cpu / rephine_mt kernels to compute standard / rephine persistence diagrams. In this PR, those kernels are intentionally replaced by an autograd-compatible PyTorch proxy that constructs H0/H1-style persistence pairs from the learned filtration values, so the model can run portably inside the TopoBench/GraphUniverse challenge pipeline without custom compiled extensions.

The adaptation preserves the challenge-relevant TopNets route structure: GCN/GIN state evolution, learned filtration MLPs, TOGL-style coordinate transforms, topology feature fusion, and node/topology embedding fusion. It does not claim bit-for-bit or diagram-level equivalence to the upstream RePHINE persistence kernels.

For Track 2, the route operator is applied over TopoBench combinatorial-complex neighborhoods and exposed through TuneWrapper + PropagateSignalDown. The submitted config is intentionally lightweight (hidden_channels=32, one layer/step, use_dim1=false) for the official 72-run GraphUniverse grid; this is a computational adaptation under the challenge criteria, not a claim of exact upstream hyperparameter reproduction.

The committed results use TopoBench's existing GraphTriangleInducedCC graph-to-combinatorial lifting with complex_dim=3. This lifting is not a clique-complex transform that preserves every structural triangle as a separate 2-cell; the TopNets adaptation runs over the rank neighborhoods produced by that available TopoBench lifting. The lifting may materialize rank-3 cells / incidence_3, but the submitted TopNets path intentionally consumes only ranks 0/1/2 through selected_dimensions: [0, 1, 2], the configured incidence routes, and PropagateSignalDown with three cell dimensions. Changing the lifting dimension, adding rank-3 routes, or otherwise consuming incidence_3 would change preprocessing/model behavior and would require regenerating results.json.

use_dim1=false is the submitted runtime-motivated challenge default. It disables proxy H1/cycle-summary pooling inside the route operator, while keeping H0-style learned-filtration node summaries and higher-order signal through the configured combinatorial incidence routes (down_incidence-1, down_incidence-2, up_incidence-1). The implementation supports the dim-1 proxy path, but the committed 72-run artifact uses the lighter route to keep the official grid feasible; this is a computational Track 2 adaptation, not a full H1-persistence TopNets reproduction for the triangle-counting task.

For inter-rank incidence routes (down_incidence-* / up_incidence-*), destination-cell features are intentionally zero-initialized inside the bipartite route graph, while source-cell features provide the signal into the destination block. The sparse incidence matrices are used only for their nonzero support to build an unweighted bipartite route graph. Incidence values, signs, and weights are not propagated as edge weights on those routes; this is intentional for the submitted Track 2 adaptation and differs from intrarank neighborhoods, where sparse matrix values are passed as edge_weight when available. The route output is then sliced back to destination-rank embeddings before TopoBench readout.

Note: topobench/nn/backbones/graph/topnets.py is a private graph-neighborhood route helper used by the Track 2 combinatorial backbone; it is not a submitted graph-model entrypoint. The only submitted TopNets model config is configs/model/combinatorial/topnets.yaml (model=combinatorial/topnets), and this PR intentionally does not add configs/model/graph/topnets.yaml.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB