redscript-mc 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to RedScript will be documented in this file.
 
+## [2.3.0] - 2026-03-17
+
+### Added
+- `stdlib/math.mcrs`: `ln` (SA-tuned atanh series, max_error < 0.0006), `sqrt_fx` (×10000 scale), `exp_fx` (Horner Taylor + 2^k scaling)
+- `stdlib/math_hp.mcrs`: `sin_hp`/`cos_hp` using MC entity rotation trick (double precision), `init_trig()` bootstrap
+- `stdlib/random.mcrs`: LCG (`next_lcg`, `random_range`, `random_bool`) + PCG (`pcg_next_lo/hi`, `pcg_output`)
+- `stdlib/color.mcrs`: RGB packing/unpacking, `rgb_lerp`, HSL↔RGB conversion (`hsl_to_r/g/b`, `rgb_to_h/s/l`)
+- `stdlib/bits.mcrs`: bitwise AND/OR/XOR/NOT, left/right shift, bit get/set/clear/toggle, popcount (all integer-simulated)
+- `stdlib/list.mcrs`: `sort3`, min/max/avg for 3 and 5 values, weighted choice utilities
+- `stdlib/geometry.mcrs`: AABB/sphere/cylinder contains checks, parabola physics, grid/tile helpers, angle normalization, MC sun angle
+- `stdlib/signal.mcrs`: uniform, normal (12-sample approximation), exponential distribution, bernoulli trial, weighted2/3 choice
+- `stdlib/bigint.mcrs`: 96-bit base-10000 arithmetic (add, sub, mul, div, cmp, int32↔bigint3 conversion)
+- `src/tuner/`: hyperparameter search framework (Nelder-Mead + Simulated Annealing) for stdlib coefficient optimization
+  - `adapters/ln-polynomial.ts`: atanh series adapter
+  - `adapters/sqrt-newton.ts`: Newton iteration adapter
+  - CLI: `redscript tune --adapter <name> [--strategy nm|sa] [--budget N] [--out path]`
+
+### Changed
+- `stdlib/vec.mcrs`: added 2D/3D add/sub/scale/neg component helpers
+
 ## [2.1.1] - 2026-03-16
 
 ### Added

package/README.md

@@ -306,8 +306,16 @@ redscript validate <file>      Validate MC commands
 RedScript ships a built-in standard library. Use the short form — no path needed:
 
 ```rs
-import "stdlib/math"      // fixed-point math
-import "stdlib/vec"       // 2D/3D vector geometry
+import "stdlib/math"      // fixed-point math: ln, sqrt_fx, exp_fx, sin_fixed, cos_fixed...
+import "stdlib/math_hp"   // high-precision trig via entity rotation (init_trig required)
+import "stdlib/vec"       // 2D/3D vector: dot, cross, length, distance, atan2, rotate...
+import "stdlib/random"    // LCG & PCG random number generators
+import "stdlib/color"     // RGB/HSL color packing, blending, conversion
+import "stdlib/bits"      // bitwise AND/OR/XOR/NOT/shift/popcount (integer-simulated)
+import "stdlib/list"      // sort3, min/max/avg, weighted utilities
+import "stdlib/geometry"  // AABB/sphere contains, parabola physics, angle helpers
+import "stdlib/signal"    // normal/exponential distributions, bernoulli, weighted choice
+import "stdlib/bigint"    // 96-bit base-10000 arithmetic (add/sub/mul/div/cmp)
 import "stdlib/combat"    // damage, kill-check helpers
 import "stdlib/player"    // health, alive check, range
 import "stdlib/cooldown"  // per-player cooldown tracking
@@ -319,6 +327,8 @@ Custom library paths can be added with `--include <dir>` so your own modules wor
 
 All stdlib files use `module library;` — only the functions you actually call are compiled in.
 
+> Parts of the standard library are inspired by [kaer-3058/large_number](https://github.com/kaer-3058/large_number), a comprehensive math library for Minecraft datapacks.
+
 ```rs
 import "stdlib/math"            // abs, sign, min, max, clamp, lerp, isqrt, sqrt_fixed,
                                 // pow_int, gcd, lcm, sin_fixed, cos_fixed, map, ceil_div,
@@ -444,6 +454,12 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full release notes.
 
 ---
 
+## Acknowledgements
+
+Parts of the standard library are inspired by [kaer-3058/large_number](https://github.com/kaer-3058/large_number), a comprehensive math library for Minecraft datapacks. RedScript provides a higher-level, type-safe API over similar algorithms.
+
+---
+
 <div align="center">
 
 MIT License · Copyright © 2026 [bkmashiro](https://github.com/bkmashiro)

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for the redscript tuner engine, simulator, and ln-polynomial adapter.
+ */
+export {};

package/dist/src/__tests__/tuner/engine.test.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Tests for the redscript tuner engine, simulator, and ln-polynomial adapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const engine_1 = require("../../tuner/engine");
+const simulator_1 = require("../../tuner/simulator");
+const metrics_1 = require("../../tuner/metrics");
+const ln_polynomial_1 = require("../../tuner/adapters/ln-polynomial");
+const sqrt_newton_1 = require("../../tuner/adapters/sqrt-newton");
+// ─── simulator tests ──────────────────────────────────────────────────────────
+describe('simulator', () => {
+    test('i32 truncates to int32', () => {
+        expect((0, simulator_1.i32)(3.7)).toBe(3);
+        expect((0, simulator_1.i32)(-3.7)).toBe(-3);
+        expect((0, simulator_1.i32)(2147483648)).toBe(-2147483648); // overflow wraps
+        expect((0, simulator_1.i32)(0)).toBe(0);
+    });
+    test('fixedMul basic', () => {
+        // 10000 * 10000 / 10000 = 10000
+        expect((0, simulator_1.fixedMul)(10000, 10000, 10000)).toBe(10000);
+        // 5000 * 2 / 10000 = 1
+        expect((0, simulator_1.fixedMul)(5000, 2, 10000)).toBe(1);
+    });
+    test('fixedMul returns Infinity on overflow', () => {
+        expect((0, simulator_1.fixedMul)(2147483647, 2147483647, 1)).toBe(Infinity);
+    });
+    test('isOverflow detects out-of-range', () => {
+        expect((0, simulator_1.isOverflow)(2147483648)).toBe(true);
+        expect((0, simulator_1.isOverflow)(-2147483649)).toBe(true);
+        expect((0, simulator_1.isOverflow)(Infinity)).toBe(true);
+        expect((0, simulator_1.isOverflow)(NaN)).toBe(true);
+        expect((0, simulator_1.isOverflow)(0)).toBe(false);
+        expect((0, simulator_1.isOverflow)(2147483647)).toBe(false);
+    });
+});
+// ─── Nelder-Mead convergence test ────────────────────────────────────────────
+describe('Nelder-Mead engine', () => {
+    test('converges to minimum of (x-3)^2', () => {
+        // Simple 1D minimization: minimize (x-3)^2
+        const mockAdapter = {
+            name: 'test-quadratic',
+            description: 'Minimize (x-3)^2',
+            params: [
+                { name: 'x', range: [-10, 10], integer: false },
+            ],
+            simulate(input, params) {
+                // Return the residual as a scaled integer
+                const x = params['x'];
+                return Math.round(x * 10000);
+            },
+            reference(_input) {
+                // Target: x = 3 → value 30000
+                return 30000;
+            },
+            sampleInputs() {
+                return [1]; // single input, target value is 3.0 (×10000 = 30000)
+            },
+            generateCode(params) {
+                return `// x = ${params['x']}`;
+            },
+        };
+        const result = (0, engine_1.search)(mockAdapter, 5000);
+        // Should converge close to x=3
+        expect(result.params['x']).toBeCloseTo(3.0, 1);
+        expect(result.maxError).toBeLessThan(0.1);
+    });
+    test('handles integer constraints', () => {
+        const mockAdapter = {
+            name: 'test-integer',
+            description: 'Integer parameter test',
+            params: [
+                { name: 'n', range: [0, 10], integer: true },
+            ],
+            simulate(input, params) {
+                // Should snap to integer 7
+                return Math.round(params['n'] * 10000);
+            },
+            reference(_input) {
+                return 70000; // 7.0 × 10000
+            },
+            sampleInputs() {
+                return [1];
+            },
+            generateCode() {
+                return '';
+            },
+        };
+        const result = (0, engine_1.search)(mockAdapter, 2000);
+        // Should find n close to 7
+        expect(Math.round(result.params['n'])).toBe(7);
+    });
+    test('i32 overflow penalization', () => {
+        const mockAdapter = {
+            name: 'test-overflow',
+            description: 'Test overflow penalization',
+            params: [
+                { name: 'scale', range: [1, 1000], integer: true },
+            ],
+            simulate(_input, params) {
+                // Always overflow for any scale >= 500
+                if (params['scale'] >= 500)
+                    return Infinity;
+                return params['scale'] * 10000;
+            },
+            reference(_input) {
+                return 2000000; // target: scale=200 → 2000000
+            },
+            sampleInputs() {
+                return [1];
+            },
+            generateCode() {
+                return '';
+            },
+        };
+        const { maxError, mae, rmse } = (0, metrics_1.evaluate)(mockAdapter, { scale: 2147483647 });
+        expect(maxError).toBe(Infinity);
+        expect(mae).toBe(Infinity);
+        expect(rmse).toBe(Infinity);
+    });
+});
+// ─── ln-polynomial adapter tests ─────────────────────────────────────────────
+describe('ln-polynomial adapter', () => {
+    const defaultParams = ln_polynomial_1.defaultParams; // { A1: 20000, A3: 6667, A5: 4000 }
+    test('sample inputs cover the valid range', () => {
+        const inputs = ln_polynomial_1.lnPolynomialAdapter.sampleInputs();
+        expect(inputs.length).toBeGreaterThan(50);
+        // All inputs should be positive
+        expect(inputs.every(x => x > 0)).toBe(true);
+    });
+    test('reference matches Math.log', () => {
+        const SCALE = 10000;
+        // ln(1.0) = 0
+        expect(ln_polynomial_1.lnPolynomialAdapter.reference(SCALE)).toBeCloseTo(0, 5);
+        // ln(2.0) ≈ 0.6931 → 6931
+        expect(ln_polynomial_1.lnPolynomialAdapter.reference(2 * SCALE)).toBeCloseTo(6931.47, 0);
+        // ln(0.5) ≈ -0.6931 → -6931
+        expect(ln_polynomial_1.lnPolynomialAdapter.reference(5000)).toBeCloseTo(-6931.47, 0);
+    });
+    test('simulate produces reasonable output for x=1 (no error)', () => {
+        const result = ln_polynomial_1.lnPolynomialAdapter.simulate(10000, defaultParams);
+        // ln(1.0) = 0; allow some approximation error
+        expect(Math.abs(result)).toBeLessThan(500); // within 0.05
+    });
+    test('simulate returns Infinity for invalid input', () => {
+        const result = ln_polynomial_1.lnPolynomialAdapter.simulate(0, defaultParams);
+        expect(result).toBeLessThan(0); // negative sentinel or -MAX_INT
+    });
+    test('max_error < 0.001 with default atanh coefficients', () => {
+        const metrics = (0, metrics_1.evaluate)(ln_polynomial_1.lnPolynomialAdapter, defaultParams);
+        expect(metrics.maxError).toBeLessThan(0.001);
+    }, 10000);
+    test('search improves over default params', () => {
+        // Run a short search and confirm it doesn't get worse
+        const baseMetrics = (0, metrics_1.evaluate)(ln_polynomial_1.lnPolynomialAdapter, defaultParams);
+        const result = (0, engine_1.search)(ln_polynomial_1.lnPolynomialAdapter, 500); // short budget for test speed
+        // Either same or better
+        expect(result.maxError).toBeLessThanOrEqual(baseMetrics.maxError * 2);
+        expect(result.maxError).toBeLessThan(0.01);
+    }, 30000);
+    test('generateCode produces valid output', () => {
+        const meta = {
+            maxError: 0.00003,
+            mae: 0.000012,
+            rmse: 0.000015,
+            estimatedCmds: 38,
+            tuneDate: '2026-03-17',
+            budgetUsed: 5000,
+        };
+        const code = ln_polynomial_1.lnPolynomialAdapter.generateCode(defaultParams, meta);
+        expect(code).toContain('AUTO-GENERATED');
+        expect(code).toContain('ln-polynomial');
+        expect(code).toContain('fn ln');
+        expect(code).toContain('A1');
+        expect(code).toContain('A3');
+        expect(code).toContain('A5');
+        expect(code).toContain('2026-03-17');
+    });
+    test('searchSA achieves max_error < 0.001 on ln-polynomial', () => {
+        const result = (0, engine_1.searchSA)(ln_polynomial_1.lnPolynomialAdapter, 3000);
+        expect(result.maxError).toBeLessThan(0.001);
+    }, 30000);
+});
+// ─── sqrt-newton adapter tests ────────────────────────────────────────────────
+describe('sqrt-newton adapter', () => {
+    test('simulate(10000, defaultParams) ≈ 10000 (sqrt(1.0)=1.0)', () => {
+        const result = sqrt_newton_1.sqrtNewtonAdapter.simulate(10000, sqrt_newton_1.defaultParams);
+        // sqrt(1.0) * 10000 = 10000
+        expect(Math.abs(result - 10000)).toBeLessThan(10);
+    });
+    test('simulate(40000, defaultParams) ≈ 20000 (sqrt(4.0)=2.0)', () => {
+        const result = sqrt_newton_1.sqrtNewtonAdapter.simulate(40000, sqrt_newton_1.defaultParams);
+        // sqrt(4.0) * 10000 = 20000
+        expect(Math.abs(result - 20000)).toBeLessThan(10);
+    });
+    test('simulate(0) returns 0', () => {
+        expect(sqrt_newton_1.sqrtNewtonAdapter.simulate(0, sqrt_newton_1.defaultParams)).toBe(0);
+        expect(sqrt_newton_1.sqrtNewtonAdapter.simulate(-1, sqrt_newton_1.defaultParams)).toBe(0);
+    });
+    test('simulate(250000, defaultParams) ≈ 50000 (sqrt(25.0)=5.0)', () => {
+        const result = sqrt_newton_1.sqrtNewtonAdapter.simulate(250000, sqrt_newton_1.defaultParams);
+        expect(Math.abs(result - 50000)).toBeLessThan(10);
+    });
+    test('sample inputs are all positive', () => {
+        const inputs = sqrt_newton_1.sqrtNewtonAdapter.sampleInputs();
+        expect(inputs.length).toBeGreaterThan(50);
+        expect(inputs.every(x => x > 0)).toBe(true);
+    });
+    test('reference matches Math.sqrt', () => {
+        const SCALE = 10000;
+        expect(sqrt_newton_1.sqrtNewtonAdapter.reference(SCALE)).toBe(SCALE); // sqrt(1.0)
+        expect(sqrt_newton_1.sqrtNewtonAdapter.reference(4 * SCALE)).toBe(2 * SCALE); // sqrt(4.0)
+        expect(sqrt_newton_1.sqrtNewtonAdapter.reference(9 * SCALE)).toBe(3 * SCALE); // sqrt(9.0)
+        expect(sqrt_newton_1.sqrtNewtonAdapter.reference(0)).toBe(0);
+    });
+    test('generateCode contains fn sqrt_fx', () => {
+        const meta = {
+            maxError: 1.5,
+            mae: 0.5,
+            rmse: 0.8,
+            estimatedCmds: 30,
+            tuneDate: '2026-03-17',
+            budgetUsed: 3000,
+        };
+        const code = sqrt_newton_1.sqrtNewtonAdapter.generateCode(sqrt_newton_1.defaultParams, meta);
+        expect(code).toContain('AUTO-GENERATED');
+        expect(code).toContain('sqrt-newton');
+        expect(code).toContain('fn sqrt_fx');
+        expect(code).toContain('2026-03-17');
+    });
+});
+//# sourceMappingURL=engine.test.js.map

package/dist/src/tuner/adapters/ln-polynomial.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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
+ */
+import { TunerAdapter } from '../types';
+export declare const defaultParams: Record<string, number>;
+export declare const lnPolynomialAdapter: TunerAdapter;

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 {};