binary-decision-diagram 3.2.0 → 5.0.0

package/src/ordering/exact-ordering.ts

@@ -0,0 +1,317 @@
+import type { DenseTruthTable } from './dense-truth-table.js';
+import { naturalOrdering } from './dense-truth-table.js';
+import { OrderingEvaluator } from './ordering-evaluator.js';
+import { SharedDiagram, StateHeap, DiagramBudgetExceededError, DEFAULT_MAX_DIAGRAM_NODES } from './shared-diagram.js';
+
+export interface ExactOrderingOptions {
+    /**
+     * The search stops without a proof when more states were expanded.
+     * Default: 200000
+     */
+    maxExpansions?: number;
+    /**
+     * The search stops without a proof when the stored cofactor sets
+     * contain more entries in total (memory protection).
+     * Default: 2^25
+     */
+    maxCofactorEntries?: number;
+    /**
+     * A known good ordering. Its size is used as upper bound to prune the search,
+     * which makes the search much faster when the ordering is already close to optimal.
+     */
+    upperBoundOrdering?: ArrayLike<number>;
+    /**
+     * Only orderings with fewer internal nodes than this are searched for.
+     */
+    upperBound?: number;
+    log?: (message: string) => void;
+}
+
+export interface ExactOrderingResult {
+    /**
+     * true when it is proven that no ordering has fewer internal nodes
+     * than the returned one (or than the upper bound, when ordering is null)
+     */
+    solved: boolean;
+    /**
+     * The best ordering that was found. Irrelevant boolean functions
+     * are always at the bottom. null when no ordering below the numeric
+     * upper bound exists and the upperBoundOrdering (if given) is not
+     * below it either.
+     */
+    ordering: number[] | null;
+    /** amount of internal (non-leaf) nodes of `ordering`, -1 when ordering is null */
+    internalNodeCount: number;
+    /** amount of expanded states */
+    expansions: number;
+    /** amount of generated states */
+    generated: number;
+}
+
+/**
+ * The number of nodes on a level of a reduced BDD only depends on the SET of
+ * variables above that level, not on their order (Friedman & Supowit, 1990):
+ * it is the amount of distinct cofactors with respect to that set that still
+ * depend on the level's variable.
+ *
+ * Therefore the optimal ordering is a shortest path through the lattice of
+ * variable subsets, from the empty set to the full set, where the edge
+ * S -> S + {x} costs the amount of nodes that test x when exactly the
+ * variables of S are above it.
+ *
+ * This class finds that shortest path with an A* search. Each subset S is
+ * represented by the set of its distinct non-constant cofactors, which are
+ * nodes of one shared hash-consed diagram in the natural variable order
+ * (so equal functions always have equal ids). The admissible estimate for the
+ * remaining cost of a subset is the amount of its distinct non-constant
+ * cofactors: each of them needs its own node below.
+ *
+ * With a good upper bound (from the local search) the search typically only
+ * has to look at a tiny fraction of the 2^n subsets.
+ */
+export class ExactOrderingSearch {
+    private readonly diagram: SharedDiagram;
+    private readonly n: number;
+    private readonly terminalCount: number;
+
+    constructor(
+        private readonly table: DenseTruthTable,
+        options: { maxDiagramNodes?: number } = {}
+    ) {
+        if (table.dontCareTerminal >= 0) {
+            throw new Error('the exact search needs a truth table without don\'t-care rows, resolve them with OrderingEvaluator.complete() first');
+        }
+        this.diagram = new SharedDiagram(
+            table,
+            options.maxDiagramNodes === undefined ? DEFAULT_MAX_DIAGRAM_NODES : options.maxDiagramNodes
+        );
+        this.n = table.variableCount;
+        this.terminalCount = table.terminalValues.length;
+    }
+
+    /**
+     * Moves the boolean functions the truth table does not depend on
+     * to the bottom. This never changes the amount of internal nodes
+     * but ensures the root node tests a relevant boolean function.
+     */
+    public normalizeOrdering(ordering: ArrayLike<number>): number[] {
+        return this.diagram.normalizeOrdering(ordering);
+    }
+
+    public run(options: ExactOrderingOptions = {}): ExactOrderingResult {
+        const log = options.log ? options.log : () => null;
+        const maxExpansions = options.maxExpansions === undefined ? 200000 : options.maxExpansions;
+        const maxCofactorEntries = options.maxCofactorEntries === undefined ? Math.pow(2, 25) : options.maxCofactorEntries;
+        const diagram = this.diagram;
+        const relevant = diagram.relevant;
+        const m = relevant.length;
+        const irrelevant = diagram.irrelevantVariables();
+
+        // upper bound
+        let upperBound = options.upperBound === undefined ? Infinity : options.upperBound;
+        let incumbent: number[] | null = null;
+        if (options.upperBoundOrdering) {
+            incumbent = this.normalizeOrdering(options.upperBoundOrdering);
+            const incumbentCount = new OrderingEvaluator(this.table).evaluate(incumbent).internalNodeCount;
+            if (incumbentCount >= upperBound) {
+                // the numeric bound is at least as good, the incumbent cannot be the answer
+                incumbent = null;
+            } else {
+                upperBound = incumbentCount;
+            }
+        }
+        const giveUp = (reason: string, expansionCount: number, generatedCount: number): ExactOrderingResult => {
+            log('exact search: ' + reason);
+            return {
+                solved: false,
+                ordering: incumbent,
+                internalNodeCount: incumbent ? upperBound : -1,
+                expansions: expansionCount,
+                generated: generatedCount
+            };
+        };
+        if (diagram.overBudget) {
+            return giveUp('diagram budget exceeded', 0, 0);
+        }
+
+        if (m === 0) {
+            // constant function: every ordering has 0 internal nodes
+            const constantOrdering = upperBound > 0 ? naturalOrdering(this.n) : incumbent;
+            return {
+                solved: true,
+                ordering: constantOrdering,
+                internalNodeCount: constantOrdering ? 0 : -1,
+                expansions: 0,
+                generated: 0
+            };
+        }
+
+        const full = (1 << m) - 1;
+        const cofactors: Map<number, Int32Array> = new Map();
+        const bestCost: Map<number, number> = new Map();
+        const parentVariable: Map<number, number> = new Map();
+        const closed: Set<number> = new Set();
+        const heap = new StateHeap();
+
+        const startSet = new Int32Array(1);
+        startSet[0] = diagram.rootId;
+        cofactors.set(0, startSet);
+        bestCost.set(0, 0);
+        heap.push(this.estimate(0, startSet), 0, 0);
+
+        let expansions = 0;
+        let generated = 1;
+        let storedEntries = 1;
+        let solvedSet = -1;
+        let solvedCost = -1;
+        try {
+        while (heap.size > 0) {
+            const state = heap.pop();
+            const currentCost = state.cost;
+            const subset = state.subset;
+            if (currentCost !== bestCost.get(subset) || closed.has(subset)) {
+                // stale heap entry
+                continue;
+            }
+            if (state.estimate >= upperBound) {
+                // nothing left that can beat the upper bound
+                break;
+            }
+            if (subset === full) {
+                solvedSet = subset;
+                solvedCost = currentCost;
+                break;
+            }
+            closed.add(subset);
+            expansions++;
+            if (expansions > maxExpansions) {
+                return giveUp('expansion budget exceeded', expansions, generated);
+            }
+            if (storedEntries > maxCofactorEntries) {
+                return giveUp('memory budget exceeded', expansions, generated);
+            }
+            if (expansions % 10000 === 0) {
+                log('exact search: ' + expansions + ' states expanded, ' + generated + ' generated, ' + heap.size + ' open');
+            }
+
+            const set = cofactors.get(subset) as Int32Array;
+            for (let c = 0; c < m; c++) {
+                const bit = 1 << c;
+                if ((subset & bit) !== 0) {
+                    continue;
+                }
+                const variable = relevant[c];
+                let edgeCost = 0;
+                for (let i = 0; i < set.length; i++) {
+                    if ((diagram.supportOf(set[i]) & bit) !== 0) {
+                        edgeCost++;
+                    }
+                }
+                const nextCost = currentCost + edgeCost;
+                const nextSubset = subset | bit;
+                const knownCost = bestCost.get(nextSubset);
+                if (knownCost !== undefined && knownCost <= nextCost) {
+                    continue;
+                }
+                let nextSet = cofactors.get(nextSubset);
+                if (nextSet === undefined) {
+                    nextSet = this.cofactorsAfter(set, variable);
+                    cofactors.set(nextSubset, nextSet);
+                    generated++;
+                    storedEntries += nextSet.length;
+                }
+                const estimate = nextCost + this.estimate(nextSubset, nextSet);
+                if (estimate >= upperBound) {
+                    continue;
+                }
+                bestCost.set(nextSubset, nextCost);
+                parentVariable.set(nextSubset, variable);
+                closed.delete(nextSubset);
+                heap.push(estimate, nextCost, nextSubset);
+            }
+        }
+        } catch (err) {
+            if (err instanceof DiagramBudgetExceededError) {
+                return giveUp('diagram budget exceeded', expansions, generated);
+            }
+            throw err;
+        }
+
+        if (solvedSet === -1) {
+            // no ordering below the upper bound exists: the incumbent (if any) is optimal
+            return {
+                solved: true,
+                ordering: incumbent,
+                internalNodeCount: incumbent ? upperBound : -1,
+                expansions,
+                generated
+            };
+        }
+
+        // reconstruct the path
+        const reversed: number[] = [];
+        let remainingSubset = solvedSet;
+        while (remainingSubset !== 0) {
+            const variable = parentVariable.get(remainingSubset) as number;
+            reversed.push(variable);
+            remainingSubset = remainingSubset & ~(1 << diagram.compactOf[variable]);
+        }
+        const ordering = reversed.reverse().concat(irrelevant);
+        return {
+            solved: true,
+            ordering,
+            internalNodeCount: solvedCost,
+            expansions,
+            generated
+        };
+    }
+
+    /**
+     * lower bound for the amount of nodes below the given subset
+     */
+    private estimate(subset: number, set: Int32Array): number {
+        let union = 0;
+        for (let i = 0; i < set.length; i++) {
+            union |= this.diagram.supportOf(set[i]);
+        }
+        const remaining = union & ~subset;
+        let remainingCount = 0;
+        for (let x = remaining; x !== 0; x &= x - 1) {
+            remainingCount++;
+        }
+        return Math.max(set.length, remainingCount);
+    }
+
+    /**
+     * the distinct non-constant cofactors after additionally fixing `variable`
+     */
+    private cofactorsAfter(set: Int32Array, variable: number): Int32Array {
+        const diagram = this.diagram;
+        const bit = 1 << diagram.compactOf[variable];
+        const candidates = new Int32Array(set.length * 2);
+        let count = 0;
+        for (let i = 0; i < set.length; i++) {
+            const g = set[i];
+            if ((diagram.supportOf(g) & bit) === 0) {
+                candidates[count++] = g;
+                continue;
+            }
+            const lo = diagram.restrict(g, variable, 0);
+            if (lo >= this.terminalCount) {
+                candidates[count++] = lo;
+            }
+            const hi = diagram.restrict(g, variable, 1);
+            if (hi >= this.terminalCount) {
+                candidates[count++] = hi;
+            }
+        }
+        const sorted = candidates.subarray(0, count).sort();
+        let unique = 0;
+        for (let i = 0; i < sorted.length; i++) {
+            if (i === 0 || sorted[i] !== sorted[i - 1]) {
+                sorted[unique++] = sorted[i];
+            }
+        }
+        return sorted.slice(0, unique);
+    }
+}

