ssoelvsten / cal

University of California BDD Package

cal's Issues

Copy documentation to be Documentation Comments in code

The documentation comments in the html files of docs/ should be moved over to the cal.h and the calObj.hh files.

• cal.h
• calObj.jj

Furthermore, the following functions should be marked as non-public parts of the API.

• Cal_BddVarBlockReorderable
• Cal_MemFatal
• Cal_MemAllocation
• Cal_MemGetBlock
• Cal_MemFreeBlock
• Cal_MemResizeBlock
• Cal_MemFreeRec
• Cal_MemNewRecMgr
• Cal_MemFreeRecMgr

`OVERFLOW` is (possibly) a Preprocessor Variable

Compilation fails on certain system configurations at src/calObj.hh:278 due to not expecting a numeric literal on the left.

One could think to make all enum values in src/calObj.hh from ALLCAPS into CamelCase. Yet, this clashes with the Overflow predicate.

Code Duplication: `CeilLog2`

Almost every C file of CAL includes a static function called CeilLog2. Each of these are a duplication of another. This must be possible to move into CalInt.h for everyone to use instead.

Add `Cal_BddPrintDot(manager, f)`

CAL currently supports printing a "human-friendly format"; yet, for many purposes a dot output would be much more lovely. One should be able to implement this based on Cal_BddPrintBdd.

Derive page size within CMake

The original build script was able to derive the page size by running a small program. We should find a way to do the very same, such that the user does not need to change it manually.

Add Association dependent functions to `BDD`

Cal

• Add direct manipulation using the association list. Here, a non-temporary association should be used, deleted, and finally reinstating the prior association (if any).
  • Exists(f, begin, end) and Exists(f, c)
  • ForAll(f, begin, end) and ForAll(f, c)
  • RelProd(f, g, begin, end) and RelProd(f, g, c)

BDD

• Add direct manipulation using the association list. Again, a non-temporary association should be used, deleted, and finally the prior association (if any) should be reinstated.
  • Exists(begin, end) and Exists(c)
  • ForAll(begin, end) and ForAll(c)
  • RelProd(g, begin, end) and RelProd(g, c)

Missing Dereference in C++ Interface

CAL seems to use much more memory than would be expected. For the 14-Queens problem, where the largest BDD only is 4 GiB in size, CAL runs out of memory on my machine after having filled 16 GiB of RAM and 8 GiB of swap.

When running the Tic-Tac-Toe 22 benchmark, we get the following output. Please note the number of nodes that were garbage collected - specifically notice nothing has been garbage collected.

Tic-Tac-Toe with 22 crosses (CAL [BDD] 8096 MiB):

   CAL [BDD] initialisation:
   | time (ms):              1

   Initial decision diagram:
   | size (nodes):           990
   | time (ms):              0

   Applying constraints:
   | final size (nodes):     6560564
   | time (ms):              336215

   counting solutions:
   | number of solutions:    9734400
   | time (ms):              3444

   total time (ms):          339659

**** CAL modifiable parameters ****
Node limit: 0
Garbage collection enabled: yes
...
Repacking after GC Threshold: 0.750000
**** CAL statistics ****
Total BDD Node Usage : 256739576 nodes, 8215666432 Bytes
Peak BDD Node Usage : 202440128 nodes, 6478084096 Bytes
Number of nodes locked: 42457
...
Number of nodes garbage collected: 0
number of garbage collections: 13
...
garbage collection limit: 404880256

Add Installation to CMake

Currently, we only support static compilation of CAL as a submodule. Some prefer to compile it once and install it in a folder, to which they can link it (and possibly also statically compile it).

Tests don't build

• test/calCacheTableTwo.c uses CacheTableTwoRehash but this function is declared to be static in src/calCacheTableTwo.c.
• test/calTest.c should include unistd.h for unlink.

`free(): invalid pointer` with `CAL_REORDER_METHOD_DF`

