About | Features | Installation | Starting | License | Contact | Author
Hypergraph-DB is a lightweight, flexible, and Python-based database designed to model and manage hypergraphs—a generalized graph structure where edges (hyperedges) can connect any number of vertices. This makes Hypergraph-DB an ideal solution for representing complex relationships between entities in various domains, such as knowledge graphs, social networks, and scientific data modeling.
Hypergraph-DB provides a high-level abstraction for working with vertices and hyperedges, making it easy to add, update, query, and manage hypergraph data. With built-in support for persistence, caching, and efficient operations, Hypergraph-DB simplifies the management of hypergraph data structures.
📊 Performance Test Results
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.
| Number of Vertices | Number of Hyperedges | Add Vertices (s) | Add Edges (s) | Query Vertices (s/queries) | Query Edges (s/queries) | Total Time (s) |
|---|---|---|---|---|---|---|
| 5,000 | 1,000 | 0.01 | 0.01 | 0.00/2,000 | 0.01/2,000 | 0.02 |
| 10,000 | 2,000 | 0.01 | 0.01 | 0.00/4,000 | 0.02/4,000 | 0.05 |
| 25,000 | 5,000 | 0.03 | 0.04 | 0.01/10,000 | 0.05/10,000 | 0.13 |
| 50,000 | 10,000 | 0.06 | 0.07 | 0.02/20,000 | 0.12/20,000 | 0.26 |
| 100,000 | 20,000 | 0.12 | 0.17 | 0.04/40,000 | 0.24/40,000 | 0.58 |
| 250,000 | 50,000 | 0.35 | 0.40 | 0.11/100,000 | 0.61/100,000 | 1.47 |
| 500,000 | 100,000 | 0.85 | 1.07 | 0.22/200,000 | 1.20/200,000 | 3.34 |
| 1,000,000 | 200,000 | 1.75 | 1.82 | 0.51/400,000 | 2.52/400,000 | 6.60 |
Key Observations:
-
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. -
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.
-
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.
✔️ Flexible Hypergraph Representation
- Supports vertices (
v) and hyperedges (e), where hyperedges can connect any number of vertices. - Hyperedges are represented as sorted tuples of vertex IDs, ensuring consistency and efficient operations.
✔️ Vertex and Hyperedge Management
- Add, update, delete, and query vertices and hyperedges with ease.
- Built-in methods to retrieve neighbors, incident edges, and other relationships.
✔️ Neighbor Queries
- Get neighboring vertices or hyperedges for a given vertex or hyperedge.
✔️ Persistence
- Save and load hypergraphs to/from disk using efficient serialization (
pickle). - Ensures data integrity and supports large-scale data storage.
✔️ Customizable and Extensible
- Built on Python’s
dataclasses, making it easy to extend and customize for specific use cases.
Hypergraph-DB is a Python library. You can install it directly from PyPI using pip.
pip install hypergraph-dbYou can also install it by cloning the repository or adding it to your project manually. Ensure you have Python 3.10 or later installed.
# Clone the repository
git clone https://github.com/iMoonLab/Hypergraph-DB.git
cd Hypergraph-DB
# Install dependencies (if any)
pip install -r requirements.txtThis section provides a quick guide to get started with Hypergraph-DB, including iusage, and running basic operations. Below is an example of how to use Hypergraph-DB, based on the provided test cases.
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"})# 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'}# 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)}# 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# 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)}# 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)}Hypergraph-DB is open-source and licensed under the Apache License 2.0. Feel free to use, modify, and distribute it as per the license terms.
Hypergraph-DB is maintained by iMoon-Lab, Tsinghua University. If you have any questions, please feel free to contact us via email: Yifan Feng.
Made with ❤️ by Yifan Feng