Hypergraph-DB

A Lightweight, Fast, and Modern Hypergraph Database with Hypergraph Visualization.

Features • Quick Start • Installation • Documentation • Examples

🚀 About

Hypergraph-DB is a lightweight, flexible, and high-performance Python library for modeling and managing hypergraphs — advanced graph structures where edges (hyperedges) can connect any number of vertices. Unlike traditional graphs that only support pairwise relationships, hypergraphs naturally represent complex multi-way relationships found in real-world scenarios.

🎯 Why Hypergraphs?

Traditional graphs can only model pairwise relationships:

Alice ←→ Bob, Bob ←→ Charlie, Alice ←→ Charlie (3 separate edges)

Hypergraphs naturally model group relationships:

{Alice, Bob, Charlie} — working together on a project (1 hyperedge)

🌟 Perfect for

• 📚 Academic Collaborations: Research papers with multiple co-authors
• 👥 Social Networks: Group activities and multi-party interactions
• 🛒 E-commerce: Shopping baskets with multiple items
• 🧬 Bioinformatics: Protein interactions and genetic networks
• 🏗️ Knowledge Graphs: Complex entity relationships

✨ Features

📈 Performance

To demonstrate the performance of Hypergraph-DB, let’s consider an example:

• Suppose we want to construct a hypergraph with 1,000,000 vertices and 200,000 hyperedges.
• Using Hypergraph-DB, it takes approximately:
  • 1.75 seconds to add 1,000,000 vertices.
  • 1.82 seconds to add 200,000 hyperedges.
• Querying this hypergraph:
  • Retrieving information for 400,000 vertices takes 0.51 seconds.
  • Retrieving information for 400,000 hyperedges takes 2.52 seconds.

This example demonstrates the efficiency of Hypergraph-DB, even when working with large-scale hypergraphs. Below is a detailed table showing how the performance scales as the size of the hypergraph increases.

Detailed Performance Results

The following table shows the results of stress tests performed on Hypergraph-DB with varying scales. The tests measure the time taken to add vertices, add hyperedges, and query vertices and hyperedges.

Key Observations:

1. Scalability:
   Hypergraph-DB scales efficiently with the number of vertices and hyperedges. The time to add vertices and hyperedges grows linearly with the size of the hypergraph.

2. Query Performance:
   Querying vertices and hyperedges remains fast, even for large-scale hypergraphs. For instance:

   • Querying 200,000 vertices takes only 0.22 seconds.
   • Querying 200,000 hyperedges takes only 1.20 seconds.

3. Total Time:
   The total time to construct and query a hypergraph with 1,000,000 vertices and 200,000 hyperedges is only 6.60 seconds, showcasing the overall efficiency of Hypergraph-DB.

This performance makes Hypergraph-DB a great choice for applications requiring fast and scalable hypergraph data management.

✨ Features

Core Capabilities

• 🎯 Hypergraph Management: Full CRUD operations for vertices and hyperedges
• 🔗 Relationship Queries: Efficient neighbor and incident edge discovery
• 📊 Data Persistence: Reliable serialization with pickle support
• 🎨 Visual Exploration: Interactive web interface for graph visualization
• ⚙️ Extensible Design: Built on dataclasses for easy customization

🚀 Installation

Quick Start with uv (Recommended)

uv is the fastest Python package manager - 10-100x faster than pip!

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# or: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Install Hypergraph-DB
uv pip install hypergraph-db

Traditional Installation

pip install hypergraph-db

Development Setup

# Clone the repository
git clone https://github.com/iMoonLab/Hypergraph-DB.git
cd Hypergraph-DB

# Quick setup with uv
uv sync

# Or with traditional tools
pip install -e ".[dev]"

Development Commands

Once you have the project set up, use these convenient commands:

🚀 Quick Start

Ready to build hypergraphs? Here's how to get started with Hypergraph-DB!

1. Create a Hypergraph

from hyperdb import HypergraphDB

# Initialize the hypergraph
hg = HypergraphDB()

