{"id":30799813,"url":"https://github.com/imoonlab/khgnn","last_synced_at":"2025-09-08T00:02:19.054Z","repository":{"id":312809217,"uuid":"1048797985","full_name":"iMoonLab/KHGNN","owner":"iMoonLab","description":"This repository contains the official implementation of \"Kernel Hypergraph Neural Networks\" published in IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI).","archived":false,"fork":false,"pushed_at":"2025-09-02T04:49:39.000Z","size":828,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T06:21:57.462Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iMoonLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T03:34:37.000Z","updated_at":"2025-09-02T04:55:26.000Z","dependencies_parsed_at":"2025-09-02T06:22:00.017Z","dependency_job_id":"f407bb3e-feb7-4168-ab36-5500801cef1a","html_url":"https://github.com/iMoonLab/KHGNN","commit_stats":null,"previous_names":["imoonlab/khgnn"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/iMoonLab/KHGNN","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FKHGNN","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FKHGNN/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FKHGNN/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FKHGNN/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iMoonLab","download_url":"https://codeload.github.com/iMoonLab/KHGNN/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FKHGNN/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273813276,"owners_count":25172892,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-05T19:54:32.760Z","updated_at":"2025-09-05T19:54:36.662Z","avatar_url":"https://github.com/iMoonLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KHGNN: Kernelized Hypergraph Neural Networks\n\n[![Paper](https://img.shields.io/badge/Paper-IEEE%20TPAMI-blue)](https://ieeexplore.ieee.org/abstract/document/11063418)\n[![Python](https://img.shields.io/badge/Python-3.8%2B-green)](https://www.python.org/)\n[![PyTorch](https://img.shields.io/badge/PyTorch-1.9%2B-orange)](https://pytorch.org/)\n[![DHG](https://img.shields.io/badge/DHG-0.9.5-red)](https://github.com/iMoonLab/DeepHypergraph)\n\nThis repository contains the official implementation of **\"Kernelized Hypergraph Neural Networks\"** published in **IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI)**.\n\n## 🔥 Overview\n\nKernelized Hypergraph Neural Networks (KHGNN) introduces a novel approach to hypergraph learning by incorporating kernel methods into hypergraph neural networks. Our method enhances the representation learning capability on hypergraph-structured data through adaptive kernel functions.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"doc/assets/khgnn_overview.png\" alt=\"KHGNN Overview\" width=\"800\"/\u003e\n  \u003cp\u003e\u003cem\u003eKHGNN Overview: Kernelized hypergraph neural network architecture\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n### Key Features\n\n- **Kernelized Hypergraph Convolution**: Novel convolution operation using adaptive kernel functions\n- **Flexible Kernel Types**: Support for polynomial, adaptive polynomial, and mean kernels\n- **Comprehensive Evaluation**: Extensive experiments on multiple benchmark datasets\n- **Easy Integration**: Compatible with existing hypergraph neural network frameworks\n\n\n## 🏗️ Model Architecture\n\nThe KHGNN architecture consists of:\n\n1. **Kernelized Hypergraph Convolution Layer**: Core convolution with adaptive kernels\n2. **Node Normalization**: Stabilizes training dynamics\n3. **Residual Connections**: Enables deep architectures\n4. **Adaptive Parameters**: Learnable kernel parameters (p, μ)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"doc/assets/khgnn_architecture.png\" alt=\"KHGNN Architecture\" width=\"700\"/\u003e\n  \u003cp\u003e\u003cem\u003eDetailed KHGNN architecture showing kernel convolution layers and adaptive parameters\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\n## 📝 Code Structure\n\n```\nKHGNN/\n├── khgnn_model.py          # Main KHGNN model implementation\n├── trans_train.py          # Transductive training script\n├── prod_train.py           # Inductive training script  \n├── utils.py                # Data loading and utility functions\n├── trans_config.yaml       # Transductive experiment config\n└── prod_config.yaml        # Inductive experiment config\n```\n\n\n## 📦 Installation\n\n### Prerequisites\n\n- Python \u003e= 3.8, \u003c 3.11\n- uv (Python package manager, recommended)\n\n### Install uv (if not already installed)\n\n```bash\n# On Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Or using pip\npip install uv\n```\n\n### Quick Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/iMoonLab/KHGNN.git\ncd KHGNN\n\n# Install dependencies using uv (recommended)\nuv sync\n\n# Or install with pip (if not using uv)\npip install -e .\n```\n\n### Development Setup\n\n```bash\n# Install development dependencies (includes black, isort, etc.)\nuv sync --group dev\n```\n\n## 🚀 Quick Start\n\n### Basic Usage\n\n```python\nimport torch\nimport torch.nn.functional as F\nfrom dhg import Hypergraph\nfrom khgnn_model import KerHGNN\nfrom utils import load_data\n\n# Load dataset\ndata, edge_list = load_data('cora')\nfeatures = data['features']\nlabels = data['labels']\n\n# Create hypergraph\nhg = Hypergraph(data['num_vertices'], edge_list)\n\n# Initialize KHGNN model\nmodel = KerHGNN(\n    in_channels=features.shape[1],\n    hid_channels=64,\n    num_classes=labels.max().item() + 1,\n    num_layer=2,\n    kernel_type='poly',  # 'poly', 'apoly', or 'mean'\n    p_min=-0.5,\n    p_max=2.0,\n    drop_rate=0.5\n)\n\n# Forward pass\nmodel.eval()\nwith torch.no_grad():\n    output = model(features, hg)\n    probs = F.softmax(output, dim=1)\n```\n\n### Quick Example\n\nTry the provided example script to see KHGNN in action:\n\n```bash\n# Run the example script\nuv run example.py\n```\n\nThis will demonstrate:\n- Loading a sample dataset\n- Initializing the KHGNN model\n- Running a forward pass\n- Displaying sample predictions\n\n### Training\n\n```bash\n# Transductive learning\nuv run trans_train.py\n\n# Inductive learning  \nuv run prod_train.py\n\n# Multi-experiment runs\nuv run trans_multi_train.py\nuv run prod_multi_exp.py\n```\n\n## 📊 Supported Datasets\n\nOur implementation supports various hypergraph datasets:\n\n### Citation Networks\n- **Cora**, **Citeseer**, **Pubmed** - Classic citation networks\n- **DBLP4k** - DBLP bibliography network (conference, paper, term views)\n\n### Co-authorship Networks  \n- **Coauthorship-DBLP** - Author collaboration networks\n- **Coauthorship-Cora** - Cora author networks\n\n### Other Domains\n- **News20** - 20 Newsgroups text classification\n- **IMDB4k** - Movie database\n- **Cooking200** - Recipe recommendation\n\n## ⚙️ Configuration\n\nThe model supports flexible configuration through YAML files. **The working directory is now automatically set to the current directory** - no manual configuration needed!\n\n```yaml\n# trans_config.yaml\ndata:\n  name: cora\n  num_train: 20\n  num_val: 100\n  \nmodel:\n  name: kerhgnn\n  hid: 64\n  num_layer: 2\n  kernel_type: poly\n  p_min: -0.5\n  p_max: 2.0\n  \noptim:\n  lr: 0.01\n  lr_p: 0.003\n```\n\n### Override Configuration\n\n```bash\n# Change dataset and model parameters\nuv run trans_train.py data.name=cora model.hid=64\n\n# Change kernel type and parameters  \nuv run trans_train.py model.kernel_type=poly model.p_min=-1.0\n\n# Change learning rates\nuv run trans_train.py optim.lr=0.01 optim.lr_p=0.001\n```\n\n📋 **For detailed configuration options, see [CONFIG_GUIDE.md](doc/CONFIG_GUIDE.md)**\n\n```\noptim:\n  lr: 0.01\n  lr_p: 0.003\n```\n\n### Kernel Types\n\n- **`poly`**: Polynomial kernel with learnable parameters\n- **`apoly`**: Adaptive polynomial kernel \n- **`mean`**: Mean aggregation kernel\n\n\n## 🎯 Citation\n\nIf you find this work useful for your research, please consider citing:\n\n```bibtex\n@article{zhang2024khgnn,\n  author={Feng, Yifan and Zhang, Yifan and Ying, Shihui and Du, Shaoyi and Gao, Yue},\n  journal={IEEE Transactions on Pattern Analysis and Machine Intelligence}, \n  title={Kernelized Hypergraph Neural Networks}, \n  year={2025},\n  volume={},\n  number={},\n  pages={1-17},\n}\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [development guide](doc/CONTRIBUTING.md) for details on:\n\n- Code formatting with Black and isort\n- Running tests\n- Submitting pull requests\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Related Work\n\n- [DeepHypergraph (DHG)](https://github.com/iMoonLab/DeepHypergraph) - The hypergraph learning library we build upon\n\n## 📞 Contact\n\nFor questions about the code or paper, please:\n\n- Open an issue in this repository\n- Contact the authors: [Yifan Feng](mailto:evanfeng97@gmail.com), [Yifan Zhang](mailto:dxny2nd@gmail.com)\n\n---\n\n**⭐ If you find this repository helpful, please give it a star!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimoonlab%2Fkhgnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimoonlab%2Fkhgnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimoonlab%2Fkhgnn/lists"}