@cubingcenter/scrambler 0.5.3 → 0.6.0

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

@@ -0,0 +1,278 @@
+/**
+ * Center3 (the center part of the phase-3 search): track the center
+ * arrangement through the phase-3 moves (which disturb the solved centers
+ * with the wide doubles) and reach the fully-solved centers.
+ *
+ * Ported from the reference's `Center3` class, adapted to this repo's
+ * layout. The state is three 8-entry arrays of "half-class" bits
+ * ((color / 3) ^ 1) per face-pair, plus a parity bit:
+ *  - ud: the U, D face positions (this repo: U = 0-3, D = 12-15)
+ *  - fb: the F, B face positions (8-11, 20-23)
+ *  - rl: the R, L face positions (4-7, 16-19)
+ *
+ * Coordinate (reference `$getct_0`): C(7,4) ranks of ud and fb vs their 8th
+ * entry (35 each), the rl C(8,4) rank reduced to one of 12 standard values,
+ * then ×2 + parity = 29,400 × 2. The rank-0 pattern is "the first four
+ * entries differ from the last four" — i.e. each face-pair uniform in half
+ * — which is exactly the solved-cube arrangement (verified: the solved cube
+ * encodes to coordinate 0). The parity bit absorbs the wing-pairing parity
+ * XOR the corner parity at the phase-2 → phase-3 bridge and flips on the
+ * wide doubles (`pmove`).
+ */
+import { FACE_MOVE_EFFECTS, parseMove } from "../moves.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const CENTER3_MOVES = [
+    "U", "U2", "U'", "R2", "F", "F2", "F'", "D", "D2", "D'",
+    "L2", "B", "B2", "B'", "Uw2", "Rw2", "Fw2", "Dw2", "Lw2", "Bw2"
+];
+/** The 17-move BFS subset (the reference's pruning loop uses m < 17). */
+export const CENTER3_BFS_MOVES = CENTER3_MOVES.slice(0, 17);
+/** Wide doubles flip the parity bit. */
+const PARITY_FLIP = new Set(["Uw2", "Rw2", "Fw2", "Dw2", "Lw2", "Bw2"]);
+/** Face-pair positions in this repo's numbering. */
+const UD_POS = [0, 1, 2, 3, 12, 13, 14, 15];
+const FB_POS = [8, 9, 10, 11, 20, 21, 22, 23];
+const RL_POS = [4, 5, 6, 7, 16, 17, 18, 19];
+/** The 12 standard rl ranks (reference rl2std). */
+const RL2STD = [0, 9, 14, 23, 27, 28, 41, 42, 46, 55, 60, 69];
+export const CENTER3_STATES = 29400;
+// Cnk table up to n=24.
+const CNK = (() => {
+    const table = [];
+    for (let n = 0; n <= 24; n++) {
+        table[n] = [];
+        for (let k = 0; k <= 24; k++) {
+            if (k === 0 || k === n)
+                table[n][k] = 1;
+            else if (k > n)
+                table[n][k] = 0;
+            else
+                table[n][k] = table[n - 1][k - 1] + table[n - 1][k];
+        }
+    }
+    return table;
+})();
+// ---------------------------------------------------------------------------
+// Half-class helpers
+// ---------------------------------------------------------------------------
+function halfClass(color) {
+    return (Math.floor(color / 3) ^ 1) & 1;
+}
+/** C(7,4) rank of the entries differing from the last one. */
+function rank7(values) {
+    const last = values[7];
+    let idx = 0;
+    let r = 4;
+    for (let i = 6; i >= 0; i--) {
+        if (values[i] !== last)
+            idx += CNK[i][r--];
+    }
+    return idx;
+}
+/** C(8,4) rank of the entries differing from `check`. */
+function rank8(values, check) {
+    let idx = 0;
+    let r = 4;
+    for (let i = 7; i >= 0; i--) {
+        if (values[i] !== check)
+            idx += CNK[i][r--];
+    }
+    return idx;
+}
+/**
+ * Encode a full cube state to the Center3 coordinate.
+ *
+ * `edgeXorCornerParity` = the $set_6 pairing parity XOR the corner
+ * permutation parity, computed at the phase-2 → phase-3 bridge.
+ */
+export function encodeCenter3(state, edgeXorCornerParity) {
+    const colors = state.centers;
+    // reference: parity = (ct[0]%3 > ct[8]%3) ^ (ct[8]%3 > ct[16]%3) ^ (ct[0]%3 > ct[16]%3) ? 0 : 1
+    const a = colors[0] % 3;
+    const b = colors[8] % 3;
+    const c = colors[16] % 3;
+    const xored = (a > b ? 1 : 0) ^ (b > c ? 1 : 0) ^ (a > c ? 1 : 0);
+    const parity = xored === 0 ? 1 : 0;
+    const ud = new Uint8Array(8);
+    const fb = new Uint8Array(8);
+    const rl = new Uint8Array(8);
+    for (let i = 0; i < 8; i++) {
+        ud[i] = halfClass(colors[UD_POS[i]]);
+        fb[i] = halfClass(colors[FB_POS[i]]);
+        rl[i] = halfClass(colors[RL_POS[i]]);
+    }
+    let idx = rank7(ud);
+    idx = idx * 35 + rank7(fb);
+    idx *= 12;
+    const check = fb[7] ^ ud[7];
+    const rlRank = rank8(rl, check);
+    const rlIndex = RL2STD.indexOf(rlRank);
+    const finalParity = (parity ^ edgeXorCornerParity);
+    return {
+        coordinate: finalParity + 2 * (idx + rlIndex),
+        parity: finalParity
+    };
+}
+// ---------------------------------------------------------------------------
+// Move tables + pruning
+// ---------------------------------------------------------------------------
+function buildMovePositionMaps() {
+    const maps = new Int32Array(CENTER3_MOVES.length * 24);
+    for (let m = 0; m < CENTER3_MOVES.length; m++) {
+        const { face, turns } = parseMove(CENTER3_MOVES[m]);
+        const effect = FACE_MOVE_EFFECTS[face];
+        let pos = Array.from({ length: 24 }, (_, i) => i);
+        for (let t = 0; t < turns; t++) {
+            const next = new Array(24);
+            for (let i = 0; i < 24; i++)
+                next[i] = pos[effect.ctperm[i]];
+            pos = next;
+        }
+        for (let i = 0; i < 24; i++)
+            maps[m * 24 + i] = pos[i];
+    }
+    return maps;
+}
+/**
+ * Decode a coordinate to canonical half-class arrays (for the move tables):
+ * the rank-0 pattern is "first four differ from the last four", so the
+ * canonical state is ud = [1,1,1,1,0,0,0,0], fb = [1,1,1,1,0,0,0,0],
+ * rl = [1,1,1,1,0,0,0,0] for coordinate 0.
+ */
+function decodeCenter3(coordinate) {
+    const parity = coordinate & 1;
+    let value = coordinate >> 1;
+    const rlIndex = value % 12;
+    value = Math.floor(value / 12);
+    const fbRank = value % 35;
+    const udRank = Math.floor(value / 35);
+    const ud = new Uint8Array(8);
+    const fb = new Uint8Array(8);
+    const rl = new Uint8Array(8);
+    // unrank C(7,4) patterns
+    let idx = udRank;
+    let r = 4;
+    for (let i = 6; i >= 0; i--) {
+        if (idx >= CNK[i][r]) {
+            idx -= CNK[i][r];
+            r--;
+            ud[i] = 1;
+        }
+    }
+    idx = fbRank;
+    r = 4;
+    for (let i = 6; i >= 0; i--) {
+        if (idx >= CNK[i][r]) {
+            idx -= CNK[i][r];
+            r--;
+            fb[i] = 1;
+        }
+    }
+    // rl: the standard rank from the index
+    const rlRank = RL2STD[rlIndex];
+    idx = rlRank;
+    r = 4;
+    for (let i = 7; i >= 0; i--) {
+        if (idx >= CNK[i][r]) {
+            idx -= CNK[i][r];
+            r--;
+            rl[i] = 1;
+        }
+    }
+    return { ud, fb, rl, parity };
+}
+export function generateCenter3Tables() {
+    const moveMaps = buildMovePositionMaps();
+    const moveTable = new Int32Array(CENTER3_STATES * CENTER3_MOVES.length).fill(-1);
+    // canonical full arrangements: half-class bits at the face-pair positions.
+    // The rl array stores the parity-XORed halves, so the decode undoes the XOR
+    // to recover the colors; the move evolution re-extracts the RAW halves and
+    // evolves the parity bit via pmove only (it is NOT re-derived from the
+    // centers, matching the reference's doMoveCenter3).
+    const full = new Uint8Array(24);
+    const moved = new Uint8Array(24);
+    const ud2 = new Uint8Array(8);
+    const fb2 = new Uint8Array(8);
+    const rl2 = new Uint8Array(8);
+    const coordinateOfMoved = (coordinate, m, parity) => {
+        const { ud, fb, rl } = decodeCenter3(coordinate);
+        // the half-class arrays live at the 24 face-pair positions; a move is a
+        // position permutation, so build the 24-array, permute, and re-extract.
+        for (let i = 0; i < 24; i++)
+            full[i] = 0;
+        for (let i = 0; i < 8; i++) {
+            full[UD_POS[i]] = ud[i];
+            full[FB_POS[i]] = fb[i];
+            full[RL_POS[i]] = rl[i];
+        }
+        const map = moveMaps;
+        for (let i = 0; i < 24; i++)
+            moved[i] = full[map[m * 24 + i]];
+        for (let i = 0; i < 8; i++) {
+            ud2[i] = moved[UD_POS[i]];
+            fb2[i] = moved[FB_POS[i]];
+            rl2[i] = moved[RL_POS[i]];
+        }
+        let idx = rank7(ud2);
+        idx = idx * 35 + rank7(fb2);
+        idx *= 12;
+        const check = fb2[7] ^ ud2[7];
+        const rlRank = rank8(rl2, check);
+        const rlIndex = RL2STD.indexOf(rlRank);
+        if (rlIndex < 0)
+            return -1;
+        const nextParity = (parity ^ (PARITY_FLIP.has(CENTER3_MOVES[m]) ? 1 : 0));
+        return nextParity + 2 * (idx + rlIndex);
+    };
+    // BFS from coordinate 0 with the 17 BFS moves, computing the move-table
+    // entries on demand (only the reachable states' transitions are needed).
+    const pruning = new Uint8Array(CENTER3_STATES).fill(0xff);
+    pruning[0] = 0;
+    const queue = [0];
+    let head = 0;
+    while (head < queue.length) {
+        const coord = queue[head++];
+        const d = pruning[coord];
+        for (let m = 0; m < CENTER3_MOVES.length; m++) {
+            const next = coordinateOfMoved(coord, m, coord & 1);
+            if (next < 0)
+                continue;
+            moveTable[coord * CENTER3_MOVES.length + m] = next;
+            if (m < CENTER3_BFS_MOVES.length && pruning[next] === 0xff) {
+                pruning[next] = d + 1;
+                queue.push(next);
+            }
+        }
+    }
+    return { moveTable, pruning };
+}
+// ---------------------------------------------------------------------------
+// Verification gates
+// ---------------------------------------------------------------------------
+export function verifyCenter3(tables) {
+    const errors = [];
+    if (tables.pruning[0] !== 0) {
+        errors.push("Goal coordinate must have pruning 0.");
+    }
+    let maxDepth = 0;
+    for (let coord = 0; coord < CENTER3_STATES; coord++) {
+        const d = tables.pruning[coord];
+        if (d === 0xff)
+            continue; // unreachable coordinates have no entries
+        if (d > maxDepth)
+            maxDepth = d;
+        for (let m = 0; m < CENTER3_MOVES.length; m++) {
+            const next = tables.moveTable[coord * CENTER3_MOVES.length + m];
+            if (next < 0)
+                continue;
+            const nd = tables.pruning[next];
+            if (nd === 0xff || nd < d - 1 || nd > d + 1) {
+                errors.push(`Pruning inconsistency at ${coord} move ${CENTER3_MOVES[m]}: ${d} -> ${nd}.`);
+                break;
+            }
+        }
+    }
+    return errors;
+}