Since compiling CAL with CMake (see #2) we get free(): invalid pointer errors in the loops for the BddReallocateNodes function on line 886 in calReorderDF.c.

BDD default constructor results in segmentation fault

The default constructor for the BDD class has a nullptr to the BDD manager and node. Yet, it still calls the free function which does not double-check for a nullptr.

`Regular` is wrongly reference counted

The C function Cal_BddGetRegular does not increment the reference count. One could of course argue this is a fault of the C api.

Add `Cal_BddNull(...)` to the C and C++ interface

The documentation mentions a function Cal_BddNull(bddManager), but looking at the source, it does not exist. One can see from the Cal_BddIsBddNull(bddManager, bdd) implementation that this is the value 0.

• C
  • Add Cal_BddNull(...) to the C interface
  • Use Cal_BddNull(...) rather than (Cal_Bdd) 0
• C++
  • Use this null in the C++ interface
  • Add BddNull()

Add `NodeCount` that reports actual Number of Nodes

As highlighted in SSoelvsten/bdd-benchmark#110 , it is of interest to now what is the actual number of nodes a BDD package uses to represent its function. Yet, while CAL uses complement edges, the NodeCount function "normalises" its output by counting subtrees with and without complementation seperately.

Default value for `negout` in `Size(...)` should be non-zero

Based on the C documentation

Add C++ API

With 5a3ae0b we added a C++ wrapper on the entire CAL library. Yet, it only included the operations necessary to get it to run on my BDD-Benchmark repository. We ought to expand on this to all of CAL's operations.

Operations

CAL Class

• Cal_BddStats(...)
• Cal_BddTotalSize(...)
• Cal_BddDynamicReordering(...)
• Cal_BddReorder(...)
• Cal_BddVars(...)
• Cal_BddNodeLimit(...)
• Cal_BddOverflow(...)
• Cal_BddManagerGetHooks(...)
• Cal_BddManagerSetHooks(...)
• Cal_BddManagerInit...)
• Cal_BddManagerQuit(...) [ #3 ]
• Cal_BddManagerSetParameters(...)
• Cal_BddManagerGetNumNodes(...)
• Cal_BddManagerCreateNewVarFirst(...)
• Cal_BddManagerCreateNewVarLast(...)
• Cal_BddNewVarBlock(...)
• Cal_BddVarBlockReorderable(...)
• Cal_BddSetGCMode(...)
• Cal_BddManagerGC(...)
• Cal_BddManagerSetGCLimit(...)

BDD Class

• Cal_BddIsEqual(...)
• Cal_BddIsBddOne(...)
• Cal_BddIsBddZero(...)
• Cal_BddIsBddNull(...)
• Cal_BddIsBddConst(...)
• Cal_BddIdentity(...)
• Cal_BddOne(...)
• Cal_BddZero(...)
• Cal_BddNot(...)
• Cal_BddGetIfIndex(...)
• Cal_BddGetIfId(...)
• Cal_BddIf(...)
• Cal_BddThen(...)
• Cal_BddElse(...)
• Cal_BddGetRegular(...)
• Cal_BddIntersects(...)
• Cal_BddImplies(...)
• Cal_BddType(...)
• Cal_BddIsCube(...)
• Cal_BddCompose(...)
• Cal_BddITE(...)
• Cal_BddManagerCreateNewVarBefore(...)
• Cal_BddManagerCreateNewVarAfter(...)
• Cal_BddManagerGetVarWithIndex(...) [:lady_beetle: Cal_BddManagerGetVarWithId]
• Cal_BddManagerGetVarWithId(...)
• Cal_BddAnd(...)
• Cal_BddNand(...)
• Cal_BddOr(...)
• Cal_BddNor(...)
• Cal_BddXor(...)
• Cal_BddXnor(...)
• Cal_BddPairwiseAnd(...)
• Cal_BddPairwiseOr(...)
• Cal_BddPairwiseXor(...)
• Cal_BddMultiwayAnd(...)
• Cal_BddMultiwayOr(...)
• Cal_BddMultiwayXor(...)
• Cal_BddSatisfy(...)
• Cal_BddSatisfySupport(...)
• Cal_BddSatisfyingFraction(...)
• Cal_BddSize(...)
• Cal_BddSizeMultiple(...)
• Cal_BddSubstitute(...)
• Cal_BddVarSubstitute(...)
• Cal_BddSupport(...)
• Cal_BddDependsOn(...)
• Cal_BddSwapVars(...)
• Cal_BddPrintBdd(...)
• Cal_BddProfile(...)
• Cal_BddProfileMultiple(...)
• Cal_BddPrintProfile(...)
• Cal_BddPrintProfileMultiple(...)
• Cal_BddFunctionPrint(...)
• Cal_BddFunctionProfile(...)
• Cal_BddFunctionProfileMultiple(...)
• Cal_BddPrintFunctionProfile(...)
• Cal_BddPrintFunctionProfileMultiple(...)
• Cal_BddExists(...)
• Cal_BddRelProd(...)
• Cal_BddForAll(...)
• Cal_BddCofactor(...)
• Cal_BddReduce(...)
• Cal_BddBetween(...)
• Cal_BddUndumpBdd(...)
• Cal_BddDumpBdd(...)

The following operations, I believe are internal or should be hidden within the C++ classes. That is, these do not need to be lifted to C++.

• Cal_BddFree(...)
• Cal_BddUnFree(...)
• Cal_MemFatal(...)
• Address_t Cal_MemAllocation(...)
• Pointer_t Cal_MemGetBlock(...)
• Cal_MemFreeBlock(...)
• Pointer_t Cal_MemResizeBlock(...)
• Pointer_t Cal_MemNewRec(...)
• Cal_MemFreeRec(...)
• RecMgr Cal_MemNewRecMgr(...)
• Cal_MemFreeRecMgr(...)

Association

Operations like Cal_BddForAll depend on an Association list, which essentially is a list of variables. These then, depending on the operation, determine how the BDD operations progress.

• Cal_AssociationInit(...)
• Cal_AssociationQuit(...)
• Cal_AssociationSetCurrent(...)
• Cal_TempAssociationAugment(...)
• Cal_TempAssociationInit(...)
• Cal_TempAssociationQuit(...)

Note the final argument pairs is a boolean whether it is a mapping x -> f. These are then used with substitution rather than exists.

Other Data Structures

• Functions
• Some of the operations above take a pointer to array(s) of input or to place the output. Both of these ought to be changed into using an iterator instead

Pipeline

The pipeline should probably get its own interface and class. One may even want to use operator overloading similar to TPIE to make pipelining readable.

• Cal_PipelineInit(...)
• Cal_PipelineSetDepth(...)
• Bdd Cal_PipelineCreateProvisionalBdd(...)
• Bdd Cal_PipelineUpdateProvisionalBdd(...)
• Cal_BddIsProvisional(...)
• Cal_PipelineExecute(...)
• Cal_PipelineQuit(...)

`free(): invalid pointer` for `Cal_BddManagerQuit`

Since compiling CAL with CMake (see #2) we get free(): invalid pointer errors in the loops for the CalPageManagerQuit function on line 158 in calMemoryManagement.c.

Move depth-first threshold into a CMake/Run-time variable

Currently, there is a hardcoded value of 2¹⁹ threshold that switches whether an algorithm should be run with depth-first or with breadth-first operations. Yet, this variable was set based on hardware from the end of the 90s.

Hence, it would be useful if this variable could be changed more easily. This can be done in one of two ways:

1. Turn it into a CMake variable that is then injected with the preprocessor.
2. Turn the threshold into a global variable that you can change at run-time.
3. Turn the threshold into a global variable that is set during initialisation based on the amount of available memory (see i-level cuts for Adiar here)

Remove `dynamicReorderingEnableFlag` from `Cal_BddManager`

The dynamicReorderingEnableFlag member of a Cal_BddManager acts as a second way to disable reordering, rather than just set it to the more intuitive Cal_ReorderNone. No parts of the code seem to truly depend on only that value rather than the reorderTechnique.

This flag also wrongly prints as part of the statistics that dynamic variable reordering is enabled even if it is not.