{"id":28124864,"url":"https://github.com/imoonlab/hypergraph-db","last_synced_at":"2025-05-14T09:19:43.866Z","repository":{"id":268254455,"uuid":"902948161","full_name":"iMoonLab/Hypergraph-DB","owner":"iMoonLab","description":"Hypergraph Database.","archived":false,"fork":false,"pushed_at":"2024-12-22T09:54:16.000Z","size":62,"stargazers_count":20,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T05:04:48.211Z","etag":null,"topics":["hypergraph","hypergraph-neural-networks","hypergraphs","visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iMoonLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-13T15:48:07.000Z","updated_at":"2025-04-25T08:01:31.000Z","dependencies_parsed_at":"2024-12-16T06:20:58.786Z","dependency_job_id":null,"html_url":"https://github.com/iMoonLab/Hypergraph-DB","commit_stats":null,"previous_names":["imoonlab/hyper-db","imoonlab/hypergraph-db"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FHypergraph-DB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FHypergraph-DB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FHypergraph-DB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iMoonLab%2FHypergraph-DB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iMoonLab","download_url":"https://codeload.github.com/iMoonLab/Hypergraph-DB/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110403,"owners_count":22016392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hypergraph","hypergraph-neural-networks","hypergraphs","visualization"],"created_at":"2025-05-14T09:19:27.922Z","updated_at":"2025-05-14T09:19:43.848Z","avatar_url":"https://github.com/iMoonLab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\" id=\"top\"\u003e \n  \u003cimg src=\"docs/_static/logo.svg\" alt=\"Hyper DB\"  width=\"30%\" height=\"50%\" /\u003e\n\n  \u0026#xa0;\n\n  \u003c!-- \u003ca href=\"https://hyperdb.netlify.app\"\u003eDemo\u003c/a\u003e --\u003e\n\u003c/div\u003e\n\n\u003ch1 align=\"center\"\u003eHypergraph-DB\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Github top language\" src=\"https://img.shields.io/github/languages/top/iMoonLab/Hypergraph-DB?color=800080\"\u003e\n\n  \u003cimg alt=\"Github language count\" src=\"https://img.shields.io/github/languages/count/iMoonLab/Hypergraph-DB?color=800080\"\u003e\n\n  \u003cimg alt=\"PyPI version\" src=\"https://img.shields.io/pypi/v/hypergraph-db?color=purple\"\u003e\n  \n  \u003c!-- \u003cimg alt=\"Downloads\" src=\"https://pepy.tech/badge/hypergraph-db?color=purple\"\u003e --\u003e\n\n  \u003cimg alt=\"Repository size\" src=\"https://img.shields.io/github/repo-size/iMoonLab/Hypergraph-DB?color=800080\"\u003e\n\n  \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/iMoonLab/Hypergraph-DB?color=800080\"\u003e\n\n  \u003c!-- \u003cimg alt=\"Github issues\" src=\"https://img.shields.io/github/issues/iMoonLab/Hypergraph-DB?color=800080\" /\u003e --\u003e\n\n  \u003c!-- \u003cimg alt=\"Github forks\" src=\"https://img.shields.io/github/forks/iMoonLab/Hypergraph-DB?color=800080\" /\u003e --\u003e\n\n  \u003cimg alt=\"Github stars\" src=\"https://img.shields.io/github/stars/iMoonLab/Hypergraph-DB?color=800080\" /\u003e\n\u003c/p\u003e\n\n\u003c!-- Status --\u003e\n\n\u003c!-- \u003ch4 align=\"center\"\u003e \n\t🚧  Hyper DB 🚀 Under construction...  🚧\n\u003c/h4\u003e \n\n\u003chr\u003e --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#dart-about\"\u003eAbout\u003c/a\u003e \u0026#xa0; | \u0026#xa0; \n  \u003ca href=\"#sparkles-features\"\u003eFeatures\u003c/a\u003e \u0026#xa0; | \u0026#xa0;\n  \u003ca href=\"#rocket-installation\"\u003eInstallation\u003c/a\u003e \u0026#xa0; | \u0026#xa0;\n  \u003ca href=\"#checkered_flag-starting\"\u003eStarting\u003c/a\u003e \u0026#xa0; | \u0026#xa0;\n  \u003ca href=\"#memo-license\"\u003eLicense\u003c/a\u003e \u0026#xa0; | \u0026#xa0;\n  \u003ca href=\"#email-contact\"\u003eContact\u003c/a\u003e \u0026#xa0; | \u0026#xa0;\n  \u003ca href=\"https://github.com/yifanfeng97\" target=\"_blank\"\u003eAuthor\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n## :dart: About \n\nHypergraph-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.\n\nHypergraph-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.\n\n**:bar_chart: Performance Test Results**\n\nTo demonstrate the performance of **Hypergraph-DB**, let’s consider an example:\n\n- Suppose we want to construct a **hypergraph** with **1,000,000 vertices** and **200,000 hyperedges**.\n- Using Hypergraph-DB, it takes approximately:\n  - **1.75 seconds** to add **1,000,000 vertices**.\n  - **1.82 seconds** to add **200,000 hyperedges**.\n- Querying this hypergraph:\n  - Retrieving information for **400,000 vertices** takes **0.51 seconds**.\n  - Retrieving information for **400,000 hyperedges** takes **2.52 seconds**.\n\nThis 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.\n\n**Detailed Performance Results**\n\nThe 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.\n\n| **Number of Vertices** | **Number of Hyperedges** | **Add Vertices (s)** | **Add Edges (s)** | **Query Vertices (s/queries)** | **Query Edges (s/queries)** | **Total Time (s)** |\n|-------------------------|--------------------------|-----------------------|-------------------|-------------------------------|----------------------------|--------------------|\n| 5,000                  | 1,000                   | 0.01                 | 0.01             | 0.00/2,000                   | 0.01/2,000                | 0.02               |\n| 10,000                 | 2,000                   | 0.01                 | 0.01             | 0.00/4,000                   | 0.02/4,000                | 0.05               |\n| 25,000                 | 5,000                   | 0.03                 | 0.04             | 0.01/10,000                  | 0.05/10,000               | 0.13               |\n| 50,000                 | 10,000                  | 0.06                 | 0.07             | 0.02/20,000                  | 0.12/20,000               | 0.26               |\n| 100,000                | 20,000                  | 0.12                 | 0.17             | 0.04/40,000                  | 0.24/40,000               | 0.58               |\n| 250,000                | 50,000                  | 0.35                 | 0.40             | 0.11/100,000                 | 0.61/100,000              | 1.47               |\n| 500,000                | 100,000                 | 0.85                 | 1.07             | 0.22/200,000                 | 1.20/200,000              | 3.34               |\n| 1,000,000              | 200,000                 | 1.75                 | 1.82             | 0.51/400,000                 | 2.52/400,000              | 6.60               |\n\n---\n\n**Key Observations:**\n\n1. **Scalability**:  \n   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.\n\n2. **Query Performance**:  \n   Querying vertices and hyperedges remains fast, even for large-scale hypergraphs. For instance:\n   - Querying **200,000 vertices** takes only **0.22 seconds**.\n   - Querying **200,000 hyperedges** takes only **1.20 seconds**.\n\n3. **Total Time**:  \n   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.\n\nThis performance makes **Hypergraph-DB** a great choice for applications requiring fast and scalable hypergraph data management.\n\n---\n\n## :sparkles: Features \n\n:heavy_check_mark: **Flexible Hypergraph Representation**  \n   - Supports vertices (`v`) and hyperedges (`e`), where hyperedges can connect any number of vertices.\n   - Hyperedges are represented as sorted tuples of vertex IDs, ensuring consistency and efficient operations.\n\n:heavy_check_mark: **Vertex and Hyperedge Management**  \n   - Add, update, delete, and query vertices and hyperedges with ease.\n   - Built-in methods to retrieve neighbors, incident edges, and other relationships.\n\n:heavy_check_mark: **Neighbor Queries**  \n   - Get neighboring vertices or hyperedges for a given vertex or hyperedge.\n\n:heavy_check_mark: **Persistence**  \n   - Save and load hypergraphs to/from disk using efficient serialization (`pickle`).\n   - Ensures data integrity and supports large-scale data storage.\n\n:heavy_check_mark: **Customizable and Extensible**  \n   - Built on Python’s `dataclasses`, making it easy to extend and customize for specific use cases.\n\n---\n\n## :rocket: Installation \n\n\nHypergraph-DB is a Python library. You can install it directly from PyPI using `pip`.\n\n```bash\npip install hypergraph-db\n```\n\nYou can also install it by cloning the repository or adding it to your project manually. Ensure you have Python 3.10 or later installed.\n\n```bash\n# Clone the repository\ngit clone https://github.com/iMoonLab/Hypergraph-DB.git\ncd Hypergraph-DB\n\n# Install dependencies (if any)\npip install -r requirements.txt\n```\n\n---\n\n## :checkered_flag: Starting \n\nThis 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.\n\n#### **1. Create a Hypergraph**\n\n```python\nfrom hyperdb import HypergraphDB\n\n# Initialize the hypergraph\nhg = HypergraphDB()\n\n# Add vertices\nhg.add_v(1, {\"name\": \"Alice\", \"age\": 30, \"city\": \"New York\"})\nhg.add_v(2, {\"name\": \"Bob\", \"age\": 24, \"city\": \"Los Angeles\"})\nhg.add_v(3, {\"name\": \"Charlie\", \"age\": 28, \"city\": \"Chicago\"})\nhg.add_v(4, {\"name\": \"David\", \"age\": 35, \"city\": \"Miami\"})\nhg.add_v(5, {\"name\": \"Eve\", \"age\": 22, \"city\": \"Seattle\"})\nhg.add_v(6, {\"name\": \"Frank\", \"age\": 29, \"city\": \"Houston\"})\nhg.add_v(7, {\"name\": \"Grace\", \"age\": 31, \"city\": \"Phoenix\"})\nhg.add_v(8, {\"name\": \"Heidi\", \"age\": 27, \"city\": \"San Francisco\"})\nhg.add_v(9, {\"name\": \"Ivan\", \"age\": 23, \"city\": \"Denver\"})\nhg.add_v(10, {\"name\": \"Judy\", \"age\": 26, \"city\": \"Boston\"})\n\n# Add hyperedges\nhg.add_e((1, 2, 3), {\"type\": \"friendship\", \"duration\": \"5 years\"})\nhg.add_e((1, 4), {\"type\": \"mentorship\", \"topic\": \"career advice\"})\nhg.add_e((2, 5, 6), {\"type\": \"collaboration\", \"project\": \"AI Research\"})\nhg.add_e((4, 5, 7, 9), {\"type\": \"team\", \"goal\": \"community service\"})\nhg.add_e((3, 8), {\"type\": \"partnership\", \"status\": \"ongoing\"})\nhg.add_e((9, 10), {\"type\": \"neighbors\", \"relationship\": \"friendly\"})\nhg.add_e((1, 2, 3, 7), {\"type\": \"collaboration\", \"field\": \"music\"})\nhg.add_e((2, 6, 9), {\"type\": \"classmates\", \"course\": \"Data Science\"})\n```\n\n#### **2. Query Vertices and Hyperedges**\n\n```python\n# Get all vertices and hyperedges\nprint(hg.all_v)  # Output: {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}\nprint(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)}\n\n# Query a specific vertex\nprint(hg.v(1))  # Output: {'name': 'Alice', 'age': 30, 'city': 'New York'}\n\n# Query a specific hyperedge\nprint(hg.e((1, 2, 3)))  # Output: {'type': 'friendship', 'duration': '5 years'}\n```\n\n#### **3. Update and Remove Vertices/Hyperedges**\n\n```python\n# Update a vertex\nhg.update_v(1, {\"name\": \"Smith\"})\nprint(hg.v(1))  # Output: {'name': 'Smith', 'age': 30, 'city': 'New York'}\n\n# Remove a vertex\nhg.remove_v(3)\nprint(hg.all_v)  # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}\nprint(hg.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (1, 4), (2, 5, 6)}\n\n# Remove a hyperedge\nhg.remove_e((1, 4))\nprint(hg.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (2, 5, 6)}\n```\n\n#### **4. Calculate Degrees**\n\n```python\n# Get the degree of a vertex\nprint(hg.degree_v(1))  # Example Output: 2\n\n# Get the degree of a hyperedge\nprint(hg.degree_e((2, 5, 6)))  # Example Output: 3\n```\n\n#### **5. Neighbor Queries**\n\n```python\n# Get neighbors of a vertex\nprint(hg.nbr_v(1))  # Example Output: {2, 7}\nhg.add_e((1, 4, 6), {\"relation\": \"team\"})\nprint(hg.nbr_v(1))  # Example Output: {2, 4, 6, 7}\n\n# Get incident hyperedges of a vertex\nprint(hg.nbr_e_of_v(1))  # Example Output: {(1, 2, 7), (1, 2), (1, 4, 6)}\n```\n\n#### **6. Persistence (Save and Load)**\n\n```python\n# Save the hypergraph to a file\nhg.save(\"my_hypergraph.hgdb\")\n\n# Load the hypergraph from a file\nhg2 = HypergraphDB(storage_file=\"my_hypergraph.hgdb\")\nprint(hg2.all_v)  # Output: {1, 2, 4, 5, 6, 7, 8, 9, 10}\nprint(hg2.all_e)  # Output: {(4, 5, 7, 9), (9, 10), (1, 2, 7), (1, 2), (2, 6, 9), (1, 4, 6), (2, 5, 6)}\n```\n\n\n--- \n\n\n## :memo: License \n\nHypergraph-DB is open-source and licensed under the [Apache License 2.0](LICENSE). Feel free to use, modify, and distribute it as per the license terms.\n\n\n---\n\n## :email: Contact \n\nHypergraph-DB is maintained by [iMoon-Lab](http://moon-lab.tech/), Tsinghua University. If you have any questions, please feel free to contact us via email: [Yifan Feng](mailto:evanfeng97@gmail.com).\n\n\nMade with :heart: by \u003ca href=\"https://github.com/yifanfeng97\" target=\"_blank\"\u003eYifan Feng\u003c/a\u003e\n\n\u0026#xa0;\n\n\u003ca href=\"#top\"\u003eBack to top\u003c/a\u003e\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimoonlab%2Fhypergraph-db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimoonlab%2Fhypergraph-db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimoonlab%2Fhypergraph-db/lists"}