package/src/ordering/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Public API of the variable ordering optimizer, see docs/variable-ordering.md.
+ *
+ * - optimize-ordering.ts: optimizeOrdering(), findOrdering(), createBddWithOrdering()
+ * - ordering-evaluator.ts: counts the nodes (and the expected cost) of any ordering in O(2^n)
+ * - local-search.ts: deterministic seeds, sifting and window permutation
+ * - exact-ordering.ts, exact-cost-ordering.ts: A* searches that prove optimality
+ * - shared-diagram.ts: the shared function diagram the exact searches work on
+ * - dense-truth-table.ts, build-bdd.ts, int-pair-map.ts: data structures and helpers
+ */
+export {
+    optimizeOrdering,
+    findOrdering,
+    createBddWithOrdering,
+    buildCostModel,
+    DEFAULT_MAX_EXACT_VARIABLES,
+    DEFAULT_MAX_EXACT_NODE_COUNT
+} from './optimize-ordering.js';
+export type {
+    FindOrderingInput,
+    FindOrderingResult,
+    OptimizeOrderingInput,
+    OptimizeOrderingResult,
+    OptimizeOrderingStats
+} from './optimize-ordering.js';
+export {
+    OrderingEvaluator,
+    OrderingCursor
+} from './ordering-evaluator.js';
+export type {
+    CostModel,
+    OrderingEvaluation,
+    ReducedDiagram
+} from './ordering-evaluator.js';
+export {
+    LocalOrderingSearch,
+    DEFAULT_WINDOW_SIZE,
+    DEFAULT_MAX_ROUNDS,
+    MAX_WINDOW_SIZE
+} from './local-search.js';
+export type {
+    LocalSearchOptions,
+    OrderingSearchResult,
+    OrderingProgress,
+    OrderingProgressCallback
+} from './local-search.js';
+export { ExactOrderingSearch } from './exact-ordering.js';
+export type { ExactOrderingOptions, ExactOrderingResult } from './exact-ordering.js';
+export { ExactCostOrderingSearch } from './exact-cost-ordering.js';
+export type { ExactCostOrderingOptions, ExactCostOrderingResult } from './exact-cost-ordering.js';
+export {
+    parseTruthTable,
+    denseTruthTableToMap,
+    naturalOrdering,
+    MAX_VARIABLE_COUNT
+} from './dense-truth-table.js';
+export type { DenseTruthTable } from './dense-truth-table.js';

