pyg-hyper 0.1.1

Unified interface for PyTorch Geometric Hypergraph Learning

pyg-hyper: Unified PyTorch Geometric Hypergraph Learning

Unified interface for all pyg-hyper components, providing convenient access to hypergraph datasets, neural network layers, self-supervised learning methods, and benchmarking protocols.

Installation

Requirements

• Python >=3.12
• PyTorch >=2.0.0
• PyTorch Geometric >=2.4.0

Quick Install (pip)

pip install pyg-hyper[all]

Note: torch-scatter and torch-sparse are required dependencies. If you encounter build errors, you may need to install pre-built wheels from PyTorch Geometric:

pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.8.0+cu126.html
pip install pyg-hyper[all]

Recommended Install (uv)

For the best experience with uv, add the following configuration to your pyproject.toml:

[project]
dependencies = [
    "pyg-hyper[all]>=0.1.0",
]

[[tool.uv.index]]
name = "pytorch-cu126"
url = "https://download.pytorch.org/whl/cu126"
explicit = true

[[tool.uv.index]]
name = "pytorch-geometric"
url = "https://data.pyg.org/whl/torch-2.8.0+cu126.html"
format = "flat"
explicit = true

[tool.uv.sources]
torch-scatter = { index = "pytorch-geometric" }
torch-sparse = { index = "pytorch-geometric" }

Then install:

uv sync

This configuration ensures torch-scatter and torch-sparse are installed from pre-built wheels, avoiding lengthy compilation times.

Install Specific Components

# Data only
pip install pyg-hyper[data]

# Neural networks only
pip install pyg-hyper[nn]

# Self-supervised learning
pip install pyg-hyper[ssl]

# Benchmarking
pip install pyg-hyper[bench]

# Combine multiple
pip install pyg-hyper[data,nn]

Quick Start

Unified Imports

from pyg_hyper import data, nn, ssl, bench

# Load dataset
dataset = data.CoraCocitation()
hyper_data = dataset[0]

# Create model
model = nn.HyperGraphSage(
    in_channels=hyper_data.num_node_features,
    hidden_channels=64,
    out_channels=dataset.num_classes,
    num_layers=2,
)

# Evaluate with benchmark
protocol = bench.NodeClassificationProtocol(seed=42)
evaluator = bench.SingleRunEvaluator(protocol)
result = evaluator.evaluate(model, dataset)
print(f"Test Accuracy: {result['test_accuracy']:.4f}")

SSL Workflow

from pyg_hyper import data, nn, ssl, bench

# Load dataset
dataset = data.CoraCocitation()
hyper_data = dataset[0]

# Create SSL encoder
encoder = nn.HyperGraphSage(
    in_channels=hyper_data.num_node_features,
    hidden_channels=64,
    out_channels=64,
    num_layers=2,
)

# Pre-train with SSL (placeholder - implement in pyg-hyper-ssl)
# ssl_trainer = ssl.MaskedNodePrediction(encoder)
# ssl_trainer.fit(dataset)

# Evaluate frozen embeddings
import torch
with torch.no_grad():
    embeddings = encoder(hyper_data.x, hyper_data.incidence_matrix)

protocol = bench.SSLLinearEvaluationProtocol(
    task="node_classification",
    classifier="logistic_regression",
    seed=42,
)
result = protocol.evaluate(embeddings, hyper_data)
print(f"Linear Probe Accuracy: {result['test_accuracy']:.4f}")

Architecture

This is a pure meta-package that provides:

• ✅ Unified import interface via lazy loading
• ✅ Zero import overhead (loads only what you use)
• ✅ Independent versioning of sub-packages
• ✅ Maximum flexibility (install only what you need)

Sub-Packages

Package	Description	Version
pyg-hyper-data	Hypergraph datasets (10 datasets)	0.1.0
pyg-hyper-nn	Neural network layers	0.1.0
pyg-hyper-ssl	Self-supervised learning	0.1.0
pyg-hyper-bench	Benchmarking framework	0.1.0

Development

Setup

# Clone repository
git clone https://github.com/your-username/pyg-hyper.git
cd pyg-hyper

# Install with dev dependencies
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

Code Quality

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Type check
uv run ty check src/

Testing

# Run all tests
uv run pytest tests/ -v

# Run only import tests
uv run pytest tests/test_imports.py -v

# Run only integration tests
uv run pytest tests/ -v -m integration

# With coverage
uv run pytest tests/ --cov=pyg_hyper --cov-report=html

Pre-commit Hooks

Automatically run code quality checks before commits:

• ruff-lint: Linting with auto-fix
• ruff-format: Code formatting
• ty-check: Type checking

Install hooks:

uv run pre-commit install

Run manually:

uv run pre-commit run --all-files

CI/CD

GitHub Actions

• CI Pipeline: Code quality, import tests, integration tests
• Publish Pipeline: Automatic publishing to TestPyPI (main branch) and PyPI (tags)

Publishing

# TestPyPI (automatic on push to main)
uv publish --index testpypi

# PyPI (automatic on tag v*)
git tag v0.1.0
git push origin v0.1.0

License

MIT License - See LICENSE file for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run pre-commit hooks
4. Submit a pull request

Citation

If you use pyg-hyper in your research, please cite:

@software{pyg_hyper,
  title = {pyg-hyper: Unified PyTorch Geometric Hypergraph Learning},
  author = {Nishide, Takumi},
  year = {2026},
  url = {https://github.com/your-username/pyg-hyper}
}