# Add vertices
hg.add_v(1, {"name": "Alice", "age": 30, "city": "New York"})
hg.add_v(2, {"name": "Bob", "age": 24, "city": "Los Angeles"})
hg.add_v(3, {"name": "Charlie", "age": 28, "city": "Chicago"})
hg.add_v(4, {"name": "David", "age": 35, "city": "Miami"})
hg.add_v(5, {"name": "Eve", "age": 22, "city": "Seattle"})
hg.add_v(6, {"name": "Frank", "age": 29, "city": "Houston"})
hg.add_v(7, {"name": "Grace", "age": 31, "city": "Phoenix"})
hg.add_v(8, {"name": "Heidi", "age": 27, "city": "San Francisco"})
hg.add_v(9, {"name": "Ivan", "age": 23, "city": "Denver"})
hg.add_v(10, {"name": "Judy", "age": 26, "city": "Boston"})

# Add hyperedges
hg.add_e((1, 2, 3), {"type": "friendship", "duration": "5 years"})
hg.add_e((1, 4), {"type": "mentorship", "topic": "career advice"})
hg.add_e((2, 5, 6), {"type": "collaboration", "project": "AI Research"})
hg.add_e((4, 5, 7, 9), {"type": "team", "goal": "community service"})
hg.add_e((3, 8), {"type": "partnership", "status": "ongoing"})
hg.add_e((9, 10), {"type": "neighbors", "relationship": "friendly"})
hg.add_e((1, 2, 3, 7), {"type": "collaboration", "field": "music"})
hg.add_e((2, 6, 9), {"type": "classmates", "course": "Data Science"})

2. Query Vertices and Hyperedges

# Get all vertices and hyperedges
print(hg.all_v)  # Output: {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
print(hg.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (3, 8), (1, 2, 3), (2, 6, 9), (1, 4), (1, 2, 3, 7), (2, 5, 6)}

# Query a specific vertex
print(hg.v(1))  # Output: {'name': 'Alice', 'age': 30, 'city': 'New York'}

# Query a specific hyperedge
print(hg.e((1, 2, 3)))  # Output: {'type': 'friendship', 'duration': '5 years'}

3. Update and Remove Vertices/Hyperedges

# Update a vertex
hg.update_v(1, {"name": "Smith"})
print(hg.v(1))  # Output: {'name': 'Smith', 'age': 30, 'city': 'New York'}

# Remove a vertex
hg.remove_v(3)
print(hg.all_v)  # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}
print(hg.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (1, 4), (2, 5, 6)}

# Remove a hyperedge
hg.remove_e((1, 4))
print(hg.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (2, 5, 6)}

4. Calculate Degrees

# Get the degree of a vertex
print(hg.degree_v(1))  # Example Output: 2

# Get the degree of a hyperedge
print(hg.degree_e((2, 5, 6)))  # Example Output: 3

5. Neighbor Queries

# Get neighbors of a vertex
print(hg.nbr_v(1))  # Example Output: {2, 7}
hg.add_e((1, 4, 6), {"relation": "team"})
print(hg.nbr_v(1))  # Example Output: {2, 4, 6, 7}

# Get incident hyperedges of a vertex
print(hg.nbr_e_of_v(1))  # Example Output: {(1, 2, 7), (1, 2), (1, 4, 6)}

6. Persistence (Save and Load)

# Save the hypergraph to a file
hg.save("my_hypergraph.hgdb")

# Load the hypergraph from a file
hg2 = HypergraphDB(storage_file="my_hypergraph.hgdb")
print(hg2.all_v)  # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}
print(hg2.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (1, 4, 6), (2, 5, 6)}

7. 🎨 Interactive Visualization

Explore your hypergraphs visually with the built-in web-based visualization tool:

# Launch interactive visualization
hg.draw()

✨ Visualization Features:

• 🌐 Real-time Web Interface: Automatic browser launch with local server
• 🔍 Interactive Exploration: Navigate vertices and hyperedges with ease
• 📊 Rich Information Display: View properties, degrees, and relationships
• 🎯 Smart Sorting: Vertices ordered by degree for quick insights
• 📱 Responsive Design: Works on desktop and mobile browsers

💡 Pro Tip: The visualization reflects your hypergraph's current state in real-time!

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.

💬 Contact & Support