package/dist/puzzles/cube4/reduction/edge3.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+/** The sym-index space: 1538 first-4 classes × 20160 remaining. */
+export declare const EDGE3_TOTAL = 31006080;
+export declare const EDGE3_CLASSES = 1538;
+export declare const EDGE3_CORD2 = 20160;
+/** The maximum BFS depth (the reference's prunValues length - 1). */
+export declare const EDGE3_MAX_DEPTH = 13;
+/** The reference's `move3std`: $move_4 case → std3 move id (the % 3 class). */
+export declare const MOVE3_STD: readonly number[];
+export declare function bitCount(v: number): number;
+/**
+ * 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`.
+ */
+declare function applyMoveCase(edge: Uint8Array, edgeo: Uint8Array, m: number): void;
+/** The reference's `$rotate_0`: rotation r (0..7) via the rot1 decomposition. */
+declare function rotateByIndex(edge: Uint8Array, edgeo: Uint8Array, r: number): void;
+/**
+ * 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.
+ */
+declare function get12Perm(arr: Uint8Array, end: number, returnMask?: boolean): number;
+/**
+ * Decode a 12-permutation from the mixed-radix index (the reference's
+ * `$set_4`): the 11 digits with the parity-corrected last two positions.
+ */
+declare function set4(out: Uint8Array, idx: number): void;
+export interface SymTables {
+    mvrot: Uint8Array;
+    mvroto: Uint8Array;
+    sym2Raw: Uint32Array;
+    /** class → the used-values mask of its representative's first 4. */
+    sym2Mask: Uint32Array;
+    /** first-4 Lehmer → (class << 3 | rotation). */
+    raw2Sym: Uint32Array;
+    /** class → the bitmask of the rotations mapping the representative to itself. */
+    symState: Uint32Array;
+    /** (move, class) → the moved state's (class << 3 | rotation) for the %3==1 moves. */
+    symMove: Uint16Array;
+}
+export declare function getSymTables(): SymTables;
+export declare function buildSymTables(): SymTables;
+/**
+ * The reference's `getMvSym`: the canonical sym-index of the state (edge,
+ * edgeo) under the move-conjugated rotation, as `(sym-index << 3 | r)`.
+ */
+export declare function getMvSymFrom(edge: Uint8Array, _edgeo: Uint8Array, mv: number, sym2Raw: Uint32Array, sym2Mask: Uint32Array, raw2Sym: Uint32Array, mvrot: Uint8Array, mvroto: Uint8Array, assumeIdx?: number): number;
+export interface Edge3Tables {
+    /** sym-index → BFS distance (packed 4-bit nibbles). */
+    distances: Uint8Array;
+    /** the distance of a std-form edge (a 12-permutation). */
+    distanceOfEdge(edge: Uint8Array): number;
+}
+/**
+ * Generate the exact BFS distances over the 31,006,080 sym-index space.
+ * `maxDepthCap` stops the BFS early (validation only).
+ */
+export declare function generateEdge3Tables(maxDepthCap?: number): Edge3Tables;
+/**
+ * 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 declare function edge3DistanceLookup(distances: Uint8Array): (edge: Uint8Array) => number;
+/** Test-only hooks. */
+export declare function __edge3TestHooks(): {
+    buildSymTables: typeof buildSymTables;
+    applyMoveCase: typeof applyMoveCase;
+    get12Perm: typeof get12Perm;
+    set4: typeof set4;
+    rotateByIndex: typeof rotateByIndex;
+    getMvSymFrom: typeof getMvSymFrom;
+};
+export declare function verifyEdge3(tables: Edge3Tables): string[];
+export {};
+//# sourceMappingURL=edge3.d.ts.map

