@cubingcenter/scrambler 0.5.3 → 0.6.0

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

@@ -0,0 +1,245 @@
+/**
+ * Center1 (phase 1 of the 4x4 reduction solver): reduce the two colors of a
+ * chosen axis (U/D, R/L or F/B) onto a single face-pair.
+ *
+ * Design (simpler than the reference's symmetry-reduced tables, which use a
+ * fragile 48-element non-group of "block-turn symmetries"):
+ *  - coordinate: the raw C(24,8) = 735,471 mask of the positions holding the
+ *    two axis colors — NO symmetry reduction;
+ *  - pruning: the exact BFS distance table from the three face-pair goal
+ *    masks (God's number 9; the 27-move set reaches the whole space);
+ *  - search: greedy descent — any move that decreases the exact distance by
+ *    exactly 1 is on an optimal path, so repeatedly applying the first such
+ *    move reaches the goal in exactly `distance` moves, with zero
+ *    backtracking and no iterative deepening.
+ *
+ * One table serves all three axes (the face-pairs are equivalent goals).
+ * The phase-1 move set: 9 axes [U,R,F,D,L,B,Uw,Rw,Fw] × 3 powers = 27.
+ */
+import { FACE_MOVE_EFFECTS, parseMove } from "../moves.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const CENTER1_AXES = [
+    "U", "R", "F", "D", "L", "B", "Uw", "Rw", "Fw"
+];
+export const CENTER1_MOVES = CENTER1_AXES.flatMap((face) => [face, `${face}2`, `${face}'`]);
+export const CENTER1_RAW_STATES = 735471;
+// 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;
+})();
+// ---------------------------------------------------------------------------
+// Mask utilities (24-bit integers; bit i = center position i)
+// ---------------------------------------------------------------------------
+/** The mask of the positions holding the two axis colors (colors % 3 == urf). */
+export function center1Mask(centers, urf) {
+    let mask = 0;
+    for (let i = 0; i < 24; i++) {
+        if (centers[i] % 3 === urf)
+            mask |= 1 << i;
+    }
+    return mask;
+}
+/** C(24,8) combination rank of a mask. */
+export function rankCenter1Mask(mask) {
+    let idx = 0;
+    let r = 8;
+    for (let i = 23; i >= 0; i--) {
+        if ((mask >> i) & 1)
+            idx += CNK[i][r--];
+    }
+    return idx;
+}
+export function unrankCenter1Mask(idx) {
+    let mask = 0;
+    let r = 8;
+    for (let i = 23; i >= 0; i--) {
+        if (idx >= CNK[i][r]) {
+            idx -= CNK[i][r];
+            r--;
+            mask |= 1 << i;
+        }
+    }
+    return mask;
+}
+/** The three face-pair goal masks (bit i = center position i, face-major). */
+export const CENTER1_GOAL_MASKS = {
+    ud: 0xf00f,
+    rl: 0xf00f0,
+    fb: 0xf00f00
+};
+// ---------------------------------------------------------------------------
+// Move bit-permutations
+// ---------------------------------------------------------------------------
+/** The 27 phase-1 moves as bit-permutations of the 24-bit mask. */
+export function buildCenter1MoveMaps() {
+    const maps = new Int32Array(CENTER1_MOVES.length * 24);
+    for (let m = 0; m < CENTER1_MOVES.length; m++) {
+        const { face, turns } = parseMove(CENTER1_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;
+        }
+        // apply a move: dest bit i takes source bit pos[i]
+        for (let i = 0; i < 24; i++)
+            maps[m * 24 + i] = pos[i];
+    }
+    return maps;
+}
+export function applyCenter1Move(mask, moveMap, move) {
+    let out = 0;
+    for (let i = 0; i < 24; i++) {
+        if ((mask >> moveMap[move * 24 + i]) & 1)
+            out |= 1 << i;
+    }
+    return out;
+}
+export function generateCenter1Tables() {
+    const moveMaps = buildCenter1MoveMaps();
+    const distance = new Uint8Array(Math.ceil(CENTER1_RAW_STATES / 2)).fill(0xff);
+    const setDistance = (rank, d) => {
+        const byte = rank >> 1;
+        if ((rank & 1) === 0)
+            distance[byte] = (distance[byte] & 0xf0) | (d & 0x0f);
+        else
+            distance[byte] = (distance[byte] & 0x0f) | ((d & 0x0f) << 4);
+    };
+    const getDistance = (rank) => {
+        const byte = distance[rank >> 1];
+        return (rank & 1) === 0 ? byte & 0x0f : byte >> 4;
+    };
+    const isUnset = (rank) => {
+        const byte = distance[rank >> 1];
+        return (rank & 1) === 0 ? (byte & 0x0f) === 0x0f : (byte >> 4) === 0x0f;
+    };
+    // BFS from the three goal masks.
+    for (const goal of [CENTER1_GOAL_MASKS.ud, CENTER1_GOAL_MASKS.rl, CENTER1_GOAL_MASKS.fb]) {
+        setDistance(rankCenter1Mask(goal), 0);
+    }
+    const queue = [
+        rankCenter1Mask(CENTER1_GOAL_MASKS.ud),
+        rankCenter1Mask(CENTER1_GOAL_MASKS.rl),
+        rankCenter1Mask(CENTER1_GOAL_MASKS.fb)
+    ];
+    let head = 0;
+    while (head < queue.length) {
+        const rank = queue[head++];
+        const mask = unrankCenter1Mask(rank);
+        const d = getDistance(rank);
+        for (let m = 0; m < CENTER1_MOVES.length; m++) {
+            const next = applyCenter1Move(mask, moveMaps, m);
+            const nextRank = rankCenter1Mask(next);
+            if (isUnset(nextRank)) {
+                setDistance(nextRank, d + 1);
+                queue.push(nextRank);
+            }
+        }
+    }
+    // verify completeness: every state reached
+    let reached = 0;
+    for (let rank = 0; rank < CENTER1_RAW_STATES; rank++) {
+        if (!isUnset(rank))
+            reached++;
+    }
+    if (reached !== CENTER1_RAW_STATES) {
+        throw new Error(`Center1 BFS incomplete: ${reached}/${CENTER1_RAW_STATES} states reached.`);
+    }
+    return { distance, moveMaps };
+}
+export function getCenter1Distance(mask, tables) {
+    const rank = rankCenter1Mask(mask);
+    const byte = tables.distance[rank >> 1];
+    return (rank & 1) === 0 ? byte & 0x0f : byte >> 4;
+}
+/**
+ * Phase-1 greedy descent: bring the axis colors onto some face-pair in
+ * exactly `distance` moves (optimal). Every move that decreases the exact
+ * distance by 1 is on an optimal path, so no backtracking is needed.
+ * Returns null if the state is unreachable (should not happen).
+ */
+export function solveCenter1(centers, urf, tables) {
+    const solutions = solveCenter1All(centers, urf, tables, 1);
+    return solutions.length > 0 ? solutions[0] : null;
+}
+/**
+ * Enumerate phase-1 solutions (the optimal descending paths, then longer
+ * alternatives up to `cap`). The phase-1 → phase-3 pipeline needs variety:
+ * the phase-2 gate rate depends strongly on the phase-1 output's wings.
+ */
+export function solveCenter1All(centers, urf, tables, cap = 50) {
+    const moveMaps = tables.moveMaps;
+    const solutions = [];
+    const path = [];
+    const maxLength = 30;
+    const dfs = (mask, depth) => {
+        if (solutions.length >= cap)
+            return true;
+        const h = getCenter1Distance(mask, tables);
+        if (h === 0) {
+            solutions.push({ moves: path.slice(0, depth).map((m) => CENTER1_MOVES[m]), length: depth });
+            return false;
+        }
+        if (depth >= maxLength)
+            return false;
+        for (let m = 0; m < CENTER1_MOVES.length; m++) {
+            const next = applyCenter1Move(mask, moveMaps, m);
+            if (getCenter1Distance(next, tables) !== h - 1)
+                continue;
+            path[depth] = m;
+            if (dfs(next, depth + 1))
+                return true;
+        }
+        return false;
+    };
+    dfs(center1Mask(centers, urf), 0);
+    return solutions;
+}
+// ---------------------------------------------------------------------------
+// Verification gates
+// ---------------------------------------------------------------------------
+export function verifyCenter1(tables) {
+    const errors = [];
+    if (getCenter1Distance(CENTER1_GOAL_MASKS.ud, tables) !== 0) {
+        errors.push("Goal mask ud must have distance 0.");
+    }
+    if (getCenter1Distance(CENTER1_GOAL_MASKS.rl, tables) !== 0) {
+        errors.push("Goal mask rl must have distance 0.");
+    }
+    if (getCenter1Distance(CENTER1_GOAL_MASKS.fb, tables) !== 0) {
+        errors.push("Goal mask fb must have distance 0.");
+    }
+    // distances must be consistent with the moves
+    let maxDepth = 0;
+    for (let rank = 0; rank < CENTER1_RAW_STATES; rank++) {
+        const mask = unrankCenter1Mask(rank);
+        const d = getCenter1Distance(mask, tables);
+        if (d > maxDepth)
+            maxDepth = d;
+        for (let m = 0; m < CENTER1_MOVES.length; m++) {
+            const next = applyCenter1Move(mask, tables.moveMaps, m);
+            const nd = getCenter1Distance(next, tables);
+            if (nd < d - 1 || nd > d + 1) {
+                errors.push(`Distance inconsistency at rank ${rank} move ${CENTER1_MOVES[m]}: ${d} -> ${nd}.`);
+                break;
+            }
+        }
+    }
+    return errors;
+}

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

