@cubingcenter/scrambler 0.5.3 → 0.6.0

package/dist/puzzles/cube4/reduction/edge3.js

@@ -0,0 +1,511 @@
+/**
+ * Edge3 (the pairing pruning table for the phase-3 search).
+ *
+ * The BFS from the solved pairing state over the 17 BFS moves, canonicalized
+ * by the 8 rotation symmetries of the reference's Edge3 phase (`$rot_1` /
+ * `$rotate_0` decomposition with the `$circlex` / `$swapx` coordinate
+ * effects). The pairing state is the relative 12-permutation between the
+ * two halves of the edge slots (see `pairing-coordinate.ts`), stored in the
+ * reference's `(edge, edgeo)` form with shared labels and `$std`-normalized
+ * (second halves hold pairs 0..11 in order).
+ *
+ * Canonicalization and indexing follow the reference exactly:
+ *  - the state space is the 12!/2 even edge permutations (parity is
+ *    invariant under the phase-3 moves), grouped into 1538 first-4
+ *    "sym" classes under the 8 rotations (the reference's
+ *    `initEdge3Sym2Raw`);
+ *  - the canonical sym-index of a state is `symcord1 * 20160 + cord2`,
+ *    computed by `getMvSym` (the reference's move-conjugated
+ *    canonicalization with the `mvrot`/`mvroto` tables);
+ *  - the table stores the exact BFS distance per sym-index (4-bit packed
+ *    nibbles): 31,006,080 * 4 bits = 15.5 MB, no class-key file needed.
+ */
+import { normalizePairingState } from "./pairing-coordinate.js";
+// ---------------------------------------------------------------------------
+// The reference's constants
+// ---------------------------------------------------------------------------
+/** The sym-index space: 1538 first-4 classes × 20160 remaining. */
+export const EDGE3_TOTAL = 31_006_080;
+export const EDGE3_CLASSES = 1538;
+export const EDGE3_CORD2 = 20_160;
+/** The first-4 Lehmer range (12 * 11 * 10 * 9). */
+const EDGE3_FIRST4 = 11_880;
+/** The maximum BFS depth (the reference's prunValues length - 1). */
+export const EDGE3_MAX_DEPTH = 13;
+/** The reference's `factX` (factorials / 2, with the small ones = 1). */
+const FACT_X = [
+    1, 1, 1, 3, 12, 60, 360, 2520, 20160, 181440, 1814400, 19958400, 239500800
+];
+/** The reference's `syminv_0`: inverse rotation index mapping. */
+const SYMINV_0 = [0, 1, 6, 3, 4, 5, 2, 7];
+/** The reference's `move3std`: $move_4 case → std3 move id (the % 3 class). */
+export const MOVE3_STD = [
+    0, 1, 2, 4, 6, 7, 8, 9, 10, 11, 13, 15, 16, 17, 19, 22, 25, 28, 31, 34, 36
+];
+/** The reference's `bfsMoves` (the $move_4 case indices). */
+const EDGE3_MOVE_CASES = [1, 0, 2, 3, 5, 4, 6, 8, 7, 9, 10, 12, 11, 13, 14, 15, 16];
+const BIT_COUNT = (() => {
+    const table = new Uint8Array(4096);
+    for (let i = 0; i < 4096; i++) {
+        table[i] = table[i >> 1] + (i & 1);
+    }
+    return table;
+})();
+export function bitCount(v) {
+    return BIT_COUNT[v & 4095] + BIT_COUNT[(v >> 12) & 4095] + BIT_COUNT[v >> 24];
+}
+// ---------------------------------------------------------------------------
+// The (edge, edgeo) coordinate with the shared labels
+// ---------------------------------------------------------------------------
+/**
+ * The reference's `$swap_0`: the two transpositions (a↔c, b↔d) on one array.
+ */
+function swap0(arr, a, b, c, d) {
+    let temp = arr[a];
+    arr[a] = arr[c];
+    arr[c] = temp;
+    temp = arr[b];
+    arr[b] = arr[d];
+    arr[d] = temp;
+}
+/** The reference's `$circlex`: a 4-cycle across the two halves. */
+function circlex(edge, edgeo, a, b, c, d) {
+    const temp = edgeo[d];
+    edgeo[d] = edge[c];
+    edge[c] = edgeo[b];
+    edgeo[b] = edge[a];
+    edge[a] = temp;
+}
+/** The reference's `$swapx`: swap the halves across slots x and y. */
+function swapx(edge, edgeo, x, y) {
+    const temp = edge[x];
+    edge[x] = edgeo[y];
+    edgeo[y] = temp;
+}
+/**
+ * The reference's `$move_4` (cases 0-19) as coordinate effects: the same
+ * slot permutations applied to `edge` and `edgeo`. The `circle` direction
+ * (the cubing.js `mathlib.circle`: the value at a moves to b) is verified
+ * against the physical move tables in `verifyEdge3`.
+ */
+function applyMoveCase(edge, edgeo, m) {
+    const circle = (arr, a, b, c, d) => {
+        const temp = arr[a];
+        arr[a] = arr[d];
+        arr[d] = arr[c];
+        arr[c] = arr[b];
+        arr[b] = temp;
+    };
+    const circle2 = (arr, a, b) => {
+        const temp = arr[a];
+        arr[a] = arr[b];
+        arr[b] = temp;
+    };
+    switch (m) {
+        case 0:
+            circle(edge, 0, 4, 1, 5);
+            circle(edgeo, 0, 4, 1, 5);
+            break;
+        case 1:
+            swap0(edge, 0, 4, 1, 5);
+            swap0(edgeo, 0, 4, 1, 5);
+            break;
+        case 2:
+            circle(edge, 0, 5, 1, 4);
+            circle(edgeo, 0, 5, 1, 4);
+            break;
+        case 3:
+            swap0(edge, 5, 10, 6, 11);
+            swap0(edgeo, 5, 10, 6, 11);
+            break;
+        case 4:
+            circle(edge, 0, 11, 3, 8);
+            circle(edgeo, 0, 11, 3, 8);
+            break;
+        case 5:
+            swap0(edge, 0, 11, 3, 8);
+            swap0(edgeo, 0, 11, 3, 8);
+            break;
+        case 6:
+            circle(edge, 0, 8, 3, 11);
+            circle(edgeo, 0, 8, 3, 11);
+            break;
+        case 7:
+            circle(edge, 2, 7, 3, 6);
+            circle(edgeo, 2, 7, 3, 6);
+            break;
+        case 8:
+            swap0(edge, 2, 7, 3, 6);
+            swap0(edgeo, 2, 7, 3, 6);
+            break;
+        case 9:
+            circle(edge, 2, 6, 3, 7);
+            circle(edgeo, 2, 6, 3, 7);
+            break;
+        case 10:
+            swap0(edge, 4, 8, 7, 9);
+            swap0(edgeo, 4, 8, 7, 9);
+            break;
+        case 11:
+            circle(edge, 1, 9, 2, 10);
+            circle(edgeo, 1, 9, 2, 10);
+            break;
+        case 12:
+            swap0(edge, 1, 9, 2, 10);
+            swap0(edgeo, 1, 9, 2, 10);
+            break;
+        case 13:
+            circle(edge, 1, 10, 2, 9);
+            circle(edgeo, 1, 10, 2, 9);
+            break;
+        case 14:
+            swap0(edge, 0, 4, 1, 5);
+            swap0(edgeo, 0, 4, 1, 5);
+            circle2(edge, 9, 11);
+            circle2(edgeo, 8, 10);
+            break;
+        case 15:
+            swap0(edge, 5, 10, 6, 11);
+            swap0(edgeo, 5, 10, 6, 11);
+            circle2(edge, 1, 3);
+            circle2(edgeo, 0, 2);
+            break;
+        case 16:
+            swap0(edge, 0, 11, 3, 8);
+            swap0(edgeo, 0, 11, 3, 8);
+            circle2(edge, 5, 7);
+            circle2(edgeo, 4, 6);
+            break;
+        case 17:
+            swap0(edge, 2, 7, 3, 6);
+            swap0(edgeo, 2, 7, 3, 6);
+            circle2(edge, 8, 10);
+            circle2(edgeo, 9, 11);
+            break;
+        case 18:
+            swap0(edge, 4, 8, 7, 9);
+            swap0(edgeo, 4, 8, 7, 9);
+            circle2(edge, 0, 2);
+            circle2(edgeo, 1, 3);
+            break;
+        case 19:
+            swap0(edge, 1, 9, 2, 10);
+            swap0(edgeo, 1, 9, 2, 10);
+            circle2(edge, 4, 6);
+            circle2(edgeo, 5, 7);
+            break;
+    }
+}
+/** The reference's `$rot_1` (r = 0, 1, 2) on the (edge, edgeo) pair. */
+function rot1(edge, edgeo, r) {
+    switch (r) {
+        case 0:
+            applyMoveCase(edge, edgeo, 14);
+            applyMoveCase(edge, edgeo, 17);
+            break;
+        case 1:
+            circlex(edge, edgeo, 11, 5, 10, 6);
+            circlex(edge, edgeo, 5, 10, 6, 11);
+            circlex(edge, edgeo, 1, 2, 3, 0);
+            circlex(edge, edgeo, 4, 9, 7, 8);
+            circlex(edge, edgeo, 8, 4, 9, 7);
+            circlex(edge, edgeo, 0, 1, 2, 3);
+            break;
+        case 2:
+            swapx(edge, edgeo, 4, 5);
+            swapx(edge, edgeo, 5, 4);
+            swapx(edge, edgeo, 11, 8);
+            swapx(edge, edgeo, 8, 11);
+            swapx(edge, edgeo, 7, 6);
+            swapx(edge, edgeo, 6, 7);
+            swapx(edge, edgeo, 9, 10);
+            swapx(edge, edgeo, 10, 9);
+            swapx(edge, edgeo, 1, 1);
+            swapx(edge, edgeo, 0, 0);
+            swapx(edge, edgeo, 3, 3);
+            swapx(edge, edgeo, 2, 2);
+            break;
+    }
+}
+/** The reference's `$rotate_0`: rotation r (0..7) via the rot1 decomposition. */
+function rotateByIndex(edge, edgeo, r) {
+    while (r >= 2) {
+        r -= 2;
+        rot1(edge, edgeo, 1);
+        rot1(edge, edgeo, 2);
+    }
+    if (r !== 0)
+        rot1(edge, edgeo, 0);
+}
+// ---------------------------------------------------------------------------
+// Lehmer helpers (the reference's get12Perm / $set_4)
+// ---------------------------------------------------------------------------
+/**
+ * The mixed-radix Lehmer encode of the first `end` values (the reference's
+ * `get12Perm`): idx = Σ digit_i * (12-i)!-radix, with the digits reduced by
+ * the values already seen.
+ */
+function get12Perm(arr, end, returnMask = false) {
+    let idx = 0;
+    let mask = 0;
+    for (let i = 0; i < end; i++) {
+        const val = arr[i];
+        idx = idx * (12 - i) + val - bitCount(mask & ((1 << val) - 1));
+        mask |= 1 << val;
+    }
+    return returnMask ? mask : idx;
+}
+/**
+ * Decode a 12-permutation from the mixed-radix index (the reference's
+ * `$set_4`): the 11 digits with the parity-corrected last two positions.
+ */
+function set4(out, idx) {
+    let parity = 0;
+    const unused = [];
+    for (let i = 0; i < 12; i++)
+        unused.push(i);
+    for (let i = 0; i < 11; i++) {
+        const p = FACT_X[11 - i];
+        const v = Math.floor(idx / p);
+        idx = idx % p;
+        parity ^= v;
+        out[i] = unused[v];
+        unused.splice(v, 1);
+    }
+    const last = unused[0];
+    if ((parity & 1) === 0) {
+        out[11] = last;
+    }
+    else {
+        out[11] = out[10];
+        out[10] = last;
+    }
+}
+let symTables = null;
+export function getSymTables() {
+    if (!symTables) {
+        symTables = buildSymTables();
+    }
+    return symTables;
+}
+export function buildSymTables() {
+    const mvrot = new Uint8Array(21 * 8 * 12);
+    const mvroto = new Uint8Array(21 * 8 * 12);
+    const edge = new Uint8Array(12);
+    const edgeo = new Uint8Array(12);
+    // initEdge3MvRot: the move-conjugated rotation effects on the solved state.
+    for (let m = 0; m < 21; m++) {
+        for (let r = 0; r < 8; r++) {
+            set4(edge, 0);
+            for (let i = 0; i < 12; i++)
+                edgeo[i] = i;
+            if (m < 20)
+                applyMoveCase(edge, edgeo, m);
+            rotateByIndex(edge, edgeo, r);
+            const base = (m << 3 | r) * 12;
+            for (let i = 0; i < 12; i++)
+                mvrot[base + i] = edge[i];
+            // the reference's $std: temp[edgeo[i]] = i; mvroto = the temp (the
+            // inverse of the pre-std edgeo), NOT the std'ed edge.
+            const temp = new Uint8Array(12);
+            for (let i = 0; i < 12; i++)
+                temp[edgeo[i]] = i;
+            for (let i = 0; i < 12; i++)
+                mvroto[base + i] = temp[i];
+        }
+    }
+    // initEdge3Sym2Raw: the 1538 first-4 classes under the 8 rotations.
+    const occ = new Uint8Array(1485);
+    const sym2Raw = new Uint32Array(EDGE3_CLASSES);
+    const sym2Mask = new Uint32Array(EDGE3_CLASSES);
+    const raw2Sym = new Uint32Array(EDGE3_FIRST4);
+    const symState = new Uint32Array(EDGE3_CLASSES);
+    let count = 0;
+    for (let i = 0; i < EDGE3_FIRST4; i++) {
+        if ((occ[i >> 3] & (1 << (i & 7))) !== 0)
+            continue;
+        set4(edge, i * FACT_X[8]);
+        for (let k = 0; k < 12; k++)
+            edgeo[k] = k;
+        sym2Raw[count] = i;
+        sym2Mask[count] = get12Perm(normalizePairingState(edge, edgeo).edge, 4, true);
+        for (let j = 0; j < 8; j++) {
+            const idx = get12Perm(normalizePairingState(edge, edgeo).edge, 4);
+            if (idx === i)
+                symState[count] = (symState[count] | (1 << j)) >>> 0;
+            occ[idx >> 3] = (occ[idx >> 3] | (1 << (idx & 7)));
+            raw2Sym[idx] = (count << 3 | SYMINV_0[j]) >>> 0;
+            rot1(edge, edgeo, 0);
+            if ((j & 1) === 1) {
+                rot1(edge, edgeo, 1);
+                rot1(edge, edgeo, 2);
+            }
+        }
+        count++;
+    }
+    if (count !== EDGE3_CLASSES) {
+        throw new Error(`Edge3: expected ${EDGE3_CLASSES} classes, found ${count}`);
+    }
+    // the reference's initEdge3Sym2Raw second half: the sym-advance table.
+    const symMove = new Uint16Array(20 * EDGE3_CLASSES);
+    for (let i = 0; i < EDGE3_CLASSES; i++) {
+        set4(edge, sym2Raw[i] * FACT_X[8]);
+        for (let k = 0; k < 12; k++)
+            edgeo[k] = k;
+        for (let m = 0; m < 20; m++) {
+            if (MOVE3_STD[m] % 3 !== 1)
+                continue;
+            const idx = getMvSymFrom(edge, edgeo, m, sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto);
+            symMove[m * EDGE3_CLASSES + i] = (Math.floor((idx >> 3) / EDGE3_CORD2) << 3 | (idx & 7));
+        }
+    }
+    const tables = { mvrot, mvroto, sym2Raw, sym2Mask, raw2Sym, symState, symMove };
+    symTables = tables;
+    return tables;
+}
+/**
+ * The reference's `getMvSym`: the canonical sym-index of the state (edge,
+ * edgeo) under the move-conjugated rotation, as `(sym-index << 3 | r)`.
+ */
+export function getMvSymFrom(edge, _edgeo, mv, sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto, assumeIdx) {
+    let mrIdx = mv << 3;
+    let idx;
+    if (assumeIdx !== undefined && MOVE3_STD[mv] % 3 === 1) {
+        mrIdx |= assumeIdx & 7;
+        idx = assumeIdx >> 3;
+    }
+    else {
+        const movoBase = mrIdx * 12;
+        let baseIdx = 0;
+        let mask = 0;
+        for (let i = 0; i < 4; i++) {
+            const val = mvroto[movoBase + edge[mvrot[movoBase + i]]];
+            baseIdx = baseIdx * (12 - i) + val - bitCount(mask & ((1 << val) - 1));
+            mask |= 1 << val;
+        }
+        baseIdx = raw2Sym[baseIdx];
+        mrIdx |= baseIdx & 7;
+        baseIdx >>= 3;
+        idx = baseIdx;
+    }
+    const mrIdxBase = mrIdx * 12;
+    let mask = sym2Mask[idx];
+    let out = idx;
+    for (let i = 4; i < 10; i++) {
+        const val = mvroto[mrIdxBase + edge[mvrot[mrIdxBase + i]]];
+        out = out * (12 - i) + val - bitCount(mask & ((1 << val) - 1));
+        mask |= 1 << val;
+    }
+    return (out << 3 | (mrIdx & 7)) >>> 0;
+}
+/**
+ * Generate the exact BFS distances over the 31,006,080 sym-index space.
+ * `maxDepthCap` stops the BFS early (validation only).
+ */
+export function generateEdge3Tables(maxDepthCap = -1) {
+    const t = buildSymTables();
+    const { sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto, symMove, symState } = t;
+    const distances = new Uint8Array(Math.ceil(EDGE3_TOTAL / 2)).fill(0xff);
+    const setDistance = (idx, depth) => {
+        const byte = idx >> 1;
+        const shift = (idx & 1) * 4;
+        distances[byte] = (distances[byte] & ~(0x0f << shift)) | ((depth & 0x0f) << shift);
+    };
+    const getDistance = (idx) => (distances[idx >> 1] >> ((idx & 1) * 4)) & 0x0f;
+    const edge = new Uint8Array(12);
+    const edgeo = new Uint8Array(12);
+    const fEdge = new Uint8Array(12);
+    const fEdgeo = new Uint8Array(12);
+    const gEdge = new Uint8Array(12);
+    const gEdgeo = new Uint8Array(12);
+    setDistance(0, 0);
+    let frontier = [0];
+    let depth = 0;
+    while (frontier.length > 0) {
+        if (maxDepthCap >= 0 && depth >= maxDepthCap)
+            break;
+        const next = [];
+        for (const si of frontier) {
+            const symcord1 = Math.floor(si / EDGE3_CORD2);
+            const cord2 = si % EDGE3_CORD2;
+            set4(edge, sym2Raw[symcord1] * FACT_X[8] + cord2);
+            for (let k = 0; k < 12; k++)
+                edgeo[k] = k;
+            for (let mi = 0; mi < 17; mi++) {
+                const m = EDGE3_MOVE_CASES[mi];
+                // the reference's getMvSym takes the UNMOVED state: the
+                // move-conjugated tables provide the moved canonical.
+                const idx = getMvSymFrom(edge, edgeo, m, sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto, symMove[m * EDGE3_CLASSES + symcord1]);
+                const canonical = idx >> 3;
+                if (getDistance(canonical) !== 0x0f)
+                    continue;
+                setDistance(canonical, depth + 1);
+                next.push(canonical);
+                // the rotation-conjugated representatives of the moved class
+                const symcord1x = Math.floor(canonical / EDGE3_CORD2);
+                let symStateBits = symState[symcord1x];
+                if (symStateBits === 1)
+                    continue;
+                fEdge.set(edge);
+                fEdgeo.set(edgeo);
+                applyMoveCase(fEdge, fEdgeo, m);
+                rotateByIndex(fEdge, fEdgeo, idx & 7);
+                for (let j = 1; (symStateBits = symStateBits >> 1) !== 0; j++) {
+                    if ((symStateBits & 1) !== 1)
+                        continue;
+                    gEdge.set(fEdge);
+                    gEdgeo.set(fEdgeo);
+                    rotateByIndex(gEdge, gEdgeo, j);
+                    const normalized = normalizePairingState(gEdge, gEdgeo);
+                    const idxx = symcord1x * EDGE3_CORD2 + (get12Perm(normalized.edge, 10) % EDGE3_CORD2);
+                    if (getDistance(idxx) !== 0x0f)
+                        continue;
+                    setDistance(idxx, depth + 1);
+                    next.push(idxx);
+                }
+            }
+        }
+        frontier = next;
+        depth++;
+    }
+    const distanceOfEdge = edge3DistanceLookup(distances);
+    return { distances, distanceOfEdge };
+}
+/**
+ * The distance lookup over a loaded distances buffer: builds the sym
+ * machinery once (cached) and returns a closure from the std-form edge
+ * (a 12-permutation) to its BFS distance.
+ */
+export function edge3DistanceLookup(distances) {
+    const t = symTables ?? buildSymTables();
+    const { sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto } = t;
+    const identity = Uint8Array.from({ length: 12 }, (_, i) => i);
+    return (e) => {
+        const std = normalizePairingState(e, identity).edge;
+        const idx = getMvSymFrom(std, identity, 20, sym2Raw, sym2Mask, raw2Sym, mvrot, mvroto) >> 3;
+        return (distances[idx >> 1] >> ((idx & 1) * 4)) & 0x0f;
+    };
+}
+// ---------------------------------------------------------------------------
+// Verification gates
+// ---------------------------------------------------------------------------
+/** Test-only hooks. */
+export function __edge3TestHooks() {
+    return { buildSymTables, applyMoveCase, get12Perm, set4, rotateByIndex, getMvSymFrom };
+}
+export function verifyEdge3(tables) {
+    const errors = [];
+    const identity = Uint8Array.from({ length: 12 }, (_, i) => i);
+    if (tables.distanceOfEdge(identity) !== 0) {
+        errors.push("Solved state must have distance 0.");
+    }
+    let seen = 0;
+    for (let i = 0; i < EDGE3_TOTAL; i++) {
+        if (((tables.distances[i >> 1] >> ((i & 1) * 4)) & 0x0f) !== 0x0f)
+            seen++;
+    }
+    if (seen !== EDGE3_TOTAL) {
+        errors.push(`Expected ${EDGE3_TOTAL} reachable classes, saw ${seen}.`);
+    }
+    return errors;
+}