@graphty/graph-samples 0.0.1 → 0.1.1

package/src/generators/weights.ts

@@ -0,0 +1,177 @@
+/**
+ * Edge weights for any graph: the `weights` option every generator takes, and `withWeights` for a
+ * graph that already exists (a dataset, a hand-built graph).
+ */
+
+import { type TypedArrayData } from "@graphty/graph-format";
+
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+
+/** How to combine the two endpoint values of a node column into an edge weight. */
+export type ColumnCombine = "source" | "target" | "sum" | "mean" | "product" | "min" | "max" | "difference";
+
+/**
+ * A weight distribution. Random kinds draw one value per edge, in edge order, from stream
+ * (seed, "weights", 0).
+ *
+ * - `uniform`: a real in [min, max) (default [0, 1)).
+ * - `integer`: an integer in [min, max], both ends included -- capacities, Dijkstra demos.
+ * - `exponential`: -mean ln(1 - u), mean default 1.
+ * - `euclidean`: the distance between the endpoints' `x`, `y` (and `z`, when present) node columns;
+ *   for the generators that emit positions.
+ * - `column`: from a numeric node column: the source's value, the target's, their sum, mean,
+ *   product, min, max, or the absolute difference.
+ */
+export type WeightSpec =
+    | { readonly kind: "uniform"; readonly min?: number | undefined; readonly max?: number | undefined }
+    | { readonly kind: "integer"; readonly min: number; readonly max: number }
+    | { readonly kind: "exponential"; readonly mean?: number | undefined }
+    | { readonly kind: "euclidean" }
+    | { readonly kind: "column"; readonly column: string; readonly combine?: ColumnCombine | undefined };
+
+/** The options every generator accepts on top of its own. */
+export interface WeightOptions {
+    /** Give every edge a weight from this distribution; absent means unweighted. */
+    weights?: WeightSpec | undefined;
+    /**
+     * The seed of the weight draws, an integer in [0, 2^53); default 0. Random generators share it
+     * with their structure (the weights use their own stream domain, so adding weights never changes
+     * the edges).
+     */
+    seed?: number | undefined;
+}
+
+/**
+ * A numeric node column of the graph, or a RangeError naming it.
+ * @param graph - the graph
+ * @param name - the column name
+ * @returns the column's values
+ */
+function numericColumn(graph: SampleGraph, name: string): TypedArrayData {
+    const column = graph.nodeColumns?.[name];
+    if (column === undefined || !ArrayBuffer.isView(column)) {
+        throw new RangeError(`weights: the graph has no numeric node column "${name}"`);
+    }
+    return column;
+}
+
+/**
+ * The weight of every edge under `spec`.
+ * @param graph - the graph
+ * @param spec - the distribution
+ * @param seed - the seed (already resolved)
+ * @returns one weight per edge
+ */
+function drawWeights(graph: SampleGraph, spec: WeightSpec, seed: number): Float32Array<ArrayBuffer> {
+    const m = graph.src.length;
+    const out = new Float32Array(m);
+    const { src, dst } = graph;
+    const stream = new RandomStream(seed, "weights", 0);
+    switch (spec.kind) {
+        case "uniform": {
+            const min = spec.min ?? 0;
+            const max = spec.max ?? 1;
+            if (!(Number.isFinite(min) && Number.isFinite(max) && min <= max)) {
+                throw new RangeError(`weights: uniform needs finite min <= max, got ${min} and ${max}`);
+            }
+            for (let e = 0; e < m; e++) {
+                out[e] = min + (max - min) * stream.nextFloat();
+            }
+            break;
+        }
+        case "integer": {
+            const { min, max } = spec;
+            if (!(Number.isSafeInteger(min) && Number.isSafeInteger(max) && min <= max)) {
+                throw new RangeError(`weights: integer needs integers min <= max, got ${min} and ${max}`);
+            }
+            for (let e = 0; e < m; e++) {
+                out[e] = min + stream.nextBelow(max - min + 1);
+            }
+            break;
+        }
+        case "exponential": {
+            const mean = spec.mean ?? 1;
+            if (!(mean > 0 && Number.isFinite(mean))) {
+                throw new RangeError(`weights: exponential needs a positive mean, got ${mean}`);
+            }
+            for (let e = 0; e < m; e++) {
+                out[e] = -mean * detLog(1 - stream.nextFloat());
+            }
+            break;
+        }
+        case "euclidean": {
+            const x = numericColumn(graph, "x");
+            const y = numericColumn(graph, "y");
+            const z = graph.nodeColumns?.z === undefined ? null : numericColumn(graph, "z");
+            for (let e = 0; e < m; e++) {
+                const dx = x[src[e]] - x[dst[e]];
+                const dy = y[src[e]] - y[dst[e]];
+                const dz = z === null ? 0 : z[src[e]] - z[dst[e]];
+                out[e] = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            }
+            break;
+        }
+        default: {
+            const values = numericColumn(graph, spec.column);
+            const combine = spec.combine ?? "sum";
+            for (let e = 0; e < m; e++) {
+                const a = values[src[e]];
+                const b = values[dst[e]];
+                out[e] = combineValues(combine, a, b);
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Combine two endpoint values.
+ * @param combine - the rule
+ * @param a - the source value
+ * @param b - the target value
+ * @returns the weight
+ */
+function combineValues(combine: ColumnCombine, a: number, b: number): number {
+    switch (combine) {
+        case "source":
+            return a;
+        case "target":
+            return b;
+        case "sum":
+            return a + b;
+        case "mean":
+            return (a + b) / 2;
+        case "product":
+            return a * b;
+        case "min":
+            return Math.min(a, b);
+        case "max":
+            return Math.max(a, b);
+        default:
+            return Math.abs(a - b);
+    }
+}
+
+/**
+ * A copy of `graph` (sharing its arrays) with edge weights drawn from `spec`. Any graph works: a
+ * generator's output, a dataset, a hand-built SampleGraph. Existing weights are replaced.
+ * @param graph - the graph
+ * @param spec - the distribution
+ * @param seed - the seed of the draws, default 0
+ * @returns the weighted graph
+ */
+export function withWeights(graph: SampleGraph, spec: WeightSpec, seed?: number): SampleGraph {
+    return { ...graph, weights: drawWeights(graph, spec, resolveSeed(seed)) };
+}
+
+/**
+ * Apply the common `weights` option, if set: the last step of every generator.
+ * @param graph - the generated graph
+ * @param options - the generator's options
+ * @returns the graph, weighted when asked
+ */
+export function applyWeights(graph: SampleGraph, options: WeightOptions): SampleGraph {
+    return options.weights === undefined ? graph : withWeights(graph, options.weights, options.seed);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@graphty/graph-samples`: the shared types, the dataset catalogue, the loader for hosted
+ * datasets and the conversion to graphty-element records. The generators live in
+ * `@graphty/graph-samples/generators` and each bundled dataset in
+ * `@graphty/graph-samples/datasets/<name>`, so an application bundles only what it imports.
+ */
+
+export { type DatasetMeta } from "./datasets/build.js";
+export { DATASETS } from "./datasets/catalog.js";
+export { DEFAULT_DATASET_BASE_URL, fetchDataset, type FetchDatasetOptions } from "./datasets/remote.js";
+export { type ElementData, toElementData } from "./element.js";
+export { type SampleGraph } from "./types.js";

package/src/random/exp.ts

@@ -0,0 +1,104 @@
+/**
+ * An exponential and the power functions built on it, returning the same bits on every JavaScript
+ * engine: a port of fdlibm's `__ieee754_exp` (e_exp.c, Sun Microsystems 1993), for the same reason
+ * and with the same technique as `detLog` in log.ts -- the exponent is read and written through a
+ * little-endian DataView and everything else is IEEE-754 double addition, subtraction,
+ * multiplication and division, which ECMAScript requires to be correctly rounded. Error below 1 ulp.
+ */
+
+import { detLog } from "./log.js";
+
+const O_THRESHOLD = 7.09782712893383973096e2;
+const U_THRESHOLD = -7.45133219101941108420e2;
+const LN2_HI = 6.93147180369123816490e-1;
+const LN2_LO = 1.90821492927058770002e-10;
+const INV_LN2 = 1.44269504088896338700;
+const TWOM1000 = 9.33263618503218878990e-302;
+const P1 = 1.66666666666666019037e-1;
+const P2 = -2.77777777770155933842e-3;
+const P3 = 6.61375632143793436117e-5;
+const P4 = -1.65339022054652515390e-6;
+const P5 = 4.13813679705723846039e-8;
+
+const view = new DataView(new ArrayBuffer(8));
+
+/**
+ * `y * 2^k` for a y in [0.5, 2) and k >= -1021, by adding k to the exponent field.
+ * @param y - the mantissa part
+ * @param k - the power of two
+ * @returns the scaled value
+ */
+function scale(y: number, k: number): number {
+    view.setFloat64(0, y, true);
+    view.setInt32(4, view.getInt32(4, true) + (k << 20), true);
+    return view.getFloat64(0, true);
+}
+
+/**
+ * e^x, bit-identical across engines.
+ * @param x - the argument
+ * @returns e^x; +Infinity above about 709.78, 0 below about -745.13, NaN for NaN
+ */
+export function detExp(x: number): number {
+    view.setFloat64(0, x, true);
+    const high = view.getInt32(4, true);
+    const negative = high < 0 ? 1 : 0;
+    const hx = high & 0x7fffffff;
+    if (hx >= 0x40862e42) {
+        if (hx >= 0x7ff00000) {
+            // NaN stays NaN, +Infinity stays, -Infinity gives 0
+            return negative === 0 || Number.isNaN(x) ? x + x : 0;
+        }
+        if (x > O_THRESHOLD) {
+            return Infinity;
+        }
+        if (x < U_THRESHOLD) {
+            return 0;
+        }
+    }
+    let hi = 0;
+    let lo = 0;
+    let k = 0;
+    let r = x;
+    if (hx > 0x3fd62e42) {
+        // |x| > 0.5 ln 2: reduce to r = x - k ln 2
+        if (hx < 0x3ff0a2b2) {
+            hi = negative === 0 ? x - LN2_HI : x + LN2_HI;
+            lo = negative === 0 ? LN2_LO : -LN2_LO;
+            k = 1 - negative - negative;
+        } else {
+            k = Math.trunc(INV_LN2 * x + (negative === 0 ? 0.5 : -0.5));
+            hi = x - k * LN2_HI;
+            lo = k * LN2_LO;
+        }
+        r = hi - lo;
+    } else if (hx < 0x3e300000) {
+        // |x| < 2^-28
+        return 1 + x;
+    }
+    const t = r * r;
+    const c = r - t * (P1 + t * (P2 + t * (P3 + t * (P4 + t * P5))));
+    if (k === 0) {
+        return 1 - ((r * c) / (c - 2.0) - r);
+    }
+    const y = 1 - (lo - (r * c) / (2.0 - c) - hi);
+    return k >= -1021 ? scale(y, k) : scale(y, k + 1000) * TWOM1000;
+}
+
+/**
+ * x^y as `detExp(y * detLog(x))` for x > 0: deterministic, not correctly rounded (the relative
+ * error grows with |y ln x|, about 1e-13 for the magnitudes the generators use). 0^y is 0 for
+ * y > 0.
+ * @param x - the base, >= 0
+ * @param y - the exponent
+ * @returns x^y
+ */
+export function detPow(x: number, y: number): number {
+    if (x === 0) {
+        if (y === 0) {
+            return 1;
+        }
+        return y > 0 ? 0 : Infinity;
+    }
+    return detExp(y * detLog(x));
+}

package/src/random/log.ts

@@ -0,0 +1,86 @@
+/**
+ * A natural logarithm that returns the same bits on every JavaScript engine.
+ *
+ * ECMAScript leaves `Math.log` "implementation-approximated", so two engines may differ in the
+ * last bit, and a geometric skip `floor(log(u) / log(1 - p))` that lands on an integer boundary
+ * would then pick a different edge. This is a port of fdlibm's `__ieee754_log` (e_log.c, Sun
+ * Microsystems 1993, the code V8 and SpiderMonkey themselves use): it reads the exponent and
+ * mantissa through a little-endian DataView and otherwise uses only IEEE-754 double addition,
+ * subtraction, multiplication and division, which ECMAScript requires to be correctly rounded
+ * (and forbids from being fused). So the result is a pure function of the input bits.
+ * Error below 1 ulp.
+ */
+
+const LN2_HI = 6.9314718036912381649e-1; // 3fe62e42 fee00000
+const LN2_LO = 1.90821492927058770002e-10; // 3dea39ef 35793c76
+const TWO54 = 1.8014398509481984e16; // 43500000 00000000
+const LG1 = 6.66666666666673513e-1; // 3FE55555 55555593
+const LG2 = 3.999999999940941908e-1; // 3FD99999 9997FA04
+const LG3 = 2.857142874366239149e-1; // 3FD24924 94229359
+const LG4 = 2.222219843214978396e-1; // 3FCC71C5 1D8E78AF
+const LG5 = 1.818357216161805012e-1; // 3FC74664 96CB03DE
+const LG6 = 1.531383769920937332e-1; // 3FC39A09 D078C69F
+const LG7 = 1.479819860511658591e-1; // 3FC2F112 DF3E5244
+
+const view = new DataView(new ArrayBuffer(8));
+
+/**
+ * The natural logarithm of `x`, bit-identical across engines.
+ * @param input - the argument
+ * @returns ln(input); -Infinity for 0, NaN for negative input or NaN
+ */
+export function detLog(input: number): number {
+    let x = input;
+    view.setFloat64(0, x, true);
+    let hx = view.getInt32(4, true);
+    const lx = view.getUint32(0, true);
+
+    let k = 0;
+    if (hx < 0x00100000) {
+        if (((hx & 0x7fffffff) | lx) === 0) {
+            return -Infinity;
+        }
+        if (hx < 0) {
+            return NaN;
+        }
+        // subnormal: scale up
+        k -= 54;
+        x *= TWO54;
+        view.setFloat64(0, x, true);
+        hx = view.getInt32(4, true);
+    }
+    if (hx >= 0x7ff00000) {
+        return x + x;
+    }
+    k += (hx >> 20) - 1023;
+    hx &= 0x000fffff;
+    const i0 = (hx + 0x95f64) & 0x100000;
+    // normalize x or x/2
+    view.setInt32(4, hx | (i0 ^ 0x3ff00000), true);
+    x = view.getFloat64(0, true);
+    k += i0 >> 20;
+    const f = x - 1.0;
+    if ((0x000fffff & (2 + hx)) < 3) {
+        // |f| < 2**-20
+        if (f === 0) {
+            return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
+        }
+        const r = f * f * (0.5 - 0.3333333333333333 * f);
+        return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
+    }
+    const s = f / (2.0 + f);
+    const dk = k;
+    const z = s * s;
+    let i = hx - 0x6147a;
+    const w = z * z;
+    const j = 0x6b851 - hx;
+    const t1 = w * (LG2 + w * (LG4 + w * LG6));
+    const t2 = z * (LG1 + w * (LG3 + w * (LG5 + w * LG7)));
+    i |= j;
+    const R = t2 + t1;
+    if (i > 0) {
+        const hfsq = 0.5 * f * f;
+        return k === 0 ? f - (hfsq - s * (hfsq + R)) : dk * LN2_HI - (hfsq - (s * (hfsq + R) + dk * LN2_LO) - f);
+    }
+    return k === 0 ? f - s * (f - R) : dk * LN2_HI - (s * (f - R) - dk * LN2_LO - f);
+}

package/src/random/stream.ts

@@ -0,0 +1,169 @@
+/**
+ * The one random number source of @graphty/graph-samples, and its determinism contract.
+ *
+ * A stream is named by `(seed, domain, block)`:
+ *
+ * - `seed` is the caller's seed, any safe integer in [0, 2^53).
+ * - `domain` is a fixed ASCII name per generator and purpose ("gnp", "sbm", ...). It is hashed
+ *   with 32-bit FNV-1a to `domainId`.
+ * - `block` is a unit of work the ALGORITHM defines (a row of the adjacency matrix, a node), an
+ *   integer in [0, 2^32). It never depends on how many workers or chunks run the generator.
+ *
+ * The stream's key is `Threefry2x32-20(key = (seed mod 2^32, floor(seed / 2^32)),
+ * counter = (domainId, block))`, and its words are `Threefry2x32-20(key = streamKey,
+ * counter = (i mod 2^32, floor(i / 2^32)))` for i = 0, 1, 2, ..., two words per counter, word 0
+ * first. Every draw below is defined in terms of those words with integer-exact arithmetic, so the
+ * same `(seed, domain, block)` yields the same values on every engine, platform and version.
+ * `test/random/stream.test.ts` freezes it with golden values: changing anything here changes every
+ * seeded graph, which is a breaking change of the package.
+ */
+
+import { detLog } from "./log.js";
+import { threefry2x32 } from "./threefry.js";
+
+const TWO_32 = 4294967296;
+const TWO_53 = 9007199254740992;
+
+/**
+ * 32-bit FNV-1a over the UTF-16 code units of `name` (the names are ASCII, so this is the bytes).
+ * @param name - the domain name
+ * @returns the unsigned 32-bit hash
+ */
+export function domainId(name: string): number {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < name.length; i++) {
+        h ^= name.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+
+/**
+ * The seed every random generator uses when the caller gives none: 0. A fixed default, never the
+ * clock, so an unseeded call is as reproducible as a seeded one. Frozen with the rest of the
+ * contract: changing it changes every unseeded graph.
+ */
+export const DEFAULT_SEED = 0;
+
+/**
+ * The caller's seed, or {@link DEFAULT_SEED} when it is undefined; throws on an invalid seed.
+ * @param seed - the seed option
+ * @returns the seed to use
+ */
+export function resolveSeed(seed: number | undefined): number {
+    const resolved = seed ?? DEFAULT_SEED;
+    checkSeed(resolved);
+    return resolved;
+}
+
+/**
+ * Throw unless `seed` is a safe non-negative integer.
+ * @param seed - the seed
+ */
+export function checkSeed(seed: number): void {
+    if (!Number.isSafeInteger(seed) || seed < 0) {
+        throw new RangeError(`seed must be an integer in [0, 2^53), got ${String(seed)}`);
+    }
+}
+
+/** A deterministic stream of random words keyed by (seed, domain, block). */
+export class RandomStream {
+    private readonly seedLo: number;
+    private readonly seedHi: number;
+    private readonly domain: number;
+    private readonly key = new Uint32Array(2);
+    private readonly out = new Uint32Array(2);
+    private counter = 0;
+    private spare = -1;
+
+    /**
+     * The stream of one block.
+     * @param seed - the caller's seed, an integer in [0, 2^53)
+     * @param domain - the generator's fixed domain name
+     * @param block - the first block, an integer in [0, 2^32)
+     */
+    constructor(seed: number, domain: string, block: number) {
+        checkSeed(seed);
+        this.seedLo = seed >>> 0;
+        this.seedHi = Math.floor(seed / TWO_32);
+        this.domain = domainId(domain);
+        this.reset(block);
+    }
+
+    /**
+     * Restart the stream at the first word of another block of the same seed and domain.
+     * @param block - the block, an integer in [0, 2^32)
+     */
+    reset(block: number): void {
+        threefry2x32(this.seedLo, this.seedHi, this.domain, block >>> 0, this.key);
+        this.counter = 0;
+        this.spare = -1;
+    }
+
+    /**
+     * The next word.
+     * @returns an unsigned 32-bit integer
+     */
+    nextU32(): number {
+        if (this.spare >= 0) {
+            const word = this.spare;
+            this.spare = -1;
+            return word;
+        }
+        const c = this.counter++;
+        threefry2x32(this.key[0], this.key[1], c >>> 0, Math.floor(c / TWO_32), this.out);
+        this.spare = this.out[1];
+        return this.out[0];
+    }
+
+    /**
+     * A uniform double in [0, 1) with 53 random bits: (a >>> 5) * 2^26 + (b >>> 6), over 2^53,
+     * for the next two words a and b. Exact: every step is an integer below 2^53.
+     * @returns the double
+     */
+    nextFloat(): number {
+        const a = this.nextU32() >>> 5;
+        const b = this.nextU32() >>> 6;
+        return (a * 67108864 + b) / TWO_53;
+    }
+
+    /**
+     * A uniform integer in [0, n) by masked rejection: draw a word, keep its low
+     * ceil(log2 n) bits, retry while the result is >= n. Exact and unbiased; fewer than two
+     * words per call on average. For n above 2^32 the high bits come from one extra word drawn
+     * first.
+     * @param n - the bound, an integer in [1, 2^53]
+     * @returns the integer
+     */
+    nextBelow(n: number): number {
+        if (n <= TWO_32) {
+            const mask = n === 1 ? 0 : 0xffffffff >>> Math.clz32(n - 1);
+            for (;;) {
+                const x = (this.nextU32() & mask) >>> 0;
+                if (x < n) {
+                    return x;
+                }
+            }
+        }
+        const hiBound = Math.ceil(n / TWO_32);
+        const hiMask = 0xffffffff >>> Math.clz32(hiBound - 1);
+        for (;;) {
+            const hi = (this.nextU32() & hiMask) >>> 0;
+            const x = hi * TWO_32 + this.nextU32();
+            if (x < n) {
+                return x;
+            }
+        }
+    }
+
+    /**
+     * The number of failures before the next success of a Bernoulli(p) sequence, given
+     * `logQ = detLog(1 - p)` for 0 < p < 1: floor(detLog(1 - u) / logQ) for u = nextFloat().
+     * The caller handles p = 0 and p = 1 without drawing.
+     * @param logQ - detLog(1 - p), negative and finite
+     * @returns a non-negative integer (possibly above 2^53 for tiny p)
+     */
+    nextSkip(logQ: number): number {
+        return Math.floor(detLog(1 - this.nextFloat()) / logQ);
+    }
+}

package/src/random/threefry.ts

@@ -0,0 +1,45 @@
+/**
+ * Threefry-2x32 with 20 rounds: the counter-based block function of J. K. Salmon, M. A. Moraes,
+ * R. O. Dror and D. E. Shaw, "Parallel random numbers: as easy as 1, 2, 3", SC11 (2011),
+ * doi:10.1145/2063384.2063405, as specified by the Random123 library and used by JAX.
+ *
+ * It maps a 64-bit key and a 64-bit counter to 64 random bits using only 32-bit addition,
+ * rotation and xor, so JavaScript computes it exactly on every engine: no floating point, no
+ * 64-bit multiply, no BigInt. It passes BigCrush with 13 rounds; 20 is Random123's default.
+ */
+
+/** Rotation constants R_32x2 of Threefry-2x32 (Random123 threefry.h). */
+const ROTATIONS = [13, 15, 26, 6, 17, 29, 16, 24] as const;
+
+/** The Skein key-schedule parity constant for 32-bit words. */
+const KS_PARITY = 0x1bd11bda;
+
+/**
+ * Encrypt one 64-bit counter under one 64-bit key.
+ * @param k0 - key word 0 (unsigned 32-bit)
+ * @param k1 - key word 1 (unsigned 32-bit)
+ * @param c0 - counter word 0 (unsigned 32-bit)
+ * @param c1 - counter word 1 (unsigned 32-bit)
+ * @param out - receives the two output words
+ */
+export function threefry2x32(k0: number, k1: number, c0: number, c1: number, out: Uint32Array): void {
+    const ks0 = k0 >>> 0;
+    const ks1 = k1 >>> 0;
+    const ks2 = (KS_PARITY ^ ks0 ^ ks1) >>> 0;
+    const ks = [ks0, ks1, ks2];
+    let x0 = (c0 + ks0) | 0;
+    let x1 = (c1 + ks1) | 0;
+    for (let round = 0; round < 20; round++) {
+        x0 = (x0 + x1) | 0;
+        const r = ROTATIONS[round & 7];
+        x1 = (x1 << r) | (x1 >>> (32 - r));
+        x1 ^= x0;
+        if ((round & 3) === 3) {
+            const s = (round + 1) >>> 2;
+            x0 = (x0 + ks[s % 3]) | 0;
+            x1 = (x1 + ks[(s + 1) % 3] + s) | 0;
+        }
+    }
+    out[0] = x0;
+    out[1] = x1;
+}

package/src/random/trig.ts

@@ -0,0 +1,83 @@
+/**
+ * The cosine and sine of a uniformly drawn angle, the same bits on every engine.
+ *
+ * The angle is given as a turn fraction u in [0, 1) (angle 2 pi u), so the argument reduction is
+ * exact: 8u splits into an octant k and a fraction f without rounding, and only f * pi / 4 rounds
+ * once. On [0, pi / 4] the polynomials are fdlibm's `__kernel_sin` and `__kernel_cos` (FreeBSD
+ * k_sin.c and k_cos.c, Sun Microsystems 1993) with a zero tail, evaluated with the four basic
+ * operations only. Error a few ulp; bit-identical everywhere.
+ */
+
+const PIO4 = 7.85398163397448278999e-1;
+
+const S1 = -1.66666666666666324348e-1;
+const S2 = 8.33333333332248946124e-3;
+const S3 = -1.98412698298579493134e-4;
+const S4 = 2.75573137070700676789e-6;
+const S5 = -2.50507602534068634195e-8;
+const S6 = 1.58969099521155010221e-10;
+
+const C1 = 4.16666666666666019037e-2;
+const C2 = -1.38888888888741095749e-3;
+const C3 = 2.48015872894767294178e-5;
+const C4 = -2.75573143513906633035e-7;
+const C5 = 2.08757232129817482790e-9;
+const C6 = -1.13596475577881948265e-11;
+
+/**
+ * sin(x) for |x| <= pi / 4.
+ * @param x - the argument
+ * @returns the sine
+ */
+function kernelSin(x: number): number {
+    const z = x * x;
+    const r = S2 + z * (S3 + z * (S4 + z * (S5 + z * S6)));
+    return x + z * x * (S1 + z * r);
+}
+
+/**
+ * cos(x) for |x| <= pi / 4.
+ * @param x - the argument
+ * @returns the cosine
+ */
+function kernelCos(x: number): number {
+    const z = x * x;
+    const w = z * z;
+    const r = z * (C1 + z * (C2 + z * C3)) + w * w * (C4 + z * (C5 + z * C6));
+    const hz = 0.5 * z;
+    const v = 1.0 - hz;
+    return v + (1.0 - v - hz + z * r);
+}
+
+/**
+ * cos(2 pi u) and sin(2 pi u).
+ * @param u - the turn fraction, in [0, 1)
+ * @param out - receives [cos, sin]
+ */
+export function detCosSinTurn(u: number, out: Float64Array): void {
+    const t = u * 8;
+    const octant = Math.floor(t);
+    const x = (t - octant) * PIO4;
+    // the octant's angle is (octant >> 1) quarter turns plus x (even octant) or pi/2 - (pi/4 - x)
+    const odd = (octant & 1) === 1;
+    const z = odd ? PIO4 - x : x;
+    const c = odd ? kernelSin(z) : kernelCos(z);
+    const s = odd ? kernelCos(z) : kernelSin(z);
+    switch ((octant >> 1) & 3) {
+        case 0:
+            out[0] = c;
+            out[1] = s;
+            break;
+        case 1:
+            out[0] = -s;
+            out[1] = c;
+            break;
+        case 2:
+            out[0] = -c;
+            out[1] = -s;
+            break;
+        default:
+            out[0] = s;
+            out[1] = -c;
+    }
+}