Code for the paper Higher-Order Learning with Graph Neural Networks via Hypergraph Encodings - accepted at NeurIPS 2025 (https://neurips.cc/virtual/2025/poster/116020)
arxiv: https://arxiv.org/pdf/2502.09570 (camera-ready version coming soon).
bash_interface/
contains the bash scripts to run the experiments. The bash scripts run the python scripts (found in the scripts folder) with the appropriate parameters. For example, run_all_general.sh will run all the experiments for the hypergraph-level node classifications with the Unignns models. run_all_encodings_brec.sh will run all the experiments for the BREC dataset (trying to see if the pairs can be distinguished using the encodings computed at the graph-level or hypergraph-level).
scripts/
contains the interface. You can also run the bash scripts. brec/ contains the scripts to compare pairs of graphs in the BREC dataset. gnn/ contains the scripts to run the experiments for on the graph-level architectures (graph classification, graph regression, node classification). unignn/ contains the scripts to run the experiments for on the hypergraph-level architectures (hypergraph node classification). compute_encodings/ contains the script to process the datasets and compute the encodings on the datasets.
src/
contains backend functions for the package.
Specifically, this contains:
animations
brec_analysis
compute_encodings
gnns -> to be cleaned up still
orchid
unignn_achitectures
tests/
contains the test files - we use pytest.
example_notebooks/
Contains the example notebooks to interact with the package.
data/
contains the coauthorship and cocitation data.
computed_encodings/
contains the precomputed encodings saved as pickle files.
gifs/
contains the gifs of the random walks.
.github/workflows/
contains the github actions workflows.
We follow the interface from UniGCN for the unignn models:
python scripts/unignn/train_val.py --data=coauthorship --dataset=dblp --model-name=UniSAGE
will run the node level classification on the dblp dataset with the UniSAGE model.
We have the following optional arguments that are in the script/unignn/config.py file:
optional arguments:
-h, --help show this help message and exit
--add-encodings BOOL whether to add encodings (default: True)
--encodings ENCODING which encoding to add (default: LDP)
--random-walk-type RANDOMWALKTYPE which random walk (WE, EN, EE)
--curvature-type CURVATURETYPE which curvature (ORC or FRC)
--laplacia-type LAPLACIANTYPE whcih Laplacian type (Normalized, Hodge, more to come)
--k-rw k number of hops for RW encodings
--data DATA data name (coauthorship/cocitation) (default: coauthorship)
--dataset DATASET dataset name (e.g.: cora/dblp for coauthorship, cora/citeseer/pubmed for cocitation) (default: cora)
--model-name MODEL_NAME UniGNN Model(UniGCN, UniGAT, UniGIN, UniSAGE...)(default: UniSAGE)
--first-aggregate FIRST_AGGREGATE aggregation for hyperedge h_e: max, sum, mean (default: mean)
--second-aggregate SECOND_AGGREGATE aggregation for node x_i: max, sum, mean (default: sum)
--add-self-loop add-self-loop to hypergraph (default: False)
--use-norm use norm in the final layer (default: False)
--activation ACTIVATION activation layer between UniConvs (default: relu)
--nlayer NLAYER number of hidden layers (default: 2)
--nhid NHID number of hidden features, note that actually it's #nhid x #nhead (default: 8)
--nhead NHEAD number of conv heads (default: 8)
--dropout DROPOUT dropout probability after UniConv layer (default: 0.6)
--input-drop INPUT_DROP dropout probability for input layer (default: 0.6)
--attn-drop ATTN_DROP dropout probability for attentions in UniGATConv (default: 0.6)
--lr LR learning rate (default: 0.01)
--wd WD weight decay (default: 0.0005)
--epochs EPOCHS number of epochs to train (default: 200)
--n-runs N_RUNS number of runs for repeated experiments (default: 10)
--gpu GPU gpu id to use (default: 0)
--seed SEED seed for randomness (default: 1)
--patience PATIENCE early stop after specific epochs (default: 200)
--nostdout do not output logging to terminal (default: False)
--split SPLIT choose which train/test split to use (default: 1)
--out-dir OUT_DIR output dir (default: runs/test)
IMPORTANT NOTE: We are working on making the code as general, but for now, assume that the hyperedges (lists) contains vertices in sorted order.
Create a virtual env, activate it and install the required packages.
conda create -n encodings_venv python=3.11
conda activate encodings_venv# Install base package
pip install -e .
# Install PyTorch Geometric dependencies
# (depends on your torch version and CPU/GPU setup)
pip install torch-scatter==2.1.1 torch-sparse==0.6.17 -f https://data.pyg.org/whl/torch-2.0.0+cpu.htmlYou might need to install julia separately as well as the ORC routine calls julia code.
Using Visual Studio, navigate to the file
scripts/unignn/train_val.py
and use the build in debugger. You can add breakpoints etc.
To run the script with multiple parameters, there is the bash script:
run_all_general.sh
We can aggregate the results using the script:
python scripts/create_results_table.pyWe have a test suite that runs using pytest.
Simply run:
pytestfrom root. That sould look for all tests and run them. You can run
pytest --verbosefor more prints.
For a file in particular, run:
pytest tests/test_curvature.pyYou might need to give permission to the file. Eg
chmod +x Hypergraph_Encodings/src/orchid/orchid_interface.jl
Feel free to open an issue on the repo if you have any questions or issues.