binary-decision-diagram 4.0.0 → 5.0.0

package/dist/esm/src/ordering/local-search.js

@@ -0,0 +1,308 @@
+import { ensureValidOrdering, naturalOrdering } from './dense-truth-table.js';
+/**
+ * Deterministic greedy construction:
+ * fills the levels from the top, at each level the boolean function
+ * that leads to the best BDD (with the other functions in their index order)
+ * is picked.
+ */
+export function greedyTopDownOrdering(evaluator) {
+    const n = evaluator.variableCount;
+    const prefix = [];
+    let remaining = naturalOrdering(n);
+    while (remaining.length > 1) {
+        let bestVar = -1;
+        let best = null;
+        for (const candidate of remaining) {
+            const ordering = prefix.concat([candidate], remaining.filter(v => v !== candidate));
+            const evaluation = evaluator.evaluate(ordering);
+            if (!best || evaluator.isBetter(evaluation, best)) {
+                best = evaluation;
+                bestVar = candidate;
+            }
+        }
+        prefix.push(bestVar);
+        remaining = remaining.filter(v => v !== bestVar);
+    }
+    return prefix.concat(remaining);
+}
+/**
+ * Deterministic greedy construction from the bottom:
+ * at each step the boolean function that is best as the lowest
+ * remaining level is picked.
+ */
+export function greedyBottomUpOrdering(evaluator) {
+    const n = evaluator.variableCount;
+    let suffix = [];
+    let remaining = naturalOrdering(n);
+    while (remaining.length > 1) {
+        let bestVar = -1;
+        let best = null;
+        for (const candidate of remaining) {
+            const ordering = remaining.filter(v => v !== candidate).concat([candidate], suffix);
+            const evaluation = evaluator.evaluate(ordering);
+            if (!best || evaluator.isBetter(evaluation, best)) {
+                best = evaluation;
+                bestVar = candidate;
+            }
+        }
+        suffix = [bestVar].concat(suffix);
+        remaining = remaining.filter(v => v !== bestVar);
+    }
+    return remaining.concat(suffix);
+}
+/**
+ * Lexicographically ordered permutations of 0..size-1
+ */
+function allPermutations(size) {
+    const ret = [];
+    const recurse = (prefix, rest) => {
+        if (rest.length === 0) {
+            ret.push(prefix);
+            return;
+        }
+        for (let i = 0; i < rest.length; i++) {
+            recurse(prefix.concat([rest[i]]), rest.slice(0, i).concat(rest.slice(i + 1)));
+        }
+    };
+    recurse([], naturalOrdering(size));
+    return ret;
+}
+export const DEFAULT_WINDOW_SIZE = 3;
+export const DEFAULT_MAX_ROUNDS = 50;
+/**
+ * Window permutation tries all w! orderings of every window of w levels,
+ * larger windows take too long.
+ */
+export const MAX_WINDOW_SIZE = 8;
+export function ensureNonNegativeInteger(value, name) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(name + ' must be a non-negative integer');
+    }
+}
+export function ensureWindowSize(windowSize) {
+    ensureNonNegativeInteger(windowSize, 'windowSize');
+    if (windowSize > MAX_WINDOW_SIZE) {
+        throw new Error('windowSize must be at most ' + MAX_WINDOW_SIZE + ', window permutation tries windowSize! orderings per window');
+    }
+}
+/**
+ * Improves an ordering by sifting (moving each variable through all positions
+ * and keeping the best one) and exhaustive window permutation until no
+ * strict improvement is found anymore. "Better" is decided by
+ * OrderingEvaluator.isBetter(): fewer nodes, or with a cost model a lower
+ * expected cost. Everything is deterministic: the same input always gives
+ * the same output.
+ */
+export class LocalOrderingSearch {
+    evaluator;
+    best;
+    cursor;
+    n;
+    windowPermutations;
+    windowSize;
+    maxRounds;
+    onImprovement;
+    log;
+    constructor(evaluator, initialOrdering, options = {}) {
+        this.evaluator = evaluator;
+        this.n = evaluator.variableCount;
+        ensureValidOrdering(initialOrdering, this.n);
+        const windowSize = options.windowSize === undefined ? DEFAULT_WINDOW_SIZE : options.windowSize;
+        ensureWindowSize(windowSize);
+        const maxRounds = options.maxRounds === undefined ? DEFAULT_MAX_ROUNDS : options.maxRounds;
+        ensureNonNegativeInteger(maxRounds, 'maxRounds');
+        this.cursor = evaluator.cursor(initialOrdering);
+        this.best = this.cursor.evaluation;
+        this.windowSize = Math.min(windowSize, this.n);
+        // the identity permutation is the current state, no need to evaluate it again
+        this.windowPermutations = this.windowSize >= 2 ?
+            allPermutations(this.windowSize).filter(permutation => permutation.some((v, i) => v !== i)) :
+            [];
+        this.maxRounds = maxRounds;
+        this.onImprovement = options.onImprovement ? options.onImprovement : () => null;
+        this.log = options.log ? options.log : () => null;
+    }
+    /**
+     * ordering[level] = boolean function tested on that level
+     */
+    get ordering() {
+        return this.cursor.ordering;
+    }
+    result() {
+        return {
+            ordering: this.ordering.slice(),
+            nodeCount: this.best.nodeCount,
+            expectedCost: this.best.expectedCost,
+            nodesPerLevel: this.best.nodesPerLevel.slice(),
+            evaluation: this.best
+        };
+    }
+    /**
+     * Runs sifting rounds and window permutation rounds
+     * until a full cycle gives no improvement.
+     */
+    run() {
+        let round = 0;
+        while (round < this.maxRounds) {
+            round++;
+            const before = this.best;
+            this.siftRound();
+            if (this.windowSize >= 2) {
+                this.windowRound();
+            }
+            this.log('local search round ' + round + ': ' + this.describe(before) + ' -> ' + this.describe(this.best));
+            if (!this.evaluator.isBetter(this.best, before)) {
+                break;
+            }
+        }
+        return this.result();
+    }
+    /**
+     * One sifting round: each variable, largest level first,
+     * is moved to the position where the BDD is best.
+     * @returns true if the ordering improved
+     */
+    siftRound() {
+        const startEvaluation = this.best;
+        const n = this.n;
+        const positionOf = (v) => this.ordering.indexOf(v);
+        const variables = this.ordering.slice().sort((a, b) => {
+            const diff = this.best.nodesPerLevel[positionOf(b)] - this.best.nodesPerLevel[positionOf(a)];
+            return diff !== 0 ? diff : a - b;
+        });
+        for (const variable of variables) {
+            const start = positionOf(variable);
+            let bestEvaluation = this.best;
+            let bestPosition = start;
+            let position = start;
+            const moveTo = (target) => {
+                while (position < target) {
+                    this.swapAdjacent(position);
+                    position++;
+                }
+                while (position > target) {
+                    this.swapAdjacent(position - 1);
+                    position--;
+                }
+            };
+            const sweep = (target) => {
+                while (position !== target) {
+                    const step = position < target ? 1 : -1;
+                    this.swapAdjacent(step === 1 ? position : position - 1);
+                    position += step;
+                    const evaluation = this.cursor.evaluation;
+                    if (this.evaluator.isBetter(evaluation, bestEvaluation)) {
+                        bestEvaluation = evaluation;
+                        bestPosition = position;
+                    }
+                }
+            };
+            // go to the closer end first, then to the other end
+            if (start < n - 1 - start) {
+                sweep(0);
+                sweep(n - 1);
+            }
+            else {
+                sweep(n - 1);
+                sweep(0);
+            }
+            moveTo(bestPosition);
+            if (this.evaluator.isBetter(bestEvaluation, this.best)) {
+                this.best = bestEvaluation;
+                this.log('sifting: ' + this.describe(bestEvaluation));
+                this.onImprovement(this.progress('sifting'));
+            }
+        }
+        return this.evaluator.isBetter(this.best, startEvaluation);
+    }
+    /**
+     * One window permutation round: for each window of adjacent levels
+     * all permutations of its variables are tried.
+     * @returns true if the ordering improved
+     */
+    windowRound() {
+        const startEvaluation = this.best;
+        const w = this.windowSize;
+        if (w < 2) {
+            return false;
+        }
+        for (let windowStart = 0; windowStart + w <= this.n; windowStart++) {
+            const original = this.ordering.slice(windowStart, windowStart + w);
+            let bestEvaluation = this.best;
+            let bestPermutation = null;
+            for (const permutation of this.windowPermutations) {
+                this.setWindow(windowStart, original, permutation);
+                const evaluation = this.cursor.evaluation;
+                if (this.evaluator.isBetter(evaluation, bestEvaluation)) {
+                    bestEvaluation = evaluation;
+                    bestPermutation = permutation;
+                }
+            }
+            if (bestPermutation) {
+                this.setWindow(windowStart, original, bestPermutation);
+                this.best = bestEvaluation;
+                this.log('window permutation: ' + this.describe(bestEvaluation));
+                this.onImprovement(this.progress('window'));
+            }
+            else {
+                this.setWindow(windowStart, original, naturalOrdering(w));
+            }
+        }
+        return this.evaluator.isBetter(this.best, startEvaluation);
+    }
+    progress(phase) {
+        return {
+            ordering: this.ordering.slice(),
+            nodeCount: this.best.nodeCount,
+            expectedCost: this.best.expectedCost,
+            phase
+        };
+    }
+    describe(evaluation) {
+        return evaluation.nodeCount + ' nodes' +
+            (this.evaluator.costModel ? ', expected cost ' + evaluation.expectedCost : '');
+    }
+    /**
+     * swaps the variables of level and level+1
+     */
+    swapAdjacent(level) {
+        this.swapLevels(level, level + 1);
+    }
+    swapLevels(levelA, levelB) {
+        this.cursor.swap(levelA, levelB);
+    }
+    /**
+     * Arranges the window so that level (windowStart + i) holds original[permutation[i]].
+     */
+    setWindow(windowStart, original, permutation) {
+        for (let i = 0; i < permutation.length; i++) {
+            const wanted = original[permutation[i]];
+            const currentLevel = this.ordering.indexOf(wanted);
+            this.swapLevels(windowStart + i, currentLevel);
+        }
+    }
+}
+/**
+ * Deterministic start orderings for the local search.
+ */
+export function seedOrderings(evaluator) {
+    const n = evaluator.variableCount;
+    const natural = naturalOrdering(n);
+    const seeds = [
+        { name: 'natural', ordering: natural },
+        { name: 'reversed', ordering: natural.slice().reverse() },
+        { name: 'greedy-top-down', ordering: greedyTopDownOrdering(evaluator) },
+        { name: 'greedy-bottom-up', ordering: greedyBottomUpOrdering(evaluator) }
+    ];
+    // remove duplicates, keep the first occurrence
+    const seen = new Set();
+    return seeds.filter(seed => {
+        const key = seed.ordering.join(',');
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+//# sourceMappingURL=local-search.js.map

package/dist/esm/src/ordering/local-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-search.js","sourceRoot":"","sources":["../../../../src/ordering/local-search.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/ordering/optimize-ordering.d.ts

@@ -0,0 +1,153 @@
+import type { TruthTable } from '../types.js';
+import { RootNode } from '../root-node.js';
+import { DenseTruthTable } from './dense-truth-table.js';
+import { CostModel } from './ordering-evaluator.js';
+import { OrderingProgressCallback } from './local-search.js';
+export declare const DEFAULT_MAX_EXACT_VARIABLES = 20;
+export declare const DEFAULT_MAX_EXACT_NODE_COUNT = 5000;
+export interface FindOrderingInput {
+    truthTable: TruthTable;
+    /**
+     * Value of the rows that can never occur at runtime.
+     * These rows are resolved exactly like removeIrrelevantLeafNodes() does it:
+     * a branch that only leads to don't-care rows is replaced by its sibling.
+     * Which ordering profits most from that is part of the search, but the
+     * rule itself is a heuristic, not the smallest possible completion.
+     */
+    dontCareValue?: number;
+    /**
+     * Cost of calling each boolean function: functionCosts[i] belongs to the
+     * boolean function with index i (the i-th character of the truth table keys).
+     * When given, the optimizer minimizes the expected cost of one resolve() call,
+     * that is the sum of the costs of the boolean functions that are called on the
+     * way from the root to the leaf, averaged over the rows, instead of the amount
+     * of nodes. Among orderings with the same expected cost, fewer nodes are
+     * preferred (best effort, not part of the optimality proof).
+     */
+    functionCosts?: number[];
+    /**
+     * How often each row occurs at runtime relative to the other rows,
+     * used together with functionCosts. Default: every row that is not a
+     * don't-care row occurs equally often. Don't-care rows never occur.
+     */
+    rowWeight?: (key: string, value: number) => number;
+    /**
+     * Additional start orderings for the local search, for example the
+     * best ordering of a previous run. ordering[level] is the index
+     * of the boolean function tested at that level.
+     */
+    initialOrderings?: number[][];
+    /**
+     * - 'auto' (default): run the exact search when the truth table has at
+     *   most maxExactVariables boolean functions and the BDD found by the local
+     *   search has at most maxExactNodeCount internal nodes (unstructured
+     *   functions have big BDDs, and on them the exact search is slow and
+     *   cannot gain much)
+     * - true: always run the exact search (within the budgets below)
+     * - false: never
+     */
+    exact?: boolean | 'auto';
+    /** Default: 20 */
+    maxExactVariables?: number;
+    /** Default: 5000 */
+    maxExactNodeCount?: number;
+    /**
+     * Budget of the exact search per candidate completion of the truth table.
+     * A candidate whose search exceeds it cannot be proven optimal.
+     * Default: 200000
+     */
+    maxExactExpansions?: number;
+    /**
+     * Memory budget of the exact search: the maximum amount of nodes of its
+     * internal diagram (roughly 100 bytes each).
+     * Default: 4000000
+     */
+    maxExactDiagramNodes?: number;
+    /**
+     * Size of the windows the local search permutes exhaustively,
+     * at most 8 (the work grows with windowSize!).
+     * Default: 3
+     */
+    windowSize?: number;
+    /**
+     * Maximum amount of sifting + window permutation rounds per start ordering.
+     * Default: 50
+     */
+    maxRounds?: number;
+    log?: boolean;
+    /** called whenever a better ordering was found */
+    onImprovement?: OrderingProgressCallback;
+}
+export interface FindOrderingResult {
+    /** ordering[level] = index of the boolean function tested at that level */
+    ordering: number[];
+    /** amount of nodes of the BDD, as RootNode.countNodes() returns it */
+    nodeCount: number;
+    /**
+     * Expected cost of one resolve() call with the returned ordering,
+     * only set when functionCosts were given.
+     */
+    expectedCost?: number;
+    /**
+     * true when the exact search has proven that no other ordering gives a
+     * BDD with fewer nodes (or, with functionCosts, a lower expected cost)
+     * for the truth table in `truthTable`. With don't-care rows that is one
+     * completion of the input: another ordering can occasionally reach a smaller
+     * BDD by resolving the don't-care rows differently.
+     */
+    optimal: boolean;
+    /**
+     * The truth table the BDD represents: the input table with the don't-care
+     * rows resolved, with the same keys as the input (iterated in row order).
+     * createBddWithOrdering(result.truthTable, result.ordering) rebuilds the BDD.
+     * When don't-care rows exist, this completion can differ from the one that
+     * createBddWithOrdering(input, result.ordering, dontCareValue) would pick.
+     */
+    truthTable: TruthTable;
+    stats: OptimizeOrderingStats;
+}
+export interface OptimizeOrderingStats {
+    /** amount of orderings that were evaluated */
+    evaluations: number;
+    /** amount of states the exact search expanded */
+    exactExpansions: number;
+    /** the amount of nodes found by the local search alone */
+    localSearchNodeCount: number;
+    durationMs: number;
+}
+export interface OptimizeOrderingInput extends FindOrderingInput {
+    /**
+     * Hook that runs on the created BDD before it is minimized,
+     * for compatibility with optimizeBruteForce().
+     * The optimizer cannot account for what the hook does, so prefer dontCareValue
+     * over removeIrrelevantLeafNodes() in the hook. When the hook changes the BDD,
+     * `optimal` is false, and `truthTable` and `expectedCost` describe the BDD
+     * before the hook.
+     */
+    afterBddCreation?: (bdd: RootNode) => void;
+}
+export interface OptimizeOrderingResult extends FindOrderingResult {
+    bdd: RootNode;
+}
+/**
+ * Validates functionCosts and rowWeight and turns them into a cost model.
+ */
+export declare function buildCostModel(table: DenseTruthTable, functionCosts?: number[], rowWeight?: (key: string, value: number) => number): CostModel | null;
+/**
+ * Deterministically finds a variable ordering with a small BDD
+ * (or, with functionCosts, with a cheap resolve() call).
+ * See docs/variable-ordering.md for how it works.
+ * Does not create BDD nodes, use optimizeOrdering() for that.
+ */
+export declare function findOrdering(input: FindOrderingInput): FindOrderingResult;
+/**
+ * Deterministic replacement for optimizeBruteForce():
+ * finds a good variable ordering and returns the minimized BDD for it.
+ * All work is synchronous, the promise exists for compatibility with optimizeBruteForce().
+ */
+export declare function optimizeOrdering(input: OptimizeOrderingInput): Promise<OptimizeOrderingResult>;
+/**
+ * Creates the minimized BDD of a truth table for a given ordering
+ * without going through the unreduced decision tree.
+ */
+export declare function createBddWithOrdering(truthTable: TruthTable, ordering: ArrayLike<number>, dontCareValue?: number): RootNode;