@cubingcenter/scrambler 0.6.3 → 0.8.0

package/dist-cjs/puzzles/cube4/reduction/finish3.js

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * Continuous two-phase 3x3 solver for the 4x4 finish (Kociemba-style).
+ *
+ * Unlike the batch solver in `cube3/solver` (collect phase-1 solutions,
+ * then solve phase 2 for each), this is the classic continuous search: an
+ * iterative-deepening phase 1 where EVERY phase-1 solution immediately runs
+ * phase 2 under the remaining length budget, and every solution found
+ * tightens the bound for the rest of the search. Optional legal views are
+ * searched interleaved by phase-1 depth — up to 3 relabelled axes
+ * (identity, x, z) × {state, inverse} — which is what makes short solutions
+ * cheap to find (the existing cube3 solver's rotation/inverse trick).
+ *
+ * Tables: the already-loaded cube3 tables (phase-1: twist/flip/slice move
+ * tables + twist×flip, slice×twist, slice×flip pruning; phase-2: cp/ep/sp
+ * move tables + cp×sp, ep×sp pruning). Nothing is generated here.
+ *
+ * Deterministic: the only stopping rules are node counts and lengths, so
+ * the result is a pure function of (state, options).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Finish3SearchError = void 0;
+exports.solveFinish3 = solveFinish3;
+const types_js_1 = require("../../cube3/types.js");
+const moves_js_1 = require("../../cube3/moves.js");
+const state_js_1 = require("../../cube3/state.js");
+const moves_js_2 = require("../moves.js");
+const state_js_2 = require("../state.js");
+const phase4_js_1 = require("./phase4.js");
+const coordinates_js_1 = require("../../cube3/solver/coordinates.js");
+const tables_js_1 = require("../../cube3/solver/tables.js");
+const symmetry_js_1 = require("../../cube3/solver/symmetry.js");
+class Finish3SearchError extends Error {
+    code = "cube4-finish3-cap";
+    constructor(message) {
+        super(message);
+        this.name = "Finish3SearchError";
+    }
+}
+exports.Finish3SearchError = Finish3SearchError;
+function toCubie(state) {
+    return {
+        cp: Int8Array.from(state.corners.permutation),
+        co: Int8Array.from(state.corners.orientation),
+        ep: Int8Array.from(state.edges.permutation),
+        eo: Int8Array.from(state.edges.orientation)
+    };
+}
+function toState(cubie) {
+    return {
+        corners: { permutation: Array.from(cubie.cp), orientation: Array.from(cubie.co) },
+        edges: { permutation: Array.from(cubie.ep), orientation: Array.from(cubie.eo) }
+    };
+}
+function inverse(a) {
+    const out = { cp: new Int8Array(8), co: new Int8Array(8), ep: new Int8Array(12), eo: new Int8Array(12) };
+    for (let i = 0; i < 8; i++) {
+        out.cp[a.cp[i]] = i;
+        out.co[a.cp[i]] = (3 - a.co[i]) % 3;
+    }
+    for (let i = 0; i < 12; i++) {
+        out.ep[a.ep[i]] = i;
+        out.eo[a.ep[i]] = a.eo[i];
+    }
+    return out;
+}
+/** Per-move permutation effects, as the solved state with the move applied. */
+const MOVE_CUBIES = types_js_1.CUBE3_MOVES.map((move) => toCubie((0, moves_js_1.applyCube3Move)((0, state_js_1.createSolvedCube3State)(), move)));
+const MOVE_CP = Int8Array.from(MOVE_CUBIES.flatMap((c) => Array.from(c.cp)));
+const MOVE_EP = Int8Array.from(MOVE_CUBIES.flatMap((c) => Array.from(c.ep)));
+/** Face (U0 D1 R2 L3 F4 B5) of each phase-1 move index. */
+const FACE = Int8Array.from(types_js_1.CUBE3_MOVES.map((_, m) => Math.floor(m / 3)));
+/** Phase-1 move index of each phase-2 move index. */
+const P2_TO_P1 = Int8Array.from(tables_js_1.CUBE3_PHASE2_MOVES.map((move) => types_js_1.CUBE3_MOVES.indexOf(move)));
+/** Phase-1 moves that keep G1 (U, D, R2, L2, F2, B2). */
+const IS_P2_MOVE = new Uint8Array(18);
+for (const m of P2_TO_P1)
+    IS_P2_MOVE[m] = 1;
+/** Skip `face` after `last`: same face, or same axis in descending order. */
+const SKIP = new Uint8Array(7 * 6);
+for (let last = -1; last < 6; last++) {
+    for (let face = 0; face < 6; face++) {
+        SKIP[(last + 1) * 6 + face] =
+            last >= 0 && (face === last || ((face >> 1) === (last >> 1) && face < last)) ? 1 : 0;
+    }
+}
+const FACT = [1, 1, 2, 6, 24, 120, 720, 5040, 40320];
+/** Lehmer rank of values[offset..offset+n) (same order as `encodePermutation`). */
+function lehmer(values, offset, n, base) {
+    let rank = 0;
+    for (let i = 0; i < n; i++) {
+        const v = values[offset + i];
+        let smaller = 0;
+        for (let j = i + 1; j < n; j++)
+            if (values[offset + j] < v)
+                smaller++;
+        rank += smaller * FACT[n - 1 - i];
+    }
+    return rank - base * 0;
+}
+// ---------------------------------------------------------------------------
+// Views (relabelled scrambles and inverses)
+// ---------------------------------------------------------------------------
+const VIEW_ROTATIONS = [[], ["x"], ["z"]];
+function invertMoves(moves) {
+    return [...moves].reverse().map((move) => {
+        if (move.endsWith("2"))
+            return move;
+        if (move.endsWith("'"))
+            return move.slice(0, -1);
+        return `${move}'`;
+    });
+}
+function multiply(a, b) {
+    const out = { cp: new Int8Array(8), co: new Int8Array(8), ep: new Int8Array(12), eo: new Int8Array(12) };
+    for (let i = 0; i < 8; i++) {
+        out.cp[i] = a.cp[b.cp[i]];
+        out.co[i] = (a.co[b.cp[i]] + b.co[i]) % 3;
+    }
+    for (let i = 0; i < 12; i++) {
+        out.ep[i] = a.ep[b.ep[i]];
+        out.eo[i] = (a.eo[b.ep[i]] + b.eo[i]) % 2;
+    }
+    return out;
+}
+/** 3x3 cubies of the whole-cube rotations, read off the rotated 4x4 model. */
+const ROTATION_WORDS = {
+    x: ["Rw", "Lw'"],
+    z: ["Fw", "Bw'"]
+};
+const ROTATION_CUBIES = new Map(Object.entries(ROTATION_WORDS).map(([name, word]) => [
+    name,
+    toCubie((0, phase4_js_1.toCube3State)((0, moves_js_2.applyCube4Algorithm)((0, state_js_2.createSolvedCube4State)(), word)))
+]));
+/**
+ * Views of the state: conjugations by x / z and inverses. The x-view of S
+ * is R⁻¹·S·R (R = the rotation's cubie) — the same state the relabelled
+ * scramble `rotate(scramble(S), [x])` reaches (verified in
+ * test/cube4-finish3.test.ts), so a view solution maps back by relabelling
+ * with the inverse rotation. Conjugation preserves parity and legality.
+ */
+function buildViews(state, count) {
+    if (count !== 1 && count !== 2 && count !== 6) {
+        throw new RangeError(`finish3: unsupported view count ${count}`);
+    }
+    const base = toCubie(state);
+    const views = [];
+    const axes = count === 6 ? VIEW_ROTATIONS : [[]];
+    for (const rotation of axes) {
+        let viewCubie = base;
+        for (const r of rotation) {
+            const rc = ROTATION_CUBIES.get(r);
+            viewCubie = multiply(multiply(inverse(rc), viewCubie), rc);
+        }
+        const makeView = (inverted) => {
+            views.push({
+                cubie: inverted ? inverse(viewCubie) : viewCubie,
+                mapSolution: (moves) => {
+                    const direct = inverted ? invertMoves(moves) : [...moves];
+                    return rotation.length === 0
+                        ? direct
+                        : (0, symmetry_js_1.rotateCube3AlgorithmBySequence)(direct, (0, symmetry_js_1.invertCube3RotationSequence)(rotation));
+                }
+            });
+        };
+        makeView(false);
+        if (count >= 2)
+            makeView(true);
+    }
+    return views;
+}
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+function solveFinish3(state, tables, options = {}) {
+    const targetLength = options.targetLength ?? 0;
+    const maxNodes = options.maxNodes ?? 200_000;
+    const hardMaxNodes = options.hardMaxNodes ?? 20_000_000;
+    const maxP2 = options.maxPhase2Length ?? 12;
+    const views = buildViews(state, options.views ?? 1);
+    const p1 = tables.phase1;
+    const coMove = p1.moveTables.cornerOrientation.values;
+    const eoMove = p1.moveTables.edgeOrientation.values;
+    const udMove = p1.moveTables.udSlice.values;
+    const udSolved = p1.moveTables.udSlice.solvedCoordinate;
+    const coeo = p1.pruningTables.cornerOrientationEdgeOrientation.values;
+    const udPrun = p1.pruningTables.udSlice.values;
+    const jointUdCo = p1.jointTables?.jointUdCo;
+    const jointUdEo = p1.jointTables?.jointUdEo;
+    const p2 = tables.phase2;
+    if (p2.phase2Moves.join(" ") !== tables_js_1.CUBE3_PHASE2_MOVES.join(" ")) {
+        throw new Error("finish3: unexpected phase-2 move order");
+    }
+    const cpMove = p2.moveTables.cornerPermutation.values;
+    const epMove = p2.moveTables.udEdgePermutation.values;
+    const spMove = p2.moveTables.slicePermutation.values;
+    const cpsp = p2.pruningTables.cornerPermutationSlicePermutation.values;
+    const epsp = p2.pruningTables.udEdgePermutationSlicePermutation.values;
+    const nib = (table, index) => (table[index >> 1] >> ((index & 1) << 2)) & 0x0f;
+    const h1 = (co, eo, ud) => {
+        let h = nib(coeo, (co << 11) + eo);
+        if (jointUdCo !== undefined && jointUdEo !== undefined) {
+            const a = nib(jointUdCo, ud * 2187 + co);
+            if (a > h)
+                h = a;
+            const b = nib(jointUdEo, ud * 2048 + eo);
+            if (b > h)
+                h = b;
+        }
+        else {
+            const u = nib(udPrun, ud);
+            if (u > h)
+                h = u;
+        }
+        return h;
+    };
+    const h2 = (cp, ep, sp) => {
+        const a = nib(cpsp, cp * 24 + sp);
+        const b = nib(epsp, ep * 24 + sp);
+        return a > b ? a : b;
+    };
+    const path1 = new Int8Array(32);
+    const path2 = new Int8Array(32);
+    const cpScratch = new Int8Array(8);
+    const epScratch = new Int8Array(12);
+    const cpTmp = new Int8Array(8);
+    const epTmp = new Int8Array(12);
+    let nodes = 0;
+    let bound = 99; // best length found so far (solutions must be shorter)
+    let best = null;
+    let stop = false;
+    let view = views[0];
+    // Hot-path guard: `shouldStop` can only change its answer once `nodes`
+    // passes this limit (the other conditions are re-checked in `leaf`).
+    let nodeLimit = hardMaxNodes;
+    const hasJoint = jointUdCo !== undefined && jointUdEo !== undefined;
+    const shouldStop = () => {
+        if (nodes > hardMaxNodes) {
+            if (best === null) {
+                throw new Finish3SearchError("finish3: node cap exceeded without a solution");
+            }
+            stop = true;
+            return true;
+        }
+        if (best !== null)
+            nodeLimit = Math.min(maxNodes, hardMaxNodes);
+        if (best !== null && (nodes > maxNodes || bound <= targetLength)) {
+            stop = true;
+            return true;
+        }
+        return false;
+    };
+    const phase2 = (cp, ep, sp, depth, togo, last) => {
+        nodes++;
+        if (nodes > nodeLimit && shouldStop())
+            return false;
+        if (togo === 0)
+            return cp === 0 && ep === 0 && sp === 0;
+        const skipRow = (last + 1) * 6;
+        const limit = togo - 1;
+        const cpRow = cp * 10;
+        const epRow = ep * 10;
+        const spRow = sp * 10;
+        for (let i = 0; i < 10; i++) {
+            if (stop)
+                return false;
+            const m = P2_TO_P1[i];
+            if (SKIP[skipRow + FACE[m]])
+                continue;
+            const nsp = spMove[spRow + i];
+            const ncp = cpMove[cpRow + i];
+            const ia = ncp * 24 + nsp;
+            if (((cpsp[ia >> 1] >> ((ia & 1) << 2)) & 0x0f) > limit)
+                continue;
+            const nep = epMove[epRow + i];
+            const ib = nep * 24 + nsp;
+            if (((epsp[ib >> 1] >> ((ib & 1) << 2)) & 0x0f) > limit)
+                continue;
+            path2[depth] = m;
+            if (phase2(ncp, nep, nsp, depth + 1, togo - 1, FACE[m]))
+                return true;
+        }
+        return false;
+    };
+    /** Runs phase 2 on a phase-1 solution of length d1; true = stop searching. */
+    const leaf = (d1) => {
+        const base = view.cubie;
+        cpScratch.set(base.cp);
+        epScratch.set(base.ep);
+        for (let k = 0; k < d1; k++) {
+            const off = path1[k];
+            for (let i = 0; i < 8; i++)
+                cpTmp[i] = cpScratch[MOVE_CP[off * 8 + i]];
+            for (let i = 0; i < 12; i++)
+                epTmp[i] = epScratch[MOVE_EP[off * 12 + i]];
+            cpScratch.set(cpTmp);
+            epScratch.set(epTmp);
+        }
+        const cp = lehmer(cpScratch, 0, 8, 0);
+        const ep = lehmer(epScratch, 0, 8, 0);
+        for (let i = 8; i < 12; i++)
+            epTmp[i] = epScratch[i] - 8;
+        const sp = lehmer(epTmp, 8, 4, 0);
+        const lb = h2(cp, ep, sp);
+        const maxD2 = Math.min(bound - 1 - d1, maxP2);
+        if (lb > maxD2)
+            return false;
+        const last = d1 > 0 ? FACE[path1[d1 - 1]] : -1;
+        for (let d2 = lb; d2 <= maxD2; d2++) {
+            if (phase2(cp, ep, sp, 0, d2, last)) {
+                const moves = [];
+                for (let k = 0; k < d1; k++)
+                    moves.push(types_js_1.CUBE3_MOVES[path1[k]]);
+                for (let k = 0; k < d2; k++)
+                    moves.push(types_js_1.CUBE3_MOVES[path2[k]]);
+                best = view.mapSolution(moves);
+                bound = d1 + d2;
+                break;
+            }
+        }
+        return shouldStop();
+    };
+    const phase1 = (co, eo, ud, depth, togo, last) => {
+        nodes++;
+        if (togo === 0) {
+            // Only phase-1 solutions ending in a quarter turn of R/L/F/B: one
+            // ending in a G1 move is a shorter phase-1 solution plus phase 2.
+            if (depth > 0 && IS_P2_MOVE[path1[depth - 1]])
+                return false;
+            return leaf(depth);
+        }
+        if ((nodes & 1023) === 0 && shouldStop())
+            return true;
+        const skipRow = (last + 1) * 6;
+        const limit = togo - 1;
+        const lastLevel = togo === 1;
+        const coRow = co * 18;
+        const eoRow = eo * 18;
+        const udRow = ud * 18;
+        for (let m = 0; m < 18; m++) {
+            if (stop)
+                return true;
+            if (SKIP[skipRow + FACE[m]])
+                continue;
+            if (lastLevel && IS_P2_MOVE[m])
+                continue;
+            const nud = udMove[udRow + m];
+            const nco = coMove[coRow + m];
+            const neo = eoMove[eoRow + m];
+            if (hasJoint) {
+                const ia = nud * 2187 + nco;
+                if (((jointUdCo[ia >> 1] >> ((ia & 1) << 2)) & 0x0f) > limit)
+                    continue;
+                const ib = nud * 2048 + neo;
+                if (((jointUdEo[ib >> 1] >> ((ib & 1) << 2)) & 0x0f) > limit)
+                    continue;
+                const ic = (nco << 11) + neo;
+                if (((coeo[ic >> 1] >> ((ic & 1) << 2)) & 0x0f) > limit)
+                    continue;
+            }
+            else if (h1(nco, neo, nud) > limit)
+                continue;
+            path1[depth] = m;
+            if (phase1(nco, neo, nud, depth + 1, togo - 1, FACE[m]))
+                return true;
+        }
+        return false;
+    };
+    const roots = views.map((v) => {
+        const s = toState(v.cubie);
+        const co = (0, coordinates_js_1.encodeCornerOrientation)(s);
+        const eo = (0, coordinates_js_1.encodeEdgeOrientation)(s);
+        const ud = (0, coordinates_js_1.encodeUdSlice)(s);
+        return { co, eo, ud, h: h1(co, eo, ud), solvedG1: co === 0 && eo === 0 && ud === udSolved };
+    });
+    let minDepth = 99;
+    for (const r of roots)
+        if (r.h < minDepth)
+            minDepth = r.h;
+    for (let d1 = minDepth; d1 < bound && !stop; d1++) {
+        for (let v = 0; v < views.length && !stop; v++) {
+            const r = roots[v];
+            if (r.h > d1)
+                continue;
+            view = views[v];
+            if (d1 === 0) {
+                if (r.solvedG1 && leaf(0))
+                    stop = true;
+                continue;
+            }
+            if (phase1(r.co, r.eo, r.ud, 0, d1, -1))
+                stop = true;
+        }
+    }
+    if (best === null)
+        throw new Finish3SearchError("finish3: no solution found");
+    return { moves: best, nodes };
+}