@@ -0,0 +1,91 @@
+/**
+ * Center2 (phase 2 of the 4x4 reduction solver): from the phase-1 output
+ * (axis colors on a face-pair), reach the phase-2 goal: the U/D/F/B faces
+ * uniform in color-class and the R/L faces in one of the 6 goal patterns.
+ *
+ * Ported from the reference's `Center2` class, adapted to this repo's layout:
+ *  - ct part: the 16 positions of the U, D, F, B faces, storing color % 3
+ *    (the color-class), ranked as C(15,8) vs ct[15] = 6,435 states;
+ *  - rl part: the 8 positions of the R, L faces, storing the actual colors,
+ *    ranked as C(7,4) vs rl[7] × 2 + wing-parity = 70 states;
+ *  - full coordinate: ct × 70 = 450,450;
+ *  - goal: ct == 0 and rl in the 6 reference goal patterns (even parity);
+ *  - the 28-move set keeps the ct and rl position sets separate, so the move
+ *    tables factor: ctmv (6,435×28) and rlmv (70×28);
+ *  - the search explores the first 23 moves (face moves + Uw2/Rw/Rw2/Rw').
+ *
+ * The phase-1 → phase-2 bridge (alignment + encode) is in `reduction.ts`.
+ */
+import type { Cube4State, Cube4Move } from "../types.js";
+/** The phase-2 move set (28 real moves + the reference's trailing no-op). */
+export declare const CENTER2_MOVES: readonly Cube4Move[];
+/** The search's exploration set (the first 23 of CENTER2_MOVES). */
+export declare const CENTER2_SEARCH_MOVES: readonly Cube4Move[];
+/** The 6 reference goal rl patterns (full 70-space values, even parity). */
+export declare const CENTER2_GOAL_RL: readonly number[];
+export declare const CENTER2_CT_STATES = 6435;
+export declare const CENTER2_RL_STATES = 70;
+export declare const CENTER2_STATES: number;
+export interface Center2Encoded {
+    ct: number;
+    rl: number;
+}
+export declare function wingPermutationParity(wp: Uint8Array): 0 | 1;
+/** Encode a full 4x4 state to the (ct, rl) coordinate (0..450,449). */
+export declare function encodeCenter2(state: Cube4State): Center2Encoded;
+export declare function isCenter2Goal(ct: number, rl: number): boolean;
+export interface Center2BridgeResult {
+    /** Alignment moves (0-2). */
+    alignment: Cube4Move[];
+    /** The aligned state (invariant). */
+    state: Cube4State;
+    /** The (ct, rl) coordinate of the aligned state. */
+    encoded: Center2Encoded;
+}
+/**
+ * Phase-1 → phase-2 bridge: apply the shortest alignment candidate that
+ * makes the state coordinate-invariant, then encode.
+ */
+export declare function center2Bridge(state: Cube4State): Center2BridgeResult | null;
+/**
+ * Generate the ct/rl move tables + the pruning BFS. The move tables are
+ * computed from canonical decodes (the class partition is all the rank
+ * needs — the actual class values are irrelevant).
+ */
+export interface Center2Tables {
+    /** 6435 × 28 — ct rank after each move. */
+    ctMove: Int32Array;
+    /** 70 × 28 — rl rank (parity included) after each move. */
+    rlMove: Int32Array;
+    /** 450,450 exact BFS distances from the goal. */
+    pruning: Uint8Array;
+}
+export declare function generateCenter2Tables(): Center2Tables;
+export interface Center2Phase2Result {
+    /** Phase-2 solution moves (standard 4x4 moves). */
+    moves: Cube4Move[];
+    /** Final coordinate (satisfies isCenter2Goal). */
+    ct: number;
+    rl: number;
+    /** Final wing permutation (present for gated solutions). */
+    wp?: Uint8Array;
+}
+export declare function solveCenter2(startCt: number, startRl: number, tables: Center2Tables, maxLength?: number): Center2Phase2Result | null;
+/**
+ * Enumerate phase-2 solutions (shortest first). The phase-2 → phase-3 bridge
+ * needs multiple candidates: the reference filters them by the pairing gate
+ * (transversal + even wing permutation), which most states fail.
+ */
+export declare function solveCenter2All(startCt: number, startRl: number, tables: Center2Tables, maxLength?: number, cap?: number): Center2Phase2Result[];
+/**
+ * Solve Center 2 gated for an exact target length.
+ */
+export declare function solveCenter2GatedLength(startCt: number, startRl: number, startWp: Uint8Array, tables: Center2Tables, isGateEligible: (wp: Uint8Array) => boolean, targetLength: number, moveLog?: number[]): Center2Phase2Result | null;
+/**
+ * Phase-2 search that tracks the wing permutation alongside the (ct, rl)
+ * coordinate and only accepts goal states whose wings satisfy the pairing
+ * transversal (the phase-3 entry gate).
+ */
+export declare function solveCenter2Gated(startCt: number, startRl: number, startWp: Uint8Array, tables: Center2Tables, isGateEligible: (wp: Uint8Array) => boolean, maxLength?: number): Center2Phase2Result | null;
+export declare function verifyCenter2(tables: Center2Tables): string[];
+//# sourceMappingURL=center2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"center2.d.ts","sourceRoot":"","sources":["../../../../src/puzzles/cube4/reduction/center2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOzD,6EAA6E;AAC7E,eAAO,MAAM,aAAa,EAAE,SAAS,SAAS,EAIpC,CAAC;AAEX,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,EAAE,SAAS,SAAS,EAA+B,CAAC;AAErF,4EAA4E;AAC5E,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAA4B,CAAC;AAE1E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,cAAc,QAAwC,CAAC;AA6BpE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAYD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,UAAU,GAAG,CAAC,GAAG,CAAC,CAe3D;AAED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,CAQ/D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAE7D;AA4BD,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,qCAAqC;IACrC,KAAK,EAAE,UAAU,CAAC;IAClB,oDAAoD;IACpD,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,GAAG,IAAI,CAe3E;AAsBD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,UAAU,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE,UAAU,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,UAAU,CAAC;CACrB;AAeD,wBAAgB,qBAAqB,IAAI,aAAa,CAoErD;AAMD,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AA+BD,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,EACrB,SAAS,SAAK,GACb,mBAAmB,GAAG,IAAI,CAG5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,EACrB,SAAS,SAAK,EACd,GAAG,SAAM,GACR,mBAAmB,EAAE,CAkCvB;AAyBD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,EAC3C,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,MAAM,EAAoC,GAClD,mBAAmB,GAAG,IAAI,CA2C5B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,aAAa,EACrB,cAAc,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,EAC3C,SAAS,SAAK,GACb,mBAAmB,GAAG,IAAI,CAgB5B;AAsBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,EAAE,CA2B7D"}