{"id":25534932,"url":"https://github.com/diegojromerolopez/djbdd","last_synced_at":"2025-11-11T20:22:27.350Z","repository":{"id":9365801,"uuid":"11220797","full_name":"diegojromerolopez/djbdd","owner":"diegojromerolopez","description":"Java BDD implementation based on hashmaps.","archived":false,"fork":false,"pushed_at":"2020-09-05T08:49:36.000Z","size":55336,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-05-11T04:01:16.122Z","etag":null,"topics":["binary-decision-diagrams","genetic-algorithm","heuristics","java","logic","reduction"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diegojromerolopez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-06T16:23:48.000Z","updated_at":"2021-09-09T09:49:05.000Z","dependencies_parsed_at":"2022-09-22T16:31:59.065Z","dependency_job_id":null,"html_url":"https://github.com/diegojromerolopez/djbdd","commit_stats":null,"previous_names":[],"tags_count":1,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diegojromerolopez%2Fdjbdd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diegojromerolopez%2Fdjbdd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diegojromerolopez%2Fdjbdd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diegojromerolopez%2Fdjbdd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diegojromerolopez","download_url":"https://codeload.github.com/diegojromerolopez/djbdd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239772252,"owners_count":19694412,"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":["binary-decision-diagrams","genetic-algorithm","heuristics","java","logic","reduction"],"created_at":"2025-02-20T03:29:17.195Z","updated_at":"2025-11-11T20:22:22.319Z","avatar_url":"https://github.com/diegojromerolopez.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"DJBDD\n=============\n\nWhat's this?\n-------------\nA Java 7 BDD package with the [GPL with classpath linking exception license](https://openjdk.java.net/legal/gplv2+ce.html) based on GPL version 2 or later, as you prefer. See [this explanation about the license](https://en.wikipedia.org/wiki/GPL_linking_exception). Howeer, if your use case requires other license, *I can re-license this project for you, please write me to my email (at the botton of this README)*.\n\nThis package provides a Binary Decision Diagram library you can use to\nmake operations with boolean logical formulas and study its properties.\n\nThis software has been developed by Diego J. Romero-López as a tool\nfor his [Master's Thesis](https://github.com/diegojromerolopez/djbdd/blob/master/doc/memoria.pdf?raw=true).\n\nHay una **versión en español de este documento** [aquí](https://github.com/diegojromerolopez/djbdd/blob/master/LEEME.md).\n\nIntroduction\n-------------\nA Binary Decision Diagram is a complete truth table of a boolean expression\nin a reduced graph form. For an introduction, see\n[Binary Decision Diagram on Wikipedia](http://en.wikipedia.org/wiki/Binary_decision_diagram).\n\nThis library provides all the operations you need to work with them.\n\nHow to use it\n-------------\n\n```java\n// These are the boolean variables used in our formulas\n// They can have any alphanumeric name you want starting with a letter and\n// being unique variable names.\nString[] variables={\"a\", \"b\", \"c\", \"d\", \"e\", \"f\"};\n\n// You always have to initialize the BDD system before you create any\n// BDD object. Be careful with that.\nBDD.init(variables);\n\n// The functions are specified as boolean expressions with Java syntax\n// adding the operators -\u003e (implication) and \u003c-\u003e (double implication)\nString function = \"(a \u0026\u0026 b) || (c \u0026\u0026 d)\";\n\n// The variable ordering is given by the order\n// of variables in the array of strings 'variables'.\n\n// Construction of a new BDD\nBDD bdd = new BDD(function);\n\n// Printing the BDD in the standard output\n// The internal table node will be shown by stdout\nbdd.print();\n\n// You can print it as a image PNG using a dot library\nPrinter.printBDD(bdd, \"bdd_\"+bdd.size());\n\n// Creating other BDDs:\nString function2 = \"(a \u0026\u0026 e) || f\"\nBDD bdd2 = new BDD(function2);\nbdd2.print();\n\n// Operations with BDDs\n\n// This BDD is the logical AND between bdd and bdd2\nBDD bdd3 = bdd.apply(\"and\", bdd2);\n\n// This BDD is the logical OR between bdd and bdd2\nBDD bdd4 = bdd.apply(\"or\", bdd2);\n\n// Destroy explicitly bdd2\n// In case we need to compute sizes, reduce the global graph or print it\nbdd2.delete();\n\n// If you think you can have few free memory,\n// you would have to free by calling the garbage collector\nBDD.gc();\n\n```\n\n### Complete tests ###\nThe main program of this library is full of examples.\nThe all-in-one jar version is located in **store/DJBDD.jar**,\nthe dependant on libraries jar one is in  **dist/DJBDD.jar**.\nYou should use **store/DJBDD.jar** for your experiments.\n\nEasiest option is opening this project with [Netbeans](https://netbeans.org/).\nThere are several executing configurations:\n- Two examples of computing consistency in the real world.\n- Six benchmark of BDD-reducing algorithms.\n- Tests that you can execute to verify BDD operations.\n\n#### Basic Options\n\n##### Output\n\n###### BDD print as image\n\n```bash\njava -jar DJBDD.jar --image --\u003cformat\u003e \u003cfile\u003e\n```\nNote that this option will work only if you are in a Linux/UNIX system\nwith the [dot](http://linux.die.net/man/1/dot) tool to draw graphs in the path **/usr/bin/dot**.\n\n###### BDD printing\n\n```bash\njava -jar DJBDD.jar --print --\u003cformat\u003e \u003cfile\u003e\n```\nPrints a BDD in the standard output.\n\n###### Restriction on BDD formats allowed\n\n- **dimacs**: Dimacs CNF format. See [SAT format](http://www.cs.ubc.ca/~hoos/SATLIB/Benchmarks/SAT/satformat.ps) or [CNF](http://people.sc.fsu.edu/~jburkardt/data/cnf/cnf.html) for more information.\n- **cstyle**: C-style boolean expression preceded by a line with all variables separated by commas. For example:\n  - a \u0026\u0026 !b\n  - a -\u003e (!b \u0026\u0026 (c || d))\n  - a \u003c-\u003e (b \u0026\u0026 !c)\n  - a != (b \u0026\u0026 !c)\n\n###### Restriction on variable naming\n\n**IMPORTANT**: for each variable there can no be any other that contains it as substring from the left.\nThat is, if we have a variable with the name 'x1' we cannot use other variable with the name 'x11'.\nIt's not in my future plans to change that, so name your variables with names like:\n- {x1}\n- {x11}\n- {x12}\n\n###### Other notes\n\n**Example source data**: directory **data** has some examples of each format (look the extension).\n\n##### BDD reduction benchmarks\nSee below for a description of each reduction method.\n\n```bash\n# Sifting Algorithm\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks/ sifting\n# Window Permutation Algorithm (window size = 2)\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks/ window_permutation window_size=2\n# Random Swapper\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks/ random_swapper random_seed=121481 iterations=100\n# Genetic Algorithm\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks-genetic genetic random_seed=10 population=8 generations=10 selection_percentage=0.2 mutation_probability=0.1\n# Memetic Algorithm\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks-memetic memetic random_seed=121481 population=8 generations=10 selection_percentage=0.2 mutation_probability=0.1\n## Iterative Sifting\njava -jar ./DJBDD/store/DJBDD.jar --memory-optimization-benchmark --dimacs ./data/benchmarks/ isifting iterations=100\n```\n\n\nFeatures\n-------------\n\n### Shared hash table ###\nAll BDDs use the same hash table, sharing the vertices and subgraphs.\nThe goal for using this data structure is reducing the number of repeated vertices.\nEach BDD has one root vertex though.\n\n### Rich I/O API ###\nThis library provides method to load logical clausules in DIMACS format\nand Java native, includen implication and double implication operators.\n\n### Memory efficient ###\nThis library shares vertices between different BDDs.\n\n### Vertices grouped by levels ###\nYou can access the vertices that has each variable in an efficient way. This will be used for BDD-reducing algorithms.\n\n### Operations implemented ###\n- Apply [6] [3].\n- Restrict. [2].\n- Swapping of two variables. [5].\n\n### Implemented Reduction Algorithms ###\nThis package contains many reduction algoritms.\nThey are implemented in the **djbdd.reductors** package.\n\nThese reduction algorithms are implemented as children classes of **djbdd.reductors.ReductionAlgorithm**,\nso they share the same API. This API contains a execute and run method. The first one must be overriden\nfor each particular reduction method while the second will act as a façade of execute. The run method\nalso measures the elapsed time in the reduction method for comparing the reduction algorithms\n\n```java\n// Some logic function used to build a BDD\nString function1 = \"(a \u0026\u0026 d) || (b \u0026\u0026 c)\";\nBDD bdd1 = new BDD(function1);\n\n// Call to garbage collector \u0026 print the\n// node table \nBDD.gc();\nBDD.T.print();\n        \nPrinter.printBDD(bdd1, \"test15_bdd1_BEFORE_\"+bdd1.size());\n\n// Construct a reduction algorithm. For example SiftingReductor:\nSiftingReductor reductor = new SiftingReductor();\n// Start the reduction process\nreductor.run();\n\n// Call to garbage collector \u0026 print the\n// node table (to compare with the first node table)\nBDD.gc();\nBDD.T.print();\n```\n\nIt is important to note that these reduction methods reduce all the BDDs created\nin the program because they reduce the vertex mesh by swapping vertex levels.\n\nThey are listed below:\n\n#### Window Permutation\nDeveloped in the class **djbdd.reductors.WindowPermutation**, this algorithm\nwas proposed by Fujita et al. \u0026 Ishiura et al. Richard L. Rudell described it\nand compared with its own reduction method in [7]. This implementation is based\non his description.\n\n```java\n// Window size\nint windowSize = 2;\nWindowPermutationReductor reductor = new WindowPermutationReductor(windowSize);\nreductor.run();\n```\n\n#### Rudell's Variable Sifting\nThis package contains a basic implementation of the variable reordering\nproposed by Richard L. Rudell in [7]. This method try to find the best\nposition for each variable keeping fixed in their position the rest.\n\nUse example:\n\n```java\nSiftingReductor reductor = new SiftingReductor();\nreductor.run();\n```\n\n#### Random Swapper Reduction\nWe wanted to compare a pure random algorithm with our evolutionary algorithms\nto test if our results are due to randomness or because this method truly works.\nThis reduction method is based in swapping two variables chosen at random in each iteration in the BDD tree.\n\n```java\nint iterations = 1000;\nRandomSwapperReductor reductor = new RandomSwapperReductor(iterations);\nreductor.run();\n```\n\nNote that this algorithm, the genetic algorithm and the memetic algorithm need\na random seed to be set before their execution.\n\n#### Genetic Reduction\nW. Lenders \u0026 C. Baier defined the genetic operators for developing a Genetic Algorithm\nfor this BDD reduction problem in [8]. We have implemeted a version of their approach\nin the **GeneticReductor** class.\n\n```java\n// Number of chromosomes\nint populationSize = 10;\n// Number of generations of the algorithm\nint generations = 1000;\n// % of population selected\ndouble selectionPercentage = 10;\n// Probability of mutating a gene in a chromosome\ndouble mutationProbability = 0.1;\nGeneticReductor reductor = new GeneticReductor(populationSize, generations, selectionPercentage, mutationProbability);\nreductor.run();\n```\n\n#### Memetic Reduction\n\nBased on [8], we propose another algorithm that combines the Genetic Algorithm optimizing\neach chromosome using the Rudell's Sifting Algorithm. Its name is **MemeticReductor** and its\nparameters are the same than the GeneticReductor.\n\n```java\n// Number of chromosomes\nint populationSize = 10;\n// Number of generations of the algorithm\nint generations = 1000;\n// % of population selected\ndouble selectionPercentage = 10;\n// Probability of mutating a gene in a chromosome\ndouble mutationProbability = 0.1;\nMemeticReductor reductor = new MemeticReductor(populationSize, generations, selectionPercentage, mutationProbability);\nreductor.run();\n```\n\n#### Iterative Sifting\n\n~~This is our original method [9] that applies a serious of sifting of variables with hopes of finding the best position for each one.~~\n\nNote that this approach seems to be almost equal to *Converging Sifting* made by R. Rudell in [Dynamic variable ordering for ordered binary decision diagrams](http://www.eecg.toronto.edu/~ece1767/project/rud.pdf).\n\n**IterativeSiftingReductor** contains this reduction method and can be used this way:\n\n```java\nint iterations = 100;\nIterativeSiftingReductor reductor = new IterativeSiftingReductor(iterations);\nreductor.run();\n```\n\nA paper with the description of this method is pending evalution.\n\n### TODOs ###\n- Include a parallel apply.\n- Parallelization of reduction methods.\n\nExamples\n-------------\n### Code examples ###\nLook the class Tester class in package djbdd.test, its full of examples.\n\nDocumentation\n-------------\nThere is a pdf file called [manual.pdf](https://github.com/diegojromerolopez/djbdd/blob/master/doc/manual.pdf?raw=true) with some remarks about the implementation and how to use this library.\nCurrently it is a work in progress, but you can read the tests, the code or ask me any question. If you are interested, there is also the Master's Thesis\n[Memoria del Trabajo Fin de Máster](https://github.com/diegojromerolopez/djbdd/blob/master/doc/memoria.pdf?raw=true) (only in Spanish).\n\nBibliography\n-------------\n[1] Symbolic Boolean Manipulation with Ordered Binary Decision Diagrams, Randal E. Bryant. Carnegie Mellon University.\n\n[2] Binary Decision Diagrams. Fabio Somenzi.\n\n[3] Efficient implementation of a BDD package, Karl S. Brace, Richard L. Rudell \u0026 Randal E. Bryant. \n\n[4] Implementation of an Efficient Parallel BDD Package. Tony Stornetta \u0026 Forrest Brewer.\n\n[5] Incremental  Reduction of Binary Decision Diagrams. R. Jacobi, N. Calazans \u0026 C. Trullemans.\n\n[6] An Introduction to Binary Decision Diagrams. Henrik Reif Andersen.\n\n[7] Dynamic variable ordering for ordered binary decision diagrams, Richard L. Rudell.\n\n[8] Genetic Algorithms for the Variable Ordering Problem of Binary Decision Diagrams, W. Lenders \u0026 C. Baier.\n\n~~[9] Iterative Sifting: A new approach to reduce BDD size. Diego J. Romero-López \u0026 Elena Ruiz-Larrocha. TBA.~~ Algorithm already published by other author.\n\nCites\n-------------\nPlease cite the author as *Diego J. Romero López* (*Diego J.* is author's name while *Romero López* is author's surname). If you want to write surname first, write *Romero López, Diego J.* In case you are interested, [read more about Spanish naming customs](https://en.wikipedia.org/wiki/Spanish_naming_customs).\n\n*If you use DJBDD and like to appear here, please send me an email*.\n\n- [CI Fallin](https://chrisfallin.com/) PhD thesis: [Finding and Exploiting Parallelism with Data-Structure-Aware Static and\nDynamic Analysis\"](https://chrisfallin.com/pubs/cfallin-dissertation.pdf).\n- [Scalable pointer analysis of data structures using semantic models](https://dl.acm.org/doi/abs/10.1145/3377555.3377885) ([pdf](https://dl.acm.org/doi/pdf/10.1145/3377555.3377885?download=true))\n\nFAQ\n-------------\n### I don't understand what is a BDD ###\nOK. The concept is not easy, read the Wikipedia page about them [Binary Decision Diagram at Wikipedia](http://en.wikipedia.org/wiki/Binary_decision_diagram) and later the reference [1] and [2].\n\n### Do you use complement arcs? ###\nNo. I don't use them. I understand they can reduce the size of the graph, but I wanted to make a pure BDD library. Maybe I could include them in some future version.\n\n### How can I import this project to my IDE? ###\nI've used Netbeans (yeah, I know it is ancient but works for me). You should be able to open with whatever IDE you use.\n\n### Can I use this library in Java5 or Java6? ###\nI suppose. I have not used it in Java 6, but it should work.\n\n### Are there some code examples? ###\nLook in the tests (**djbdd.test.Tester** class) and in the benchmarks.\n\n### I'm running the examples (or my custom code) and throws a exception ###\nIt depends on the exception type, but my money is on a memory-related exception.\nThis library is memory greedy, use **BDD.gc** or help me\nto implement some reduction method on the vertex table :)\n\n### Why don't you use dynamic variable ordering when creating the BDD? ###\nI prefer building the BDD \"as is\" and relying in the developer using some\nvariable reordering algorithm, like Variable Sifting, implemented in this\npackage.\n\n### Your code is inefficient/wrong/could be improved ###\nI accept suggestions, critiques and comments you want to communicate me. \n\n### Why don't you use \u003cwhatever\u003e method? ###\nMaybe I don't know it, please send me an email asking me and pointing me\nto a paper where it is explained. I will take a look to that.\n\n### What is the license of this code? ###\nThis code is **GPL3 with classpath linking exception**. That's the same license than the OpenJDK7 one.\nIf you are unsure about this kind of license, [read about it in](http://en.wikipedia.org/wiki/GPL_linking_exception).\n\n### Do you answer emails? ###\nOf course I will answer questions, suggestions and comments about this library.\n\n### Who are you? ###\nI'm Diego J., my email is die_gojr_om-erol-op_ez AT g-m-a-i-l.com\n(erase - and _ and replace AT with @). I'm from Spain and this is part of my master's final thesis.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiegojromerolopez%2Fdjbdd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiegojromerolopez%2Fdjbdd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiegojromerolopez%2Fdjbdd/lists"}