Generate families of graphs with finely controllable properties for systematic evaluation of inductive graph learning models.
Quick Start | Interactive UI | Validation | Paper Experiments
Synthetic graph learning benchmarks are limited to single-graph, transductive settings. GraphUniverse enables the first systematic evaluation of inductive generalization by generating entire families of graphs with:
- Consistent Semantics: Communities maintain stable identities across graphs
- Fine-grained Control: Tune homophily, degree distributions, community structure
- Scalable Generation: Linear scaling, thousands of graphs per minute
- Validated Framework: Comprehensive parameter sensitivity analysis
- Interactive Tool: Web-based exploration and visualization and Downloadable Pyg-dataset object ready to train!
Install from PyPI:
pip install graph-universeFor the interactive UI (streamlit) and visualization tools:
pip install graph-universe[viz]Optional extras:
[viz]- Streamlit UI + seaborn visualization tools[dev]- Development dependencies (testing, linting)[all]- Everything (includes documentation tools)
Install from source:
git clone https://github.com/LouisVanLangendonck/GraphUniverse.git
cd GraphUniverse
pip install -e ".[dev]"After installing with [viz], launch the interactive dashboard:
graph-universe-uiHosted demo: Try it online at graphuniverse.streamlit.app
Launch from Python:
from graph_universe import launch_ui
launch_ui() # Opens browser, press Ctrl+C to stopfrom graph_universe import GraphUniverse, GraphFamilyGenerator
# Create universe with 8 communities and 10-dimensional features
universe = GraphUniverse(K=8, edge_propensity_variance=0.3, feature_dim=10)
# Generate family with full parameter control
family = GraphFamilyGenerator(
universe=universe,
n_nodes_range=(35, 50),
n_communities_range=(2, 6),
homophily_range=(0.2, 0.8),
avg_degree_range=(2.0, 10.0),
power_law_exponent_range=(2.0, 5.0),
degree_separation_range=(0.1, 0.7),
seed=42
)
# Generate 30 graphs
family.generate_family(n_graphs=30, show_progress=True)
print(f"Generated {len(family.graphs)} graphs!")
# Convert to PyTorch Geometric format for training
pyg_graphs = family.to_pyg_graphs(task="community_detection")Create config.yaml:
universe_parameters:
K: 10
edge_propensity_variance: 0.5
feature_dim: 16
center_variance: 1.0
cluster_variance: 0.3
seed: 42
family_parameters:
n_graphs: 100
n_nodes_range: [25, 200]
n_communities_range: [3, 7]
homophily_range: [0.1, 0.9]
avg_degree_range: [2.0, 8.0]
power_law_exponent_range: [2.0, 3.0]
degree_separation_range: [0.4, 0.8]
seed: 42
task: "community_detection"Then load and generate:
import yaml
from graph_universe import GraphUniverseDataset
with open("config.yaml") as f:
config = yaml.safe_load(f)
dataset = GraphUniverseDataset(root="./data", parameters=config)
print(f"Generated dataset with {len(dataset)} graphs!")GraphUniverse includes built-in validation to ensure generated graphs match target properties:
# Validate standard graph properties
family_properties = family.analyze_graph_family_properties()
for property_name in ['node_counts', 'avg_degrees', 'homophily_levels']:
values = family_properties[property_name]
print(f"{property_name}: mean={np.mean(values):.3f}")
# Analyze within-graph community signals (fits Random Forest per graph)
family_signals = family.analyze_graph_family_signals()
for signal in ['structure_signal', 'feature_signal', 'degree_signal']:
values = family_signals[signal]
print(f"{signal}: mean={np.mean(values):.3f}")
# Measure between-graph consistency
family_consistency = family.analyze_graph_family_consistency()
for metric in ['structure_consistency', 'feature_consistency', 'degree_consistency']:
value = family_consistency[metric]
print(f"{metric}: {value:.3f}")- GitHub Repository: https://github.com/LouisVanLangendonck/GraphUniverse
- PyPI Package: https://pypi.org/project/graph-universe/
- Issue Tracker: https://github.com/LouisVanLangendonck/GraphUniverse/issues
- Changelog: https://github.com/LouisVanLangendonck/GraphUniverse/blob/main/CHANGELOG.md
If you use GraphUniverse in your research, please cite:
@article{van2025graphuniverse,
title={GraphUniverse: Enabling Systematic Evaluation of Inductive Generalization},
author={Van Langendonck, Louis and Bern{\'a}rdez, Guillermo and Miolane, Nina and Barlet-Ros, Pere},
journal={arXiv preprint arXiv:2509.21097},
year={2025}
}The sections below contain resources for reproducing paper experiments and contributing to development.
Clone the repository to access validation and experiment scripts:
git clone https://github.com/LouisVanLangendonck/GraphUniverse.git
cd GraphUniverse
pip install -e ".[dev]"Run parameter sensitivity validation (reproduces paper results):
python experiments/validate_parameter_sensitivity.py --n-random-samples 100 --n-graphs 30Run scalability experiments:
python experiments/scalability_experiment.pyMIT License - see LICENSE for details.
Copyright (c) 2025 Louis Van Langendonck and Guillermo Bernardez