package/dist/puzzles/cube4/reduction/edge3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge3.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/edge3.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,mEAAmE;AACnE,eAAO,MAAM,WAAW,WAAa,CAAC;AACtC,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,eAAO,MAAM,WAAW,QAAS,CAAC;AAGlC,qEAAqE;AACrE,eAAO,MAAM,eAAe,KAAK,CAAC;AAUlC,+EAA+E;AAC/E,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAEtC,CAAC;AAaF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAkCD;;;;;GAKG;AACH,iBAAS,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CA2G3E;AAkCD,iFAAiF;AACjF,iBAAS,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAO3E;AAMD;;;;GAIG;AACH,iBAAS,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,UAAQ,GAAG,MAAM,CAS3E;AAED;;;GAGG;AACH,iBAAS,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAmBhD;AAOD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,oEAAoE;IACpE,QAAQ,EAAE,WAAW,CAAC;IACtB,gDAAgD;IAChD,OAAO,EAAE,WAAW,CAAC;IACrB,iFAAiF;IACjF,QAAQ,EAAE,WAAW,CAAC;IACtB,qFAAqF;IACrF,OAAO,EAAE,WAAW,CAAC;CACtB;AAID,wBAAgB,YAAY,IAAI,SAAS,CAKxC;AAED,wBAAgB,cAAc,IAAI,SAAS,CAoE1C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,WAAW,EACrB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CA6BR;AAMD,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,SAAS,EAAE,UAAU,CAAC;IACtB,0DAA0D;IAC1D,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,SAAK,GAAG,WAAW,CAkEjE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,UAAU,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CASvF;AAMD,uBAAuB;AACvB,wBAAgB,gBAAgB;;;;;;;EAE/B;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAgBzD"}