package/src/ordering/int-pair-map.ts

@@ -0,0 +1,85 @@
+/**
+ * Open addressing hash map from a pair of non-negative 32 bit integers
+ * to a non-negative 32 bit integer. Used in the hot paths of the exact search
+ * where a Map with string keys would be far too slow.
+ */
+export class IntPairMap {
+    public size: number = 0;
+    private keysA: Int32Array;
+    private keysB: Int32Array;
+    private values: Int32Array;
+    private mask: number;
+
+    constructor(initialCapacity: number = 1024) {
+        let capacity = 16;
+        while (capacity < initialCapacity) {
+            capacity *= 2;
+        }
+        this.keysA = new Int32Array(capacity).fill(-1);
+        this.keysB = new Int32Array(capacity);
+        this.values = new Int32Array(capacity);
+        this.mask = capacity - 1;
+    }
+
+    /**
+     * @returns the stored value or -1
+     */
+    public get(a: number, b: number): number {
+        let h = this.hash(a, b);
+        while (true) {
+            const storedA = this.keysA[h];
+            if (storedA === -1) {
+                return -1;
+            }
+            if (storedA === a && this.keysB[h] === b) {
+                return this.values[h];
+            }
+            h = (h + 1) & this.mask;
+        }
+    }
+
+    public set(a: number, b: number, value: number) {
+        if ((this.size + 1) * 2 > this.keysA.length) {
+            this.grow();
+        }
+        let h = this.hash(a, b);
+        while (true) {
+            const storedA = this.keysA[h];
+            if (storedA === -1) {
+                this.keysA[h] = a;
+                this.keysB[h] = b;
+                this.values[h] = value;
+                this.size++;
+                return;
+            }
+            if (storedA === a && this.keysB[h] === b) {
+                this.values[h] = value;
+                return;
+            }
+            h = (h + 1) & this.mask;
+        }
+    }
+
+    private hash(a: number, b: number): number {
+        let h = (Math.imul(a, 0x9E3779B1) ^ Math.imul(b + 0x7F4A7C15, 0x85EBCA77)) >>> 0;
+        h ^= h >>> 15;
+        return h & this.mask;
+    }
+
+    private grow() {
+        const oldA = this.keysA;
+        const oldB = this.keysB;
+        const oldValues = this.values;
+        const capacity = oldA.length * 2;
+        this.keysA = new Int32Array(capacity).fill(-1);
+        this.keysB = new Int32Array(capacity);
+        this.values = new Int32Array(capacity);
+        this.mask = capacity - 1;
+        this.size = 0;
+        for (let i = 0; i < oldA.length; i++) {
+            if (oldA[i] !== -1) {
+                this.set(oldA[i], oldB[i], oldValues[i]);
+            }
+        }
+    }
+}