redscript-mc 2.1.1 → 2.3.0

package/dist/src/tuner/adapters/ln-polynomial.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * ln(x) polynomial approximation adapter — atanh series form.
+ *
+ * Algorithm:
+ *   Input x: fixed-point integer (×10000), e.g. 10000 = 1.0
+ *   1. Range reduction: find k s.t. xr ∈ [10000, 20000)
+ *   2. s = (xr - 10000) * 10000 / (xr + 10000)   →  s ∈ [0, 3333]
+ *   3. ln(xr/10000) ≈ A1*s/SCALE + A3*s³/SCALE² + A5*s⁵/SCALE³
+ *      (coefficients absorb the factor of 2; theoretical: A1=20000, A3=6667, A5=4000)
+ *   4. ln(x/10000) = k * LN2 + ln(xr/10000)
+ *
+ * Intermediate overflow analysis (s ≤ 3333, SCALE = 10000):
+ *   s²    = s*s    ≤ 11M   — fits int32 (max ~2.1B)
+ *   s2    = s²/SCALE ≤ 1111
+ *   s3    = s*s2   ≤ 3.7M  — fits int32
+ *   s5    = s3*s2  ≤ 4.1M  — fits int32
+ *   A1*s  ≤ 22000*3333 ≤ 73M — fits int32
+ *   A3*s3 ≤ 7000*3703  ≤ 26M — fits int32
+ *   A5*s5 ≤ 5000*4115  ≤ 21M — fits int32
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lnPolynomialAdapter = exports.defaultParams = void 0;
+const simulator_1 = require("../simulator");
+const SCALE = 10000;
+const LN2_SCALED = 6931; // ln(2) * 10000
+exports.defaultParams = {
+    A1: 20000,
+    A3: 6667,
+    A5: 4000,
+};
+exports.lnPolynomialAdapter = {
+    name: 'ln-polynomial',
+    description: 'ln(x) atanh series approximation using fixed-point int32 arithmetic',
+    params: [
+        { name: 'A1', range: [18000, 22000], integer: true },
+        { name: 'A3', range: [5000, 9000], integer: true },
+        { name: 'A5', range: [2000, 6000], integer: true },
+    ],
+    simulate(input, params) {
+        const A1 = (0, simulator_1.i32)(params['A1']);
+        const A3 = (0, simulator_1.i32)(params['A3']);
+        const A5 = (0, simulator_1.i32)(params['A5']);
+        let x = (0, simulator_1.i32)(input);
+        if (x <= 0)
+            return -2147483648;
+        // Step 1: range reduction to [10000, 20000)
+        let k = 0;
+        while (x < 10000) {
+            x = (0, simulator_1.i32)(x * 2);
+            k--;
+        }
+        while (x >= 20000) {
+            x = (0, simulator_1.i32)(x / 2);
+            k++;
+        }
+        // Step 2: s = (xr - SCALE) * SCALE / (xr + SCALE)
+        const num = (0, simulator_1.i32)((0, simulator_1.i32)(x - SCALE) * SCALE);
+        const den = (0, simulator_1.i32)(x + SCALE);
+        if (den === 0)
+            return Infinity;
+        const s = (0, simulator_1.i32)(num / den); // s ∈ [0, 3333]
+        // Step 3: atanh series  (overflow-safe, each power divided by SCALE)
+        const s2 = (0, simulator_1.i32)((0, simulator_1.i32)(s * s) / SCALE); // s²/SCALE    ∈ [0, 1111]
+        const s3 = (0, simulator_1.i32)((0, simulator_1.i32)(s * s2) / SCALE); // s³/SCALE²   ∈ [0, 370]
+        const s5 = (0, simulator_1.i32)((0, simulator_1.i32)(s3 * s2) / SCALE); // s⁵/SCALE⁴   ∈ [0, 41]
+        const lnxr = (0, simulator_1.i32)((0, simulator_1.i32)(A1 * s / SCALE) +
+            (0, simulator_1.i32)(A3 * s3 / SCALE) +
+            (0, simulator_1.i32)(A5 * s5 / SCALE));
+        // Step 4: ln(x) = k*ln(2) + ln(xr)
+        return (0, simulator_1.i32)((0, simulator_1.i32)(k * LN2_SCALED) + lnxr);
+    },
+    reference(input) {
+        if (input <= 0)
+            return -Infinity;
+        return Math.log(input / SCALE) * SCALE;
+    },
+    sampleInputs() {
+        const inputs = [];
+        // logarithmic sampling from 0.01 to 100 (×10000: 100 to 1_000_000)
+        const logMin = Math.log10(100);
+        const logMax = Math.log10(1_000_000);
+        const steps = 200;
+        for (let i = 0; i <= steps; i++) {
+            const v = logMin + (i / steps) * (logMax - logMin);
+            inputs.push(Math.round(Math.pow(10, v)));
+        }
+        return inputs;
+    },
+    generateCode(params, meta) {
+        const A1 = Math.round(params['A1']);
+        const A3 = Math.round(params['A3']);
+        const A5 = Math.round(params['A5']);
+        return `// AUTO-GENERATED by redscript tune — DO NOT EDIT
+// Adapter: ln-polynomial | Date: ${meta.tuneDate}
+// max_error: ${meta.maxError.toFixed(6)} | mae: ${meta.mae.toFixed(6)} | estimated_cmds: ${meta.estimatedCmds}
+// Run \`redscript tune --adapter ln-polynomial\` to regenerate
+//
+// atanh series coefficients (×10000 scale):
+//   A1 = ${A1}  (theoretical 2×10000 = 20000)
+//   A3 = ${A3}  (theoretical 2/3×10000 = 6667)
+//   A5 = ${A5}  (theoretical 2/5×10000 = 4000)
+
+fn ln(x: int): int {
+    // Input x: fixed-point ×10000; returns ln(x/10000)×10000
+    // Valid range: x ∈ [100, 1000000]  (0.01 ~ 100.0)
+    // max_error: ${meta.maxError.toFixed(6)} (in ×10000 units, i.e. ${(meta.maxError / SCALE).toFixed(8)} in real units)
+
+    let scale: int = ${SCALE};
+    let ln2: int = ${LN2_SCALED};
+    let A1: int = ${A1};
+    let A3: int = ${A3};
+    let A5: int = ${A5};
+
+    // Step 1: range reduction — bring x into [scale, 2*scale)
+    let xr: int = x;
+    let k: int = 0;
+    while (xr < scale) {
+        xr = xr * 2;
+        k = k - 1;
+    }
+    while (xr >= scale * 2) {
+        xr = xr / 2;
+        k = k + 1;
+    }
+
+    // Step 2: s = (xr - scale) * scale / (xr + scale)
+    let s: int = (xr - scale) * scale / (xr + scale);
+
+    // Step 3: atanh series ln(xr/scale) ≈ A1*s + A3*s³ + A5*s⁵ (all /scale)
+    let s2: int = s * s / scale;
+    let s3: int = s * s2;
+    let s5: int = s3 * s2;
+    let lnxr: int = A1 * s / scale + A3 * s3 / scale + A5 * s5 / scale;
+
+    // Step 4: ln(x) = k*ln(2) + ln(xr/scale)
+    return k * ln2 + lnxr;
+}
+`;
+    },
+};
+//# sourceMappingURL=ln-polynomial.js.map

package/dist/src/tuner/adapters/sqrt-newton.d.ts

@@ -0,0 +1,28 @@
+/**
+ * sqrt(x) Newton's method adapter — fixed-point ×10000 scale.
+ *
+ * Algorithm:
+ *   Input x: fixed-point integer (×10000), e.g. 10000 = 1.0
+ *   Target: return floor(sqrt(x/10000) * 10000)
+ *
+ *   1. If x <= 0, return 0
+ *   2. Initial guess: g = x >> INIT_SHIFT  (default: x/2)
+ *   3. Newton iteration: g = (g + x * 10000 / g) / 2, repeated N times
+ *      Overflow-safe: x * 10000 / g  →  (x * 100) / (g / 100)
+ *   4. Return g
+ *
+ * Valid range: x ∈ [1, 1_000_000]  (real range 0.0001 to 100.0)
+ *   Larger x needs more iterations; beyond 1M, convergence is not guaranteed
+ *   within N=12 iterations from an x/2 initial guess.
+ *
+ * Overflow analysis (x ≤ 1_000_000, SCALE = 10000):
+ *   x * 100 ≤ 100_000_000 — fits int32 (max ~2.1B) ✓
+ *   g / 100 is never 0 for g ≥ 100 (guard included) ✓
+ *
+ * Parameters:
+ *   N:          iteration count, range [4, 12], integer
+ *   INIT_SHIFT: initial guess right shift, range [0, 3], integer (1 → x/2)
+ */
+import { TunerAdapter } from '../types';
+export declare const defaultParams: Record<string, number>;
+export declare const sqrtNewtonAdapter: TunerAdapter;

package/dist/src/tuner/adapters/sqrt-newton.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * sqrt(x) Newton's method adapter — fixed-point ×10000 scale.
+ *
+ * Algorithm:
+ *   Input x: fixed-point integer (×10000), e.g. 10000 = 1.0
+ *   Target: return floor(sqrt(x/10000) * 10000)
+ *
+ *   1. If x <= 0, return 0
+ *   2. Initial guess: g = x >> INIT_SHIFT  (default: x/2)
+ *   3. Newton iteration: g = (g + x * 10000 / g) / 2, repeated N times
+ *      Overflow-safe: x * 10000 / g  →  (x * 100) / (g / 100)
+ *   4. Return g
+ *
+ * Valid range: x ∈ [1, 1_000_000]  (real range 0.0001 to 100.0)
+ *   Larger x needs more iterations; beyond 1M, convergence is not guaranteed
+ *   within N=12 iterations from an x/2 initial guess.
+ *
+ * Overflow analysis (x ≤ 1_000_000, SCALE = 10000):
+ *   x * 100 ≤ 100_000_000 — fits int32 (max ~2.1B) ✓
+ *   g / 100 is never 0 for g ≥ 100 (guard included) ✓
+ *
+ * Parameters:
+ *   N:          iteration count, range [4, 12], integer
+ *   INIT_SHIFT: initial guess right shift, range [0, 3], integer (1 → x/2)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqrtNewtonAdapter = exports.defaultParams = void 0;
+const simulator_1 = require("../simulator");
+const SCALE = 10000;
+exports.defaultParams = {
+    N: 8,
+    INIT_SHIFT: 1,
+};
+exports.sqrtNewtonAdapter = {
+    name: 'sqrt-newton',
+    description: 'sqrt(x) Newton iteration using fixed-point int32 arithmetic (×10000 scale)',
+    params: [
+        { name: 'N', range: [4, 12], integer: true },
+        { name: 'INIT_SHIFT', range: [0, 3], integer: true },
+    ],
+    simulate(input, params) {
+        const N = Math.round(params['N']);
+        const INIT_SHIFT = Math.round(params['INIT_SHIFT']);
+        let x = (0, simulator_1.i32)(input);
+        if (x <= 0)
+            return 0;
+        // Initial guess: x >> INIT_SHIFT
+        let g = (0, simulator_1.i32)(x >> INIT_SHIFT);
+        if (g <= 0)
+            g = 1; // guard against zero/negative guess
+        // Newton iterations: g = (g + x * 10000 / g) / 2
+        // Overflow-safe for x ≤ 1_000_000: split x*10000/g as (x*100)/(g/100)
+        for (let iter = 0; iter < N; iter++) {
+            const gDiv = (0, simulator_1.i32)(g / 100);
+            if (gDiv <= 0)
+                break; // guard: g is too small, stop
+            const xdivg = (0, simulator_1.i32)((0, simulator_1.i32)(x * 100) / gDiv); // ≈ x * 10000 / g
+            g = (0, simulator_1.i32)((0, simulator_1.i32)(g + xdivg) / 2);
+            if (g <= 0) {
+                g = 1;
+                break;
+            }
+        }
+        return g;
+    },
+    reference(input) {
+        if (input <= 0)
+            return 0;
+        return Math.floor(Math.sqrt(input / SCALE) * SCALE);
+    },
+    sampleInputs() {
+        const inputs = [];
+        // Logarithmic sampling from 0.01 to 100.0 (×10000: 100 to 1_000_000)
+        // Lower bound 100 avoids g/100=0 in overflow-safe Newton step.
+        const logMin = Math.log10(100);
+        const logMax = Math.log10(1_000_000);
+        const steps = 200;
+        for (let i = 0; i <= steps; i++) {
+            const v = logMin + (i / steps) * (logMax - logMin);
+            const x = Math.round(Math.pow(10, v));
+            inputs.push(x);
+        }
+        // Exact perfect squares (k=1..10 → x up to 100 * 10000 = 1_000_000)
+        for (let k = 1; k <= 10; k++) {
+            inputs.push(k * k * SCALE); // sqrt should be exactly k * SCALE
+        }
+        return inputs;
+    },
+    generateCode(params, meta) {
+        const N = Math.round(params['N']);
+        const INIT_SHIFT = Math.round(params['INIT_SHIFT']);
+        const iters = Array.from({ length: N }, (_, i) => `    g = (g + x * 100 / (g / 100)) / 2;  // iteration ${i + 1}`).join('\n');
+        return `// AUTO-GENERATED by redscript tune — DO NOT EDIT
+// Adapter: sqrt-newton | Date: ${meta.tuneDate}
+// max_error: ${meta.maxError.toFixed(6)} | mae: ${meta.mae.toFixed(6)} | estimated_cmds: ${meta.estimatedCmds}
+// Run \`redscript tune --adapter sqrt-newton\` to regenerate
+//
+// Parameters:
+//   N          = ${N}   (Newton iteration count)
+//   INIT_SHIFT = ${INIT_SHIFT}   (initial guess = x >> ${INIT_SHIFT}, i.e. x / ${1 << INIT_SHIFT})
+
+fn sqrt_fx(x: int): int {
+    // Input x: fixed-point ×10000, returns floor(sqrt(x/10000)*10000)
+    // Valid range: x ∈ [0, 1000000]  (real range 0.0 to 100.0)
+    // max_error: ${meta.maxError.toFixed(6)} (in ×10000 units)
+    //
+    // Overflow-safe: x*10000/g computed as (x*100)/(g/100), valid for x ≤ 1_000_000
+
+    if (x <= 0) { return 0; }
+
+    // Initial guess: x / ${1 << INIT_SHIFT}
+    let g: int = x / ${1 << INIT_SHIFT};
+    if (g <= 0) { g = 1; }
+
+    // Newton iterations: g = (g + x * 10000 / g) / 2
+    // Split to avoid overflow: (x * 100) / (g / 100) ≈ x * 10000 / g
+${iters}
+
+    return g;
+}
+`;
+    },
+};
+//# sourceMappingURL=sqrt-newton.js.map

package/dist/src/tuner/cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CLI entry point for `redscript tune`.
+ * Usage: redscript tune --adapter <name> [--budget N] [--out path]
+ */
+export {};

package/dist/src/tuner/cli.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * CLI entry point for `redscript tune`.
+ * Usage: redscript tune --adapter <name> [--budget N] [--out path]
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_1 = require("./engine");
+const ln_polynomial_1 = require("./adapters/ln-polynomial");
+const sqrt_newton_1 = require("./adapters/sqrt-newton");
+const ADAPTERS = {
+    'ln-polynomial': ln_polynomial_1.lnPolynomialAdapter,
+    'sqrt-newton': sqrt_newton_1.sqrtNewtonAdapter,
+};
+function printUsage() {
+    console.log(`Usage: redscript tune --adapter <name> [--budget N] [--out path]
+
+Available adapters:
+${Object.entries(ADAPTERS)
+        .map(([name, a]) => `  ${name.padEnd(20)} ${a.description}`)
+        .join('\n')}
+
+Options:
+  --adapter <name>   Adapter to use (required)
+  --budget <N>       Max optimizer iterations (default: 10000)
+  --out <path>       Output .mcrs file path (optional)
+`);
+}
+function parseArgs(args) {
+    const result = { budget: 10000, strategy: 'nm' };
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--adapter' && args[i + 1]) {
+            result.adapter = args[++i];
+        }
+        else if (args[i] === '--budget' && args[i + 1]) {
+            result.budget = parseInt(args[++i], 10);
+        }
+        else if (args[i] === '--out' && args[i + 1]) {
+            result.out = args[++i];
+        }
+        else if (args[i] === '--strategy' && args[i + 1]) {
+            const s = args[++i];
+            if (s === 'nm' || s === 'sa')
+                result.strategy = s;
+        }
+    }
+    return result;
+}
+function renderProgressBar(fraction, width = 30) {
+    const filled = Math.round(fraction * width);
+    const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+    return `[${bar}]`;
+}
+async function main() {
+    // Skip 'node', 'ts-node', 'cli.ts' etc from argv
+    const rawArgs = process.argv.slice(2);
+    // Support `redscript tune` prefix (first arg might be 'tune')
+    const args = rawArgs[0] === 'tune' ? rawArgs.slice(1) : rawArgs;
+    if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+        printUsage();
+        process.exit(0);
+    }
+    const { adapter: adapterName, budget, out, strategy } = parseArgs(args);
+    if (!adapterName) {
+        console.error('Error: --adapter is required');
+        printUsage();
+        process.exit(1);
+    }
+    const adapter = ADAPTERS[adapterName];
+    if (!adapter) {
+        console.error(`Error: unknown adapter "${adapterName}"`);
+        console.error(`Available: ${Object.keys(ADAPTERS).join(', ')}`);
+        process.exit(1);
+    }
+    console.log(`\nredscript tune — ${adapter.name}`);
+    console.log(`Description: ${adapter.description}`);
+    console.log(`Strategy: ${strategy === 'sa' ? 'Simulated Annealing' : 'Nelder-Mead'}`);
+    console.log(`Budget: ${budget} iterations`);
+    console.log(`Parameters: ${adapter.params.map(p => p.name).join(', ')}\n`);
+    let lastProgress = 0;
+    const startTime = Date.now();
+    const searchFn = strategy === 'sa' ? engine_1.searchSA : engine_1.search;
+    const result = searchFn(adapter, budget, (iteration, bestError) => {
+        const fraction = iteration / budget;
+        const bar = renderProgressBar(fraction);
+        const errorStr = isFinite(bestError) ? bestError.toFixed(6) : 'Inf';
+        process.stdout.write(`\r  ${bar} ${(fraction * 100).toFixed(1)}%  iter=${iteration}  best_max_error=${errorStr}   `);
+        lastProgress = iteration;
+    });
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    process.stdout.write('\n');
+    console.log(`\n${'─'.repeat(60)}`);
+    console.log(`Optimization complete in ${elapsed}s`);
+    console.log(`Budget used: ${result.budgetUsed}/${budget} iterations`);
+    console.log(`\nResults:`);
+    console.log(`  max_error : ${result.maxError.toFixed(8)}`);
+    console.log(`  mae       : ${result.mae.toFixed(8)}`);
+    console.log(`  rmse      : ${result.rmse.toFixed(8)}`);
+    console.log(`\nBest parameters:`);
+    for (const [k, v] of Object.entries(result.params)) {
+        console.log(`  ${k.padEnd(12)} = ${v}`);
+    }
+    // Estimate command count (rough: ~4 cmds per param + 10 overhead)
+    const estimatedCmds = adapter.params.length * 4 + 15;
+    const meta = {
+        maxError: result.maxError,
+        mae: result.mae,
+        rmse: result.rmse,
+        estimatedCmds,
+        tuneDate: new Date().toISOString().split('T')[0],
+        budgetUsed: result.budgetUsed,
+    };
+    const code = adapter.generateCode(result.params, meta);
+    if (out) {
+        const outPath = path.resolve(out);
+        const dir = path.dirname(outPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(outPath, code, 'utf8');
+        console.log(`\nWrote: ${outPath}`);
+    }
+    else {
+        console.log(`\n${'─'.repeat(60)}`);
+        console.log('Generated code:');
+        console.log('─'.repeat(60));
+        console.log(code);
+    }
+}
+main().catch(err => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/tuner/engine.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Nelder-Mead simplex optimization engine for hyperparameter tuning.
+ * Suitable for continuous parameter spaces without gradient information.
+ * Supports mixed-integer parameters.
+ */
+import { TunerAdapter, SearchResult } from './types';
+export type ProgressCallback = (iteration: number, bestError: number) => void;
+/**
+ * Run Nelder-Mead optimization.
+ */
+export declare function search(adapter: TunerAdapter, budget?: number, onProgress?: ProgressCallback): SearchResult;
+/**
+ * Simulated Annealing search strategy.
+ * More robust than Nelder-Mead for integer parameters and multimodal objectives.
+ * Uses 3 independent restarts, taking the global best.
+ */
+export declare function searchSA(adapter: TunerAdapter, budget: number, onProgress?: ProgressCallback): SearchResult;