pyg-hyper 0.1.2

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.

Prerequisites

This package requires PyTorch Geometric to be installed:

pip install torch torch-geometric

Installation

Install all components

pip install pyg-hyper[all]

Or with uv:

uv add pyg-hyper[all]

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

Import Style

Import directly from each sub-package:

from pyg_hyper.data.datasets import CoraCocitation
from pyg_hyper.bench import NodeClassificationProtocol, SingleRunEvaluator
from pyg_hyper.ssl import TriCL, TriCLEncoder

Dataset Loading

from pyg_hyper.data.datasets import CoraCocitation

dataset = CoraCocitation()
data = dataset[0]
print(data)  # HyperData with x, hyperedge_index, y

SSL Training & Evaluation

from pyg_hyper.data.datasets import CoraCocitation
from pyg_hyper.ssl import TriCL, TriCLEncoder
from pyg_hyper.bench import SSLLinearEvaluationProtocol

dataset = CoraCocitation()
data = dataset[0]

# Build encoder and SSL model
encoder = TriCLEncoder(
    in_dim=data.num_node_features,
    edge_dim=64,
    node_dim=64,
    num_layers=2,
)
model = TriCL(encoder=encoder, proj_dim=64)

# Get embeddings for downstream evaluation
embeddings = model.get_embeddings(data)  # [num_nodes, node_dim]

# Linear evaluation
protocol = SSLLinearEvaluationProtocol(seed=42)
split = protocol.split_data(data)
metrics = protocol.evaluate(
    embeddings=embeddings,
    labels=data.y,
    train_mask=split["train_mask"],
    val_mask=split["val_mask"],
    test_mask=split["test_mask"],
)
print(f"Test Accuracy: {metrics['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 (11 datasets)	0.1.1
pyg-hyper-nn	Neural network layers	0.1.1
pyg-hyper-ssl	Self-supervised learning	0.1.1
pyg-hyper-bench	Benchmarking framework	0.1.1

Development

Setup

# Clone repository
git clone https://github.com/nishide-dev/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 = {Ryusei Nishide},
  year = {2026},
  url = {https://github.com/nishide-dev/pyg-hyper}
}