This project is an implementation for various variants of binary decision diagrams that is used at Microsoft Research. It focuses on high performance, usability, and correctness. The library currently maintains 100% code coverage.
Just add the project to your visual studio solution or add the package from nuget.
To import the library, add the following line to your file:
using DecisionDiagrams;A simple use of the library is shown shown below:
// create a manager that uses chain-reduced binary decision diagrams
var manager = new DDManager<CBDDNode>(new CBDDNodeFactory());
// allocate three variables, two booleans and one 32-bit integer
// the internal ordering will match the order allocated from the manager.
var a = manager.CreateBool();
var b = manager.CreateBool();
var c = manager.CreateInt32();
// build formulas from the variables.
DD f1 = manager.Or(a.Id(), b.Id());
DD f2 = manager.And(c.GreaterOrEqual(1), c.LessOrEqual(4));
// get a satisfying assignment for a formula
var assignment = manager.Sat(manager.And(f1, f2));
// get the values as C# objects
bool valuea = assignment.Get(a); // valuea = false
bool valueb = assignment.Get(b); // valueb = true
int valuec = assignment.Get(c); // valuec = 1You can find more detailed examples in the tests.
The library is based on the cache-optimized implementation of decision diagrams here, and implements three variants:
- Binary decision diagrams (link)
- Zero-suppressed binary decision diagrams (link)
- Chain-reduced binary decision diagrams (link)
Internally decision diagram nodes are represented using integer ids that are bit-packed with other metadata such as a garbage collection mark bit, and a complemented bit. User references to nodes (DD type) are maintained through a separate (smaller) table.
The DD reference table uses WeakReference wrappers to integrate with the .NET garbage collector. This means that users of the library do not need to perform any reference counting, which is common in BDD libraries. Nodes are maintained in a memory pool and the library maintains the invariant that a node allocated before another will appear earlier in this pool. This allows for various optimizations when looking up nodes in the unique table. To maintain this invariant, the library implements a mark, sweep, and shift garbage collector that compacts nodes when necessary.
By hashconsing nodes in the unique table, the library ensures that two boolean functions are equal if and only if their pointers (indices) are equal. The unique table maintains all nodes and is periodically resized when out of memory. For performance reasons, we ensure that this table is always a power of two size. This makes allocating new space a bit inflexible (harder to use all memory) but in return makes all operations faster. To compensate for this inflexible allocation scheme, the library becomes more reluctant to resize the table as the number of nodes grows.
The library makes use of "complement edges" (a single bit packed into the node id), which determines whether the formula represented by the node is negated. This ensures that all negation operations take constant time and also reduces memory consumption since a formula and its negation share the same representation. The implementation also includes a compressed node type CBDDNode which can offer large memory savings in many cases.
Internally, the manager only supports a single operation: and, but then leverages free negation to support other operations efficiently. This does make some operations such as ite and iff more costly, but can improve cache behavior since there is now only a single operation cache. Because "and" is commutative, the cache can further order the arguments to avoid redundant entries. Currently, the library does not support dynamic variable reordering as well as a number of operations such as functional composition.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.