{"id":23498119,"url":"https://github.com/tulip-control/dd","last_synced_at":"2025-05-15T13:08:40.107Z","repository":{"id":22023391,"uuid":"25349468","full_name":"tulip-control/dd","owner":"tulip-control","description":"Binary Decision Diagrams (BDDs) in pure Python and Cython wrappers of CUDD, Sylvan, and BuDDy","archived":false,"fork":false,"pushed_at":"2025-04-15T12:48:01.000Z","size":1436,"stargazers_count":198,"open_issues_count":2,"forks_count":40,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-12T01:17:16.360Z","etag":null,"topics":["bdd","binary-decision-diagrams","cudd","cython","python","sylvan","zdd"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/dd","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tulip-control.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-17T09:13:07.000Z","updated_at":"2025-04-23T06:57:32.000Z","dependencies_parsed_at":"2024-06-18T18:31:23.380Z","dependency_job_id":"09808d36-3f5c-435a-8dcf-562326deeb51","html_url":"https://github.com/tulip-control/dd","commit_stats":{"total_commits":1352,"total_committers":7,"mean_commits":"193.14285714285714","dds":"0.020710059171597628","last_synced_commit":"a011a427b6c3adaa1a465638ad509d3f99c0fcb7"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulip-control%2Fdd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulip-control%2Fdd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulip-control%2Fdd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tulip-control%2Fdd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tulip-control","download_url":"https://codeload.github.com/tulip-control/dd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"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":["bdd","binary-decision-diagrams","cudd","cython","python","sylvan","zdd"],"created_at":"2024-12-25T05:18:49.904Z","updated_at":"2025-05-15T13:08:35.099Z","avatar_url":"https://github.com/tulip-control.png","language":"Python","readme":"[![Build Status][build_img]][ci]\n\n\nAbout\n=====\n\nA pure-Python (Python \u003e= 3.11) package for manipulating:\n\n- [Binary decision diagrams](\n    https://en.wikipedia.org/wiki/Binary_decision_diagram) (BDDs).\n- [Multi-valued decision diagrams](\n    https://dx.doi.org/10.1109/ICCAD.1990.129849) (MDDs).\n\nas well as [Cython](https://cython.org) bindings to the C libraries:\n\n- [CUDD](\n    https://web.archive.org/web/20180127051756/http://vlsi.colorado.edu/~fabio/CUDD/html/index.html)\n  (also read [the introduction](\n    https://web.archive.org/web/20150317121927/http://vlsi.colorado.edu/~fabio/CUDD/node1.html),\n  and note that the original link for CUDD is \u003chttp://vlsi.colorado.edu/~fabio/CUDD/\u003e)\n- [Sylvan](https://github.com/utwente-fmt/sylvan) (multi-core parallelization)\n- [BuDDy](https://sourceforge.net/projects/buddy/)\n\nThese bindings expose almost identical interfaces as the Python implementation.\nThe intended workflow is:\n\n- develop your algorithm in pure Python (easy to debug and introspect),\n- use the bindings to benchmark and deploy\n\nYour code remains the same.\n\n\nContains:\n\n- All the standard functions defined, e.g.,\n  by [Bryant](https://www.cs.cmu.edu/~bryant/pubdir/ieeetc86.pdf).\n- Dynamic variable reordering using [Rudell's sifting algorithm](\n    http://www.eecg.toronto.edu/~ece1767/project/rud.pdf).\n- Reordering to obtain a given order.\n- Parser of quantified Boolean expressions in either\n  [TLA+](https://en.wikipedia.org/wiki/TLA%2B) or\n  [Promela](https://en.wikipedia.org/wiki/Promela) syntax.\n- Pre/Image computation (relational product).\n- Renaming variables.\n- Zero-omitted binary decision diagrams (ZDDs) in CUDD\n- Conversion from BDDs to MDDs.\n- Conversion functions to [`networkx`](https://networkx.org) and\n  [DOT](https://www.graphviz.org/doc/info/lang.html) graphs.\n- BDDs have methods to `dump` and `load` them using [JSON](\n    https://wikipedia.org/wiki/JSON), or [`pickle`](\n    https://docs.python.org/3/library/pickle.html).\n- BDDs dumped by CUDD's DDDMP can be loaded using fast iterative parser.\n- [Garbage collection](\n    https://en.wikipedia.org/wiki/Garbage_collection_(computer_science))\n  that combines reference counting and tracing\n\n\nIf you prefer to work with integer variables instead of Booleans, and have\nBDD computations occur underneath, then use the module\n[`omega.symbolic.fol`](\n    https://github.com/tulip-control/omega/blob/main/omega/symbolic/fol.py)\nfrom the [`omega` package](\n    https://github.com/tulip-control/omega/blob/main/doc/doc.md).\n\nIf you are interested in computing minimal covers (two-level logic minimization)\nthen use the module `omega.symbolic.cover` of the `omega` package.\nThe method `omega.symbolic.fol.Context.to_expr` converts BDDs to minimal\nformulas in disjunctive normal form (DNF).\n\n\nDocumentation\n=============\n\nIn the [Markdown](https://en.wikipedia.org/wiki/Markdown) file\n[`doc.md`](https://github.com/tulip-control/dd/blob/main/doc.md).\n\nThe [changelog](https://en.wiktionary.org/wiki/changelog) is in\nthe file [`CHANGES.md`](\n    https://github.com/tulip-control/dd/blob/main/CHANGES.md).\n\n\nExamples\n========\n\nThe module `dd.autoref` wraps the pure-Python BDD implementation `dd.bdd`.\nThe API of `dd.cudd` is almost identical to `dd.autoref`.\nYou can skip details about `dd.bdd`, unless you want to implement recursive\nBDD operations at a low level.\n\n\n```python\nfrom dd.autoref import BDD\n\nbdd = BDD()\nbdd.declare('x', 'y', 'z', 'w')\n\n# conjunction (in TLA+ syntax)\nu = bdd.add_expr(r'x /\\ y')\n    # symbols `\u0026`, `|` are supported too\n    # note the \"r\" before the quote,\n    # which signifies a raw string and is\n    # needed to allow for the backslash\nprint(u.support)\n# substitute variables for variables (rename)\nrename = dict(x='z', y='w')\nv = bdd.let(rename, u)\n# substitute constants for variables (cofactor)\nvalues = dict(x=True, y=False)\nv = bdd.let(values, u)\n# substitute BDDs for variables (compose)\nd = dict(x=bdd.add_expr(r'z \\/ w'))\nv = bdd.let(d, u)\n# as Python operators\nv = bdd.var('z') \u0026 bdd.var('w')\nv = ~ v\n# quantify universally (\"forall\")\nu = bdd.add_expr(r'\\A x, y:  (x /\\ y) =\u003e y')\n# quantify existentially (\"exist\")\nu = bdd.add_expr(r'\\E x, y:  x \\/ y')\n# less readable but faster alternative,\n# (faster because of not calling the parser;\n# this may matter only inside innermost loops)\nu = bdd.var('x') | bdd.var('y')\nu = bdd.exist(['x', 'y'], u)\nassert u == bdd.true, u\n# inline BDD references\nu = bdd.add_expr(rf'x /\\ {v}')\n# satisfying assignments (models):\n# an assignment\nd = bdd.pick(u, care_vars=['x', 'y'])\n# iterate over all assignments\nfor d in bdd.pick_iter(u):\n    print(d)\n# how many assignments\nn = bdd.count(u)\n# write to and load from JSON file\nfilename = 'bdd.json'\nbdd.dump(filename, roots=dict(res=u))\nother_bdd = BDD()\nroots = other_bdd.load(filename)\nprint(other_bdd.vars)\n```\n\nTo run the same code with CUDD installed, change the first line to:\n\n```python\nfrom dd.cudd import BDD\n```\n\nMost useful functionality is available via methods of the class `BDD`.\nA few of the functions can prove useful too, among them `to_nx()`.\nUse the method `BDD.dump` to write a `BDD` to a `pickle` file, and\n`BDD.load` to load it back. A CUDD dddmp file can be loaded using\nthe function `dd.dddmp.load`.\n\nA `Function` object wraps each BDD node and decrements its reference count\nwhen disposed by Python's garbage collector. Lower-level details are\ndiscussed in the documentation.\n\nFor using ZDDs, change the first line to\n\n```python\nfrom dd.cudd_zdd import ZDD as BDD\n```\n\n\nInstallation\n============\n\n\n## pure-Python\n\nFrom the [Python Package Index (PyPI)](https://pypi.org) using the\npackage installer [`pip`](https://pip.pypa.io):\n\n```shell\npip install dd\n```\n\nor from the directory of source files:\n\n```shell\npip install .\n```\n\nFor graph layout, install also [graphviz](https://graphviz.org).\n\nThe `dd` package requires Python 3.11 or later.\nFor Python 2.7, use `dd == 0.5.7`.\n\n\n## Cython bindings\n\nTo compile also the module `dd.cudd` (which interfaces to CUDD)\nwhen installing from PyPI, run:\n\n```shell\npip install --upgrade wheel cython\nexport DD_FETCH=1 DD_CUDD=1\npip install dd -vvv --use-pep517 --no-build-isolation\n```\n\n(`DD_FETCH=1 DD_CUDD=1 pip install dd` also works,\nwhen the source tarball includes cythonized code.)\n\nTo confirm that the installation succeeded:\n\n```shell\npython -c 'import dd.cudd'\n```\n\nThe [environment variables](\n    https://en.wikipedia.org/wiki/Environment_variable)\nabove mean:\n- `DD_FETCH=1`: download CUDD v3.0.0 sources from the internet,\n  unpack the tarball (after checking its hash), and `make` CUDD.\n- `DD_CUDD=1`: build the Cython module `dd.cudd`\n\nMore about environment variables that configure the\nC extensions of `dd` is described in the file [`doc.md`](\n    https://github.com/tulip-control/dd/blob/main/doc.md)\n\n\n## Wheel files with compiled CUDD\n\n[Wheel files](\n    https://www.python.org/dev/peps/pep-0427/)\nare [available from PyPI](\n    https://pypi.org/project/dd/#files),\nwhich contain the module `dd.cudd`,\nwith the CUDD library compiled and linked.\nIf you have a Linux system and Python version compatible with\none of the PyPI wheels,\nthen `pip install dd` will install also `dd.cudd`.\n\n\n### Licensing of the compiled modules `dd.cudd` and `dd.cudd_zdd` in the wheel\n\nThese notes apply to the compiled modules `dd.cudd` and `dd.cudd_zdd` that are\ncontained in the [wheel file](https://www.python.org/dev/peps/pep-0427/) on\nPyPI (namely the files `dd/cudd.cpython-39-x86_64-linux-gnu.so` and\n`dd/cudd_zdd.cpython-39-x86_64-linux-gnu.so` in the [`*.whl` file](\n    https://pypi.org/project/dd/#files), which can\nbe obtained using [`unzip`](http://infozip.sourceforge.net/UnZip.html)).\nThese notes do not apply to the source code of the modules\n`dd.cudd` and `dd.cudd_zdd`.\nThe source distribution of `dd` on PyPI is distributed under a 3-clause BSD\nlicense.\n\nThe following libraries and their headers were used when building the modules\n`dd.cudd` and `dd.cudd_zdd` that are included in the wheel:\n\n- Python: \u003chttps://www.python.org/ftp/python/3.A.B/Python-3.A.B.tgz\u003e\n  (where `A` and `B` the numerals of\n   the corresponding Python version used;\n   for example `10` and `2` to signify Python 3.10.2).\n  CPython releases are described at:\n    \u003chttps://www.python.org/downloads/\u003e\n- [CUDD](https://sourceforge.net/projects/cudd-mirror/files/cudd-3.0.0.tar.gz/download).\n\nThe licenses of Python and CUDD are included in the wheel archive.\n\nCython [does not](https://github.com/cython/cython/blob/master/COPYING.txt)\nadd its license to C code that it generates.\n\nGCC was used to compile the modules `dd.cudd` and `dd.cudd_zdd` in the wheel,\nand the GCC [runtime library exception](\n    https://github.com/gcc-mirror/gcc/blob/master/COPYING.RUNTIME#L61-L66)\napplies.\n\nThe modules `dd.cudd` and `dd.cudd_zdd` in the wheel dynamically link to the:\n\n- Linux kernel (in particular [`linux-vdso.so.1`](\n    https://man7.org/linux/man-pages/man7/vdso.7.html)),\n  which allows system calls (read the kernel's file [`COPYING`](\n    https://github.com/torvalds/linux/blob/master/COPYING) and the explicit\n  syscall exception in the file [`LICENSES/exceptions/Linux-syscall-note`](\n    https://github.com/torvalds/linux/blob/master/LICENSES/exceptions/Linux-syscall-note))\n- [GNU C Library](https://www.gnu.org/software/libc/) (glibc) (in particular\n  `libpthread.so.0`, `libc.so.6`, `/lib64/ld-linux-x86-64.so.2`), which uses\n  the [LGPLv2.1](https://sourceware.org/git/?p=glibc.git;a=blob_plain;f=COPYING.LIB;hb=HEAD)\n  that allows dynamic linking, and other [licenses](\n    https://sourceware.org/git/?p=glibc.git;a=blob_plain;f=LICENSES;hb=HEAD).\n  These licenses are included in the wheel file and apply to the GNU C Library\n  that is dynamically linked.\n\n\nTests\n=====\n\nUse [`pytest`](https://pypi.org/project/pytest). Run with:\n\n```shell\npushd tests/\npytest -v --continue-on-collection-errors .\npopd\n```\n\nTests of Cython modules that were not installed will fail.\nThe code is covered well by tests.\n\n\nLicense\n=======\n[BSD-3](https://opensource.org/licenses/BSD-3-Clause), read file `LICENSE`.\n\n\n[build_img]: https://github.com/tulip-control/dd/actions/workflows/main.yml/badge.svg?branch=main\n[ci]: https://github.com/tulip-control/dd/actions\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulip-control%2Fdd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftulip-control%2Fdd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftulip-control%2Fdd/lists"}