Skip to content

RINGS integration for existing GNN pipelines#12

Merged
jeremy-wayland merged 28 commits into
mainfrom
worktree-jaunty-fluttering-horizon
May 20, 2026
Merged

RINGS integration for existing GNN pipelines#12
jeremy-wayland merged 28 commits into
mainfrom
worktree-jaunty-fluttering-horizon

Conversation

@jeremy-wayland

@jeremy-wayland jeremy-wayland commented May 20, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Introduces rings.integrations.SeparabilityStudy, a thin, framework-agnostic collector that slots into a user's existing PyG training loop instead of taking it over.
  • Replaces the direction taken on graph-bench-wrapper (a GraphBenchEvaluator orchestrator with a train_func(dataset, evaluator) callback and a hard graphbench-lib dependency) — that shape was too invasive for users who already have full training pipelines.
  • Adds a canonical PyG/MUTAG recipe in examples/pyg_separability.py and unit tests in tests/test_study.py.

Why

RINGS' actual integration surface is small: perturbations are already PyG BaseTransforms, and SeparabilityFunctor already accepts a plain Dict[str, np.array]. So instead of wrapping the training loop, this PR provides ~5 lines of glue the user adds around their existing code:

study = SeparabilityStudy(perturbations={...}, num_seeds=5)
for name, transform, seed in study.runs():
    dataset = study.apply(base_dataset, transform)
    score = my_existing_train_and_eval(dataset, seed=seed)
    study.record(name, score)
results = study.evaluate()

apply() uses isinstance against torch_geometric.data.Data/Dataset (replacing the brittle hasattr(..., "__len__") branching from the prior wrapper) and torch_geometric is imported lazily so import rings stays cheap.

jeremy-wayland and others added 3 commits May 20, 2026 13:34
Replaces the framework-coupled GraphBenchEvaluator approach with a thin,
framework-agnostic collector that slots into a user's existing training
loop rather than owning it. Includes a PyG/MUTAG recipe and unit tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- SeparabilityCallback bridges Lightning's trainer.callback_metrics into
  SeparabilityStudy.record on on_test_end. Guards pytorch_lightning and
  lightning.pytorch imports so rings.integrations stays importable without
  Lightning installed, and exposes the callback via lazy __getattr__.
- pyproject.toml: new [project.optional-dependencies] lightning extra.
- examples/lightning_separability.py: end-to-end MUTAG recipe with a
  LightningModule GCN, LightningDataset, and one Trainer per run.
- tests/test_lightning_callback.py: stub-trainer tests covering normal
  recording, unknown-perturbation, missing-metric, accumulation, and
  plain-float metric values. Skipped cleanly when Lightning is absent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@jeremy-wayland jeremy-wayland changed the title Add SeparabilityStudy: drop-in RINGS integration for existing GNN pipelines RINGS integration for existing GNN pipelines May 20, 2026
jeremy-wayland and others added 17 commits May 20, 2026 14:10
CompleteFeatures requires max_nodes; compute it from the dataset before
constructing the perturbation map.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Lightning emits "GPU available", "Seed set to N", "Trainer.fit stopped",
checkpoint paths and a litlogger tip through several logger namespaces
(and some via print). Setting individual logger levels does not catch
all of them, so the example uses logging.disable(WARNING) at import
time and also disables checkpointing on the Trainer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This update ensures that dataset files and checkpoints are excluded from version control, preventing unnecessary clutter in the repository.
This commit removes the optional dependencies section for Lightning from pyproject.toml and deletes the uv.lock file, streamlining the project configuration.
This commit introduces a new example script, `graphbench.py`, demonstrating the use of GraphBench metrics in a GCN training pipeline on the MUTAG dataset. The script includes dataset loading, model training, and evaluation, showcasing the application of various perturbations through the `SeparabilityStudy` class. This enhances the integration of GraphBench with PyG for graph classification tasks.
This commit introduces a `__version__` attribute to the `rings` module, setting the initial version to "0.1.0". This addition helps in tracking the module's version for future releases.
This commit introduces a GitHub Actions CI workflow that triggers on pushes and pull requests to the main branch. It sets up a matrix build for Python versions 3.11, 3.12, and 3.13, installs dependencies, checks for version consistency between `pyproject.toml` and `rings/__init__.py`, runs tests with pytest, and performs linting and formatting checks using Ruff for Python 3.13.
torch_geometric's BaseTransform now requires subclasses to implement
forward() rather than __call__(). Renaming the method across Shuffle and
all perturbation transforms restores instantiability and unblocks the
test suite under the new CI checks.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
- Updated the introduction to succinctly describe RINGS as a perturbation framework for attributed graphs.
- Consolidated installation instructions into a quickstart section for easier access.
- Improved example usage with clearer code snippets and integration instructions for PyTorch Lightning.
- Removed outdated sections to focus on current features and usage.
- Introduced new documentation files for the `rings.complementarity` and `rings.separability` modules, detailing their functionalities and usage.
- Removed outdated files related to complementarity comparators, functors, metrics, and utilities to streamline the documentation.
- Updated the main index and configuration files to reflect the new structure and added sidebar navigation for improved user experience.

@Pseudomanifold Pseudomanifold left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks very good to me :-)

@Pseudomanifold Pseudomanifold marked this pull request as ready for review May 20, 2026 14:33
- Added installation instructions for the package from PyPI, including a requirement for Python 3.11+.
- Included guidance for installing from source to facilitate contributions and example execution.
@jeremy-wayland jeremy-wayland merged commit 68a58a4 into main May 20, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants