Initial revision

buddy/CHANGES

+----------------------------------------------------------------------------
+   Logfile for changes to the BDD package
+----------------------------------------------------------------------------
+
++  means added code
+x  means bugfix or changed code
+-  means removed code
+
+Thanks to the following people for bug reports, suggestions and source code:
+  Alan Mishchenko
+  Gerd Behrmann
+  Henrik Hulgaard
+  Henrik Reif Andersen
+  Jacob Lichtenberg
+  Ken Larsen
+  Nicola Soranzo
+  Nikolaj Bjorner
+
+
+VER 2.2 (november 2002)
+-----------------------
+  + Added bvec_ite() for calculating an if-then-else operation on
+    a boolean vector.
+  x Fixed some garbage collection problems introduced in version 2.1.
+
+
+VER 2.1 (march 2002)
+--------------------
+  + Added bdd_allsat() for calculating all possible variable assignments
+    to a bdd.
+  x Fixed some wrong garbage collection #defines in kernel.h. If you
+    haven't experinced any problems using BuDDy, then this should not
+    be an issue. No bug reports reported for this one - found by code
+    inspection thanx to Nicola Soranzo.
+  x Fixed some copy paste errors in the prime number calculation.
+    This should not be an issue. No bug reports reported for this one
+    - found by code inspection thanx to Nicola Soranzo.
+
+
+VER 2.0 (march 2001)
+--------------------
+  x Change the copyright notice to a more acceptable form.
+  x Speedup changes in bdd_support()
+  x Rewrote all the prime number calculations in order to get the
+    copyright right.
+
+
+VER 1.9 (august 2000)
+---------------------
+  + Added bdd_pathcount
+  + Added bdd_anodecount
+  + Added bdd_buildcube, bdd_ibuildcube
+  x Bugfix in bdd_satcountset and bdd_satcountlnset. This corrects a bug
+    introduced in version 1.8.
+  x bug fixes in bdd_constraint and bdd_simplify. Both did calculate a
+    correct cofactor, but not necessarily a minimal one. Changed the name
+    of bdd_constraint to bdd_constrain at the same time.
+  x bug fix in memory allocation for bdd_addvarblock
+  x Changed functions in bddop.c in order to avoid some compiler warnings.
+  x Makefile also installs "fdd.h" and "bvec.h".
+  x Small #include fix in N-Queen example.
+  x Minor changes in the documentation.
+
+
+VER 1.8 (may 2000)
+------------------
+  + Bugfix in the kernel: canonicity was not unfortunately not guaranteed
+    on certain compilers (at least the microsoft visual C compiler) due to a
+    signed/unsigned bug in kernel.c (and actually not microsofts fault).
+  + Speedups in the reordering code.
+  + Added the use of an interaction matrix for variable swapping.
+  + Added bdd_satoneset
+  + Added bdd_getallocnum
+  + Added bdd_setvarorder
+  + Added bdd_unique, bdd_appuni.
+  + Added bvec_shlfixed, bvec_shrfixed and changed the prototype for
+    bvec_shl and bvec_shr.
+  + Added bvec_mulfixed, bdd_divfixed, bdd_div and changed the
+    prototype for bvec_mul.
+  + Added bdd_printstat
+  + Added new examples: solitare and money
+  + Forces cache tables to prime-number size.
+  + Added bdd_clear_error() if anybody needs that.
+  + Added reorder method WIN3 and WIN3ITE
+  x Small change in queen.cxx - with a huge impact on runtime!
+  x Bugfix in reordering. In some cases reordering would go on forever;
+    first reroder, then retry, then reorder again without resize etc. always
+    reordering in the same operation. Now at most one reordering is allowed
+    for each bdd operation.
+  x Bugfix in C++ printing in Dot format. Wrote zero for one and vice versa.
+  x Bugfix in the garbage collector. If bdd_setmaxincrease was used, then
+    BuDDy would call bdd_error prematurely. Not a major bug, but annoying.
+  x Bugfix in bdd_load.
+  x Speedup in bdd_satcountset and bdd_satcountlnset
+  x Updates to the docs.
+  x Updates to the makefiles
+
+
+VER 1.7 (september 1999)
+------------------------
+  +  Added support for boolean vector operations used in integer arithmetics
+  +  Split "bdd.h" into "bdd.h", "fdd.h" and "bvec.h"
+  +  Added bdd_cachestats
+  +  Added bdd_and, bdd_or, bdd_xor, bdd_impl, bdd_biimpl
+     (wrappers for bdd_apply).
+  +  Added a BDD calculator for combinatorial circuits as an example.
+  +  Added an example showing the use of the FDD interface.
+  +  Added bdd_autoreorder_times, bdd_getreorder_method, bdd_getreorder_times,
+     bdd_reorder_probe, bdd_enable_reorder, bdd_disable_reorder,
+     bdd_var2level, bdd_level2var, bdd_reorder_gain, bdd_swapvar
+  +  Added bdd_file_hook, bdd_strm_hook, fdd_file_hook, fdd_strm_hook
+  +  Added support for dynamic resizing of the operator caches with
+     the function bdd_setcacheratio.
+  +  Added more documentation.
+  x  Bugfix in reordering code. This would appear when recursive variable
+     blocks were defined (blocks with sub-blocks).
+  x  Speedup changes in the variable reordering code
+  x  The automatic reordering threshhold function has been changed
+  x  Automatic reordering is now interrupting and restarts bdd operations
+  x  Prototype for bdd_reorder_hook changed.
+  x  Printing of reorder information (verbose level > 0) is changed.
+  x  The threshold for stopping of the iterative reordering methods has
+     been changed. The reordering now continues until no progress is done
+     at all (before it would stop when less than 5% where gained).
+  x Added a few sanity checks to many of the functions.
+  x Bugfix (parameter checking) in fdd_ithvar.
+  - bdd_varlevel removed (use bdd_var2level and bdd_level2var).
+
+
+VER 1.6 (november 1998)
+-----------------------
+  +  Added bdd_resetpair
+  +  Added bdd_satcountset, bdd_satcountlnset
+  +  Added macro bdd_relprod
+  +  Added fdd_overlapdomain
+  +  Added fdd_domain
+  x  Fixed a bug in bdd_setvarnum and bdd_extvarnum.
+  x  Fixed a bug in bdd_newpair() which would give problems with reordering.
+  x  Speedup changes in bdd_exist, bdd_forall, bdd_appex, bdd_appall
+  x  Speedup changes in bdd_restrict
+  x  Changed bdd_gbc_hook to include both pre and post garbage collection.
+
+
+VER 1.5 (september 1998)
+------------------------
+  +  Added bdd_cofactor
+  +  Added and fixed some error checks in fdd.c
+  x  Fixed a bug in bdd_setvarnum().
+
+
+VER 1.4 (july 1998)
+-------------------
+  The package just got a name: BuDDy
+  +  Added functions bdd_compose, bdd_veccompose, bdd_ite.
+  +  Added functions bdd_setbddpair, bdd_setbddpairs.
+  +  Added functions bdd_var, bdd_low, bdd_high.
+  +  Added technical documentation in docs/tech.txt
+  x  Overloaded C++ functions are not used any more. This mainly changes
+     the name of the printing functions in C++.
+  x  Changed datatype names (You'll hate me for this one):
+        BddPair -> bddPair
+	BddStat -> bddStat
+	BddGbcStat -> bddGbcStat
+  x  Added slightly more documentation.
+  x  Some internal changes to the code - should not be visible to users.
+
+
+VER 1.3 (june 1998)
+-------------------
+  x  Fixed a few serious bugs in the reordering code
+
+
+VER 1.2 (june 1998)
+-------------------
+  +  Added support for dynamic variable reordering
+  +  Added reordering handler (bdd_reorder_hook)
+  +  More added to the docs
+  x  Changed the event handlers (bdd_xxx_hook)
+
+
+VER 1.1 (april 1998)
+--------------------
+  +  Added bdd_varprofile
+  +  Added fdd_scanset
+  +  Mucho better documentation.
+  +  Added Henrik Reif Andersen's BDD notes to the documentation.
+  +  Added BDD_REORDER_RANDOM for test purposes (usefull for others?)
+  x  Fixed a bug in bdd_appex and bdd_appall.
+  x  Fixed a bug in bdd_simplify.
+  x  Speed fixup to fdd_extdomain 
+  x  Lots of small (insignificant?) bug fixes in fdd.c.
+  x  bdd_load/save updated to take reordering into account.
+  x  Generalized bdd_restrict to use a BDD variable set.
+  x  Fixed the identifiers for the operator caches.
+  x  The math functions log1p and pow2 has been removed as they didn't
+     exist on some systems. The same applies to M_LN2.
+  x  New file structure and makefiles.
+  -  Removed bdd_break, bdd_restart1
+
+

buddy/README

+==========================================================================
+                              *** BuDDy ***
+                         Binary Decision Diagrams
+                           Library Package v2.2
+--------------------------------------------------------------------------
+               Copyright (C) 1996-2002 by Jorn Lind-Nielsen
+                            All rights reserved
+
+    Permission is hereby granted, without written agreement and without
+    license or royalty fees, to use, reproduce, prepare derivative
+    works, distribute, and display this software and its documentation
+    for any purpose, provided that (1) the above copyright notice and
+    the following two paragraphs appear in all copies of the source code
+    and (2) redistributions, including without limitation binaries,
+    reproduce these notices in the supporting documentation. Substantial
+    modifications to this software may be copyrighted by their authors
+    and need not follow the licensing terms described here, provided
+    that the new terms are clearly indicated in all files where they apply.
+
+    IN NO EVENT SHALL JORN LIND-NIELSEN, OR DISTRIBUTORS OF THIS
+    SOFTWARE BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
+    INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS
+    SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHORS OR ANY OF THE
+    ABOVE PARTIES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+    JORN LIND-NIELSEN SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
+    BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
+    ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO
+    OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
+    MODIFICATIONS.
+==========================================================================
+
+
+
+---------------------------------------------------------------------
+--- REQUIREMENTS ----------------------------------------------------
+---------------------------------------------------------------------
+
+* A (not to old) C++ compiler
+* A machine that supports 32 bit integers
+
+
+---------------------------------------------------------------------
+--- INSTALLING ------------------------------------------------------
+---------------------------------------------------------------------
+
+2) Edit the file "config" to specify your compiler options and
+where the package is to be installed.
+
+3) type "make" to make the binary.
+
+4) type "make install" to copy the BDD files to their appropriate
+directories.
+
+5) type "make examples" to make the examples
+
+
+---------------------------------------------------------------------
+--- USING -----------------------------------------------------------
+---------------------------------------------------------------------
+
+Assuming that the files "bdd.h" and "libbdd.a" are in directories
+"/usr/local/include" and "/usr/local/lib" then the compile command
+could be:
+
+ g++ -I/usr/local/include myfile.cc -o myfile -L/usr/local/lib -lbdd
+
+Your machine may be setup to use the above directories auto-
+matically, so you might be able to do:
+
+ g++ myfile.cc -o myfile -lbdd
+
+
+---------------------------------------------------------------------
+--- FILES -----------------------------------------------------------
+---------------------------------------------------------------------
+
+src:           All files needed for the BuDDy package.
+examples:      Example files
+  fdd:         An example of use of the FDD interface.
+  calculator:  An example of a BDD calculator. Uses reordering.
+  adder:       Construction of a N-bit adder. Uses reordering.
+  milner:      A calculation of the reachable statespace for Milner's
+               scheduler. C++.
+  cmilner:     As above but purely in ANSI-C.
+  queen:       Solution to the N-queen chess problem.
+  solitare:    Solution to a solitare game.
+  money:       Solution to the send-more-money problem (bvec demo).
+  internal:    Some internal regression tests.
+doc:           Documentation.
+  buddy.ps:    Package documentation.
+  bddnotes.ps: BDD introduction notes.
+
+
+---------------------------------------------------------------------
+--- FEEDBACK --------------------------------------------------------
+---------------------------------------------------------------------
+
+Please do not hesitate to send any questions or bug reports to:
+
+  Jorn Lind-Nielsen:  buddy@itu.dk
+  (or maybe jorn_lind_nielsen@hotmail.com or jln@fjeldgruppen.dk)
+
+It may take some time to get an answer since BuDDy do not have that
+much focus any more - but I'll try to give a reasonable answer
+in (finite) time.
+
+New updates and other info can be found at:
+
+  http://www.it-c.dk/research/buddy/
+  (or http://www.itu.dk/research/buddy)
+
+
+Hope you find some use for this software
+
+      Jorn Lind-Nielsen
+

buddy/config

+# ==============================================================
+# Makefile for the BuDDy package
+# - Edit the lines below to configure
+# ==============================================================
+
+# --- Your compiler flags
+CFLAGS = -g -ansi -Wmissing-prototypes -Wall
+
+# --- Where to install the library (directory, no trailing slash)
+LIBDIR = /usr/local/lib
+
+# --- Where to install the include file (directory, no trailing slash)
+INCDIR = /usr/local/include
+
+# --- Your C compiler
+CC = gcc
+
+# --- Your C++ compiler
+CPP = g++
+
+# Some machines are missing "CLOCKS_PER_SEC". Please define a default value
+# If you do not know this, then leave it as it is.
+CLOCK=60
+
+CLOCKFLAG = -DDEFAULT_CLOCK=$(CLOCK)
+
+# Debugging and statistical flags. Possible values are:
+# -DSWAPCOUNT  :  Count number of fundamental variable swaps
+# -DCACHESTATS :  Gather statistical information about operator and
+#                 unique node caching
+DEBUGFLAGS =
+
+# Some of the BuDDy library needs 64 bit arithmetics.
+# With gnu C++, Microsoft C++ and KAI C++ this is part of the
+# language and used by BuDDy. With other compilers BuDDy need
+# to implement the math it self -- which is a bit slower. If
+# you now of a 64 bit unsigned integer type on your platform
+# then define that in the BUDDYUINT64 variable. Example:
+# BUDDYUINT64 = -DBUDDYUINT64="long long"
+
+
+# --------------------------------------------------------------
+# Do not touch 
+# --------------------------------------------------------------
+DFLAGS = $(CLOCKFLAG) $(DEBUGFLAGS) $(BUDDYUINT64)
+

buddy/doc/makefile

+clean:

buddy/doc/tech.txt

+****************************************************************************
+  How to create your own internal BDD functions.
+****************************************************************************
+
+PLEASE NOTE
+That interrupting variable reordering has been introduced after this document was written.
+
+
+===[ Functions that do not change or produce new BDDs ]=====================
+
+I'll do this by example. Take "bdd_satcount" that counts the number of
+satisfying assignments that makes a BDD true.
+
+Almost all functions consists of some introduction followed by a
+recursion through the BDD.
+
+* Use the type BDD for all references (numbers) to BDD nodes.
+* External BDD variables used internally in the package are
+  defined in "kernel.h"
+* Macros for reading BDD nodes are:
+   LEVEL(r)
+   LOW(r)
+   HIGH(r)
+   ISCONST(r)  =>  true if r is one of the terminals
+
+
+double bdd_satcount(BDD r)
+{
+   double size=1;
+   int n;
+
+   CHECKa(r, 0.0);  /* CHECK for valid nodes - defined in kernel.h */
+   
+   miscid = CACHEID_SATCOU;           /* Setup global variables. This is
+                                         used extensively instead of passing
+					 arguments to the recursive functions,
+					 for faster recursive calls */
+
+   for (n=0 ; n<LEVEL(r) ; n++)       /* Setup whatever is needed for the */
+      size *= 2;                      /* recursion */
+   
+   return size * bdd_satcount_rec(r); /* Do the recurison */
+}
+
+
+Cache tables are used for storing intermidiate results when doing BDD
+operations. These are defined as static in the top of bddop.c (the
+code is in cache.c) and they should be setup, cleared and delete at
+the top of bddop.c in the functions bdd_operator_init,
+bdd_operator_done, bdd_operator_reset.
+
+
+
+static double bdd_satcount_rec(BDD root)
+{
+   BddCacheData *entry;  /* Entry pointer in the cache */
+   BddNode *node;
+   double size, s;
+   int m;
+   
+   if (ISCONST(root))    /* Check for the constant terminals */
+      return root;
+
+      /* Lookup entry in the cache table used for this function */
+
+   entry = BddCache_lookup(&misccache, SATCOUHASH(root));
+   if (entry->a == root  &&  entry->c == miscid)
+      return entry->r.dres;
+
+      /* Do whatever calculations are needed */
+
+   size = 0;
+   s = 1;
+   
+   for (m=LEVEL(root)+1 ; m<LEVEL(LOW(root)) ; m++)
+      s *= 2;
+   size += s * bdd_satcount_rec(LOW(root));  /* Recurse on low part */
+
+   s = 1;
+   for (m=LEVEL(root)+1 ; m<LEVEL(HIGH(root)) ; m++)
+      s *= 2;
+   size += s * bdd_satcount_rec(HIGH(root)); /* Recurse on high part */
+
+      /* Insert result in cache table */
+
+   entry->a = root;
+   entry->c = miscid;
+   entry->r.dres = size;
+   
+   return size;  /* Return result */
+}
+
+
+
+===[ Functions that produces new BDDs ]=====================================
+
+Functions that produces BDD nodes must take great care to avoid
+loosing intermidiate nodes when automatic garbage collections
+occur. This is doneby stacking each intermidiate result until they are no more used. This stack is check by the garbage collector.
+
+Macros for accessing the stack:
+   INITREF:    Reset the stack
+   PUSHREF(n): Push the node 'n' on the stack
+   READREF(p): Read 'p' positions down the stack
+   POPREF(p):  Pop 'p' nodes off the stack.
+
+Again I'll illustrate this with an example - the NOT operator.
+
+BDD bdd_not(BDD r)
+{
+   int res;
+   CHECKa(r, bddfalse); /* Validate arguments */
+   
+   INITREF;             /* Important! resets the stack */
+
+   res = not_rec(r);    /* Recurse */
+   checkreorder(res);   /* Check to see if a reordering was called for */
+
+   return res;          /* Return result */
+}
+
+
+static BDD not_rec(BDD r)
+{
+   BddCacheData *entry;   /* Cache entry pointer */
+   BDD res;
+
+   if (ISZERO(r))         /* Check constant terminals */
+      return BDDONE;
+   if (ISONE(r))
+      return BDDZERO;
+
+      /* Lookup in cache */
+   entry = BddCache_lookup(&applycache, NOTHASH(r));
+   if (entry->a == r  &&  entry->c == bddop_not)
+      return entry->r.res;
+
+      /* Recurse AND push result on the reference stack */
+   PUSHREF( not_rec(LOW(r)) );
+   PUSHREF( not_rec(HIGH(r)) );
+
+      /* Create a new BDD node */
+   res = bdd_makenode(LEVEL(r), READREF(2), READREF(1));
+
+      /* Pop result off the stack */
+   POPREF(2);
+
+      /* Insert in cache */
+   entry->a = r;
+   entry->c = bddop_not;
+   entry->r.res = res;
+
+      /* Return the result */
+   return res;
+}
+
+
+
+
+===[ Documentation ]========================================================
+
+ALL entries visible to the user should be documentet by an commented
+section like the one shown here, placed right before the code.
+
+Each doc. entry consist of a keyword followed by {* ... text
+... *}. The entries are:
+
+   NAME:    Name of the function.
+   SECTION: Which part to place the documentation in.
+   SHORT:   One line description of the code.
+   PROTO:   The exact prototype.
+   DESCR:   Multiline description of the code.
+   ALSO:    Other relevant stuff.
+   RETURN:  The returned value.
+
+/*
+NAME    {* bdd\_satcount *}
+SECTION {* info *}
+SHORT   {* Calculates the number of satisfying variable assignments *}
+PROTO   {* double bdd_satcount(BDD r) *}
+DESCR   {* Calculates how many possible variable assignments there exists
+           such that {\tt r} is satisfied, taking all defined variables
+	   into account. *}
+ALSO    {* bdd\_satone, bdd\_fullsatone, bdd\_satcountln *}
+RETURN  {* The number of possible assignments. *}
+*/

buddy/examples/adder/adder.cxx

+/*************************************************************************
+  FILE:  adder.cc
+  DESCR: BDD implementation of an N bit adder.
+  AUTH:  Jorn Lind
+  DATE:  feb 1998
+*************************************************************************/
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include "bdd.h"
+
+int N;
+
+bdd *ainp;
+bdd *binp;
+bdd *co;
+bdd *xout;
+
+
+/*************************************************************************
+  Adder
+*************************************************************************/
+
+void build_adder(void)
+{
+   int n;
+   
+   for (n=0 ; n<N ; n++)
+   {
+      if (n > 0)
+      {
+	 xout[n] = ainp[n] ^ binp[n] ^ co[n-1];
+	 co[n] = ainp[n] & binp[n] |
+                 ainp[n] & co[n-1] |
+	         binp[n] & co[n-1];
+      }
+      else
+      {
+	 xout[n] = ainp[n] ^ binp[n];
+	 co[n] = ainp[n] & binp[n];
+      }
+   }
+}
+
+
+int main(int argc, char **argv)
+{
+   int method=BDD_REORDER_NONE;
+   int n;
+   
+   if(argc < 2 || argc > 3)
+   {
+      cout << "usage: adder N R\n";
+      cout << "       N number of bits\n";
+      cout << "       R -> enable reordering if R is win2,win2ite,win3,win3ite,sift,siftite\n";
+      cout << "            in this case 'adder' starts with a worst case ordering\n";
+      exit(1);
+   }
+   
+   N = atoi(argv[1]);
+   if (N <= 0)
+   {
+      cout << "The number of bits must be more than zero\n";
+      exit(2);
+   }
+
+   if (argc == 3)
+   {
+      if (strcmp(argv[2], "win2") == 0)
+	 method = BDD_REORDER_WIN2;
+      else
+      if (strcmp(argv[2], "win2ite") == 0)
+	 method = BDD_REORDER_WIN2ITE;
+      else
+      if (strcmp(argv[2], "win3") == 0)
+	 method = BDD_REORDER_WIN3;
+      else
+      if (strcmp(argv[2], "win3ite") == 0)
+	 method = BDD_REORDER_WIN3ITE;
+      else
+      if (strcmp(argv[2], "sift") == 0)
+	 method = BDD_REORDER_SIFT;
+      else
+      if (strcmp(argv[2], "siftite") == 0)
+	 method = BDD_REORDER_SIFTITE;
+      else
+      if (strcmp(argv[2], "rand") == 0)
+	 method = BDD_REORDER_RANDOM;
+   }
+