{"id":29884178,"url":"https://github.com/marcelwa/aigverse","last_synced_at":"2025-07-31T14:33:00.213Z","repository":{"id":255445939,"uuid":"852386601","full_name":"marcelwa/aigverse","owner":"marcelwa","description":"A Python library for working with logic networks, synthesis, and optimization.","archived":false,"fork":false,"pushed_at":"2025-07-28T08:02:30.000Z","size":1200,"stargazers_count":63,"open_issues_count":10,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-28T09:08:02.635Z","etag":null,"topics":["aig","aiger","logic-optimization","logic-synthesis","machine-learning","python","verilog"],"latest_commit_sha":null,"homepage":"https://aigverse.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcelwa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/support.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-04T18:05:23.000Z","updated_at":"2025-07-28T08:01:43.000Z","dependencies_parsed_at":"2024-09-13T17:28:02.521Z","dependency_job_id":"81cb8b1b-7749-4775-a802-e8fddc5358f4","html_url":"https://github.com/marcelwa/aigverse","commit_stats":null,"previous_names":["marcelwa/aigverse"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/marcelwa/aigverse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelwa%2Faigverse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelwa%2Faigverse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelwa%2Faigverse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelwa%2Faigverse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcelwa","download_url":"https://codeload.github.com/marcelwa/aigverse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelwa%2Faigverse/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268057119,"owners_count":24188614,"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","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aig","aiger","logic-optimization","logic-synthesis","machine-learning","python","verilog"],"created_at":"2025-07-31T14:30:33.534Z","updated_at":"2025-07-31T14:33:00.201Z","avatar_url":"https://github.com/marcelwa.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aigverse: A Python Library for Logic Networks, Synthesis, and Optimization\n\n[![CI](https://img.shields.io/github/actions/workflow/status/marcelwa/aigverse/aigverse-pypi-deployment.yml?label=CI\u0026logo=github\u0026style=flat-square)](https://github.com/marcelwa/aigverse/actions/workflows/aigverse-pypi-deployment.yml)\n[![Documentation Status](https://img.shields.io/readthedocs/aigverse?label=Docs\u0026logo=readthedocs\u0026style=flat-square)](https://aigverse.readthedocs.io/)\n[![PyPI](https://img.shields.io/static/v1?label=PyPI\u0026message=aigverse\u0026logo=pypi\u0026color=informational\u0026style=flat-square)](https://pypi.org/project/aigverse/)\n[![License](https://img.shields.io/github/license/marcelwa/aigverse?label=License\u0026style=flat-square)](https://github.com/marcelwa/aigverse/blob/main/LICENSE)\n[![Release](https://img.shields.io/github/v/release/marcelwa/aigverse?label=aigverse\u0026style=flat-square)](https://github.com/marcelwa/aigverse/releases)\n\n\u003e [!Important]\n\u003e This project is still in the early stages of development. The API is subject to change, and some features may not be\n\u003e fully implemented. I appreciate your patience and understanding as work to improve the library continues.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://aigverse.readthedocs.io\"\u003e\n   \u003cpicture\u003e\n     \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/marcelwa/aigverse/refs/heads/main/docs/_static/aigverse_logo_dark_mode.svg\" width=\"60%\"\u003e\n     \u003cimg src=\"https://raw.githubusercontent.com/marcelwa/aigverse/refs/heads/main/docs/_static/aigverse_logo_light_mode.svg\" width=\"60%\" alt=\"aigverse logo\"\u003e\n   \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n`aigverse` is a Python framework designed to bridge the gap between logic synthesis and AI/ML applications. It allows\nyou to represent and manipulate logic circuits efficiently, making it easier to integrate logic synthesis tasks into\nmachine learning pipelines. `aigverse` is built directly upon the powerful [EPFL Logic Synthesis Libraries](https://arxiv.org/abs/1805.05121),\nparticularly [mockturtle](https://github.com/lsils/mockturtle), providing a high-level Python interface to\nstate-of-the-art algorithms for And-Inverter Graph (AIG) manipulation and logic synthesis, widely used in formal\nverification, hardware design, and optimization tasks.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://aigverse.readthedocs.io/\"\u003e\n  \u003cimg width=30% src=\"https://img.shields.io/badge/documentation-blue?style=for-the-badge\u0026logo=read%20the%20docs\" alt=\"Documentation\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## ✨ Features\n\n- **Efficient Logic Representation**: Use And-Inverter Graphs (AIGs) to model and manipulate logic circuits in Python.\n- **File Format Support**: Read and write AIGER, Verilog, Bench, PLA, ... files for interoperability with other logic\n  synthesis tools.\n- **C++ Backend**: Leverage the performance of the EPFL Logic Synthesis Libraries for fast logic synthesis and\n  optimization.\n- **High-Level API**: Simplify logic synthesis tasks with a Pythonic interface for AIG manipulation and optimization.\n- **Integration with Machine Learning**: Convenient integration with popular data science libraries.\n\n## 🤔 Motivation\n\nAs AI and machine learning (ML) increasingly impact hardware design automation, there's a growing need for tools that\nintegrate logic synthesis with ML workflows. `aigverse` provides a Python-friendly interface for logic synthesis, making\nit easier to develop applications that blend both AI/ML and traditional circuit synthesis techniques. By building upon the\nrobust foundation of the EPFL Logic Synthesis Libraries, `aigverse` delivers powerful logic manipulation capabilities while\nmaintaining accessibility through its Python interface. With `aigverse`, you can parse, manipulate, and optimize logic circuits\ndirectly from Python. Eventually, we aim to provide seamless integration with popular ML libraries, enabling the development\nof novel AI-driven synthesis and optimization tools.\n\n## 📦 Installation\n\n`aigverse` is built using the EPFL Logic Synthesis Libraries with [pybind11](https://github.com/pybind/pybind11).\nIt is available via PyPI for all major operating systems and supports Python 3.9 to 3.13.\n\n```bash\npip install aigverse\n```\n\n### 🔌 Adapters\n\nTo keep the core library lightweight, machine learning integration adapters are not installed by default. These adapters\nenable seamless conversion of AIGs to graph and array formats for use with ML and data science libraries (such as\n[NetworkX](https://networkx.org/), [NumPy](https://numpy.org/), etc.). To install `aigverse` with the adapters extra,\nuse:\n\n```bash\npip install aigverse[adapters]\n```\n\nThis will install additional dependencies required for ML workflows. See the\n[documentation](https://aigverse.readthedocs.io/en/latest/installation.html#machine-learning-adapters) for more details.\n\n## 🚀 Usage\n\nThe following gives a shallow overview on `aigverse`. Detailed documentation and examples are available at\n[ReadTheDocs](https://aigverse.readthedocs.io/).\n\n### 🏗️ Basic Example: Creating an AIG\n\nIn `aigverse`, you can create a simple And-Inverter Graph (AIG) and manipulate it using various logic operations.\n\n```python\nfrom aigverse import Aig\n\n# Create a new AIG network\naig = Aig()\n\n# Create primary inputs\nx1 = aig.create_pi()\nx2 = aig.create_pi()\n\n# Create logic gates\nf_and = aig.create_and(x1, x2)  # AND gate\nf_or = aig.create_or(x1, x2)  # OR gate\n\n# Create primary outputs\naig.create_po(f_and)\naig.create_po(f_or)\n\n# Print the size of the AIG network\nprint(f\"AIG Size: {aig.size()}\")\n```\n\nNote that all primary inputs (PIs) must be created before any logic gates.\n\n### 🔍 Iterating over AIG Nodes\n\nYou can iterate over all nodes in the AIG, or specific subsets like the primary inputs or only logic nodes (gates).\n\n```python\n# Iterate over all nodes in the AIG\nfor node in aig.nodes():\n    print(f\"Node: {node}\")\n\n# Iterate only over primary inputs\nfor pi in aig.pis():\n    print(f\"Primary Input: {pi}\")\n\n# Iterate only over logic nodes (gates)\nfor gate in aig.gates():\n    print(f\"Gate: {gate}\")\n\n# Iterate over the fanins of a node\nn_and = aig.get_node(f_and)\nfor fanin in aig.fanins(n_and):\n    print(f\"Fanin of {n_and}: {fanin}\")\n```\n\n### 📏 Depth and Level Computation\n\nYou can compute the depth of the AIG network and the level of each node. Depth information is useful for estimating the\ncritical path delay of a respective circuit.\n\n```python\nfrom aigverse import DepthAig\n\ndepth_aig = DepthAig(aig)\nprint(f\"Depth: {depth_aig.num_levels()}\")\nfor node in aig.nodes():\n    print(f\"Level of {node}: {depth_aig.level(node)}\")\n```\n\n### 🕸️ AIGs with Fanout Information\n\nIf needed, you can retrieve the fanouts of AIG nodes as well:\n\n```python\nfrom aigverse import FanoutAig\n\nfanout_aig = FanoutAig(aig)\nn_and = aig.get_node(f_and)\n# Iterate over the fanouts of a node\nfor fanout in fanout_aig.fanouts(n_and):\n    print(f\"Fanout of node {n_and}: {fanout}\")\n```\n\n### 🔄 Sequential AIGs\n\n`aigverse` also supports sequential AIGs, which are AIGs with registers.\n\n```python\nfrom aigverse import SequentialAig\n\nseq_aig = SequentialAig()\nx1 = seq_aig.create_pi()  # Regular PI\nx2 = seq_aig.create_ro()  # Register output (sequential PI)\n\nf_and = seq_aig.create_and(x1, x2)  # AND gate\n\nseq_aig.create_ri(f_and)  # Register input (sequential PO)\n\nprint(seq_aig.registers())  # Prints the association of registers\n```\n\nIt is to be noted that the construction of sequential AIGs comes with some caveats:\n\n1. All register outputs (ROs) must be created after all primary inputs (PIs).\n2. All register inputs (RIs) must be created after all primary outputs (POs).\n3. As for regular AIGs, all PIs and ROs must be created before any logic gates.\n\n### ⚡ Logic Optimization\n\nYou can optimize AIGs using various algorithms. For example, you can perform _resubstitution_ to simplify logic using\nshared divisors. Similarly, _refactoring_ collapses maximal fanout-free cones (MFFCs) into truth tables and resynthesizes\nthem into new structures. Cut _rewriting_ optimizes the AIG by replacing cuts with improved ones from a pre-computed NPN\ndatabase. Finally, _balancing_ performs (E)SOP factoring to minimize the number of levels in the AIG.\n\n```python\nfrom aigverse import aig_resubstitution, sop_refactoring, aig_cut_rewriting, balancing\n\n# Clone the AIG network for size comparison\naig_clone = aig.clone()\n\n# Optimize the AIG with several optimization algorithms\nfor optimization in [aig_resubstitution, sop_refactoring, aig_cut_rewriting, balancing]:\n    optimization(aig)\n\n# Print the size of the unoptimized and optimized AIGs\nprint(f\"Original AIG Size:  {aig_clone.size()}\")\nprint(f\"Optimized AIG Size: {aig.size()}\")\n```\n\n### ✅ Equivalence Checking\n\nEquivalence of AIGs (e.g., after optimization) can be checked using SAT-based equivalence checking.\n\n```python\nfrom aigverse import equivalence_checking\n\n# Perform equivalence checking\nequiv = equivalence_checking(aig1, aig2)\n\nif equiv:\n    print(\"AIGs are equivalent!\")\nelse:\n    print(\"AIGs are NOT equivalent!\")\n```\n\n### 📄 File Format Support\n\nYou can read and write AIGs in various file formats, including (ASCII) [AIGER](https://fmv.jku.at/aiger/), gate-level\nVerilog and PLA.\n\n#### ✏️ Writing\n\n```python\nfrom aigverse import write_aiger, write_verilog, write_dot\n\n# Write an AIG network to an AIGER file\nwrite_aiger(aig, \"example.aig\")\n# Write an AIG network to a Verilog file\nwrite_verilog(aig, \"example.v\")\n# Write an AIG network to a DOT file\nwrite_dot(aig, \"example.dot\")\n```\n\n#### 👓 Parsing\n\n```python\nfrom aigverse import (\n    read_aiger_into_aig,\n    read_ascii_aiger_into_aig,\n    read_verilog_into_aig,\n    read_pla_into_aig,\n)\n\n# Read AIGER files into AIG networks\naig1 = read_aiger_into_aig(\"example.aig\")\naig2 = read_ascii_aiger_into_aig(\"example.aag\")\n# Read a Verilog file into an AIG network\naig3 = read_verilog_into_aig(\"example.v\")\n# Read a PLA file into an AIG network\naig4 = read_pla_into_aig(\"example.pla\")\n```\n\nAdditionally, you can read AIGER files into sequential AIGs using `read_aiger_into_sequential_aig` and\n`read_ascii_aiger_into_sequential_aig`.\n\n### 🥒 `pickle` Support\n\nAIGs support Python's `pickle` protocol, allowing you to serialize and deserialize AIG objects for persistent storage or\ninterface with data science or machine learning workflows.\n\n```python\nimport pickle\n\nwith open(\"aig.pkl\", \"wb\") as f:\n    pickle.dump(aig, f)\n\nwith open(\"aig.pkl\", \"rb\") as f:\n    unpickled_aig = pickle.load(f)\n```\n\nYou can also pickle multiple AIGs at once by storing them in a tuple or list.\n\n### 🧠 Machine Learning Integration\n\nWith the `adapters` extra, you can convert an AIG to a [NetworkX](https://networkx.org/) directed graph, enabling\nvisualization and use with graph-based ML tools:\n\n```python\nimport aigverse.adapters\n\nG = aig.to_networkx(levels=True, fanouts=True, node_tts=True)\n```\n\nGraph, node, and edge attributes provide logic, level, fanout, and function information for downstream ML or\nvisualization tasks.\n\nFor more details and examples, see the\n[machine learning integration documentation](https://aigverse.readthedocs.io/en/latest/machine_learning.html).\n\n### 🔢 Truth Tables\n\nSmall Boolean functions can be efficiently represented using truth tables. `aigverse` enables the creation and\nmanipulation of truth tables by wrapping a portion of the [kitty](https://github.com/msoeken/kitty) library.\n\n#### 🎉 Creation\n\n```python\nfrom aigverse import TruthTable\n\n# Initialize a truth table with 3 variables\ntt = TruthTable(3)\n# Create a truth table from a hex string representing the MAJ function\ntt.create_from_hex_string(\"e8\")\n```\n\n#### 🔧 Manipulation\n\n```python\n# Flip each bit in the truth table\nfor i in range(tt.num_bits()):\n    print(f\"Flipping bit {int(tt.get_bit(i))}\")\n    tt.flip_bit(i)\n\n# Print a binary string representation of the truth table\nprint(tt.to_binary())\n\n# Clear the truth table\ntt.clear()\n\n# Check if the truth table is constant 0\nprint(tt.is_const0())\n```\n\n#### 🔣 Symbolic Simulation of AIGs\n\n```python\nfrom aigverse import simulate, simulate_nodes\n\n# Obtain the truth table of each AIG output\ntts = simulate(aig)\n\n# Print the truth tables\nfor i, tt in enumerate(tts):\n    print(f\"PO{i}: {tt.to_binary()}\")\n\n# Obtain the truth tables of each node in the AIG\nn_to_tt = simulate_nodes(aig)\n\n# Print the truth tables of each node\nfor node, tt in n_to_tt.items():\n    print(f\"Node {node}: {tt.to_binary()}\")\n```\n\n#### 📃 Exporting as Lists or NumPy Arrays\n\nFor machine learning applications, it is often useful to convert truth tables into standard data structures like Python\nlists or NumPy arrays. Since `TruthTable` objects are iterable, conversion is straightforward.\n\n```python\nimport numpy as np\n\n# Export to a list\ntt_list = list(tt)\n\n# Export to NumPy arrays\ntt_np_bool = np.array(tt)\ntt_np_int = np.array(tt, dtype=np.int32)\ntt_np_float = np.array(tt, dtype=np.float64)\n```\n\n#### 🥒 `pickle` Support\n\nTruth tables also support Python's `pickle` protocol, allowing you to serialize and deserialize them.\n\n```python\nimport pickle\n\nwith open(\"tt.pkl\", \"wb\") as f:\n    pickle.dump(tt, f)\n\nwith open(\"tt.pkl\", \"rb\") as f:\n    unpickled_tt = pickle.load(f)\n```\n\n## 🙌 Contributing\n\nContributions are welcome! If you'd like to contribute to `aigverse`, please see the\n[contribution guide](https://aigverse.readthedocs.io/en/latest/contributing.html). I appreciate feedback and suggestions\nfor improving the library.\n\n## 💼 Support and Consulting\n\n`aigverse` is and will always be a free, open-source library. If you or your organization require dedicated support,\nspecific new features, or integration of `aigverse` into your projects, professional consulting services are available.\nThis is a great way to get the features you need while also supporting the ongoing maintenance and development of the\nlibrary.\n\nFor inquiries, please reach out to [@marcelwa](https://github.com/marcelwa/). More information can be found in the\n[documentation](https://aigverse.readthedocs.io/en/latest/support.html).\n\n## 📜 License\n\n`aigverse` is available under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelwa%2Faigverse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcelwa%2Faigverse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelwa%2Faigverse/lists"}