@danielsimonjr/mathts-functions 0.69.1 → 0.70.0

package/dist/scalar-batch-task.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The unit of work that crosses to a scalar batch worker (M14), and the function that
+ * does it. The worker entry and the tests both call {@link runScalarBatchTask}, so the
+ * message a worker receives is evaluated by one body, on or off the main thread.
+ *
+ * @packageDocumentation
+ */
+import { type buildTape } from './scalar-compile.js';
+/** Prefix of every error the tape evaluator throws for a batch task. */
+export declare const SCALAR_BATCH_MESSAGE_PREFIX = "compileScalar:";
+type Tape = ReturnType<typeof buildTape>['tape'];
+/** One compiled tree and the parameter values it is evaluated with. */
+export interface ScalarBatchTaskItem {
+    /** Position of the tree in the caller's list; results come back under it. */
+    readonly candidateIndex: number;
+    readonly tape: Tape;
+    readonly rootReg: number;
+    readonly nRegs: number;
+    readonly params: readonly number[];
+    readonly parameters: readonly string[];
+}
+/** Several trees over the same columns; this is the message payload. */
+export interface ScalarBatchTask {
+    readonly items: readonly ScalarBatchTaskItem[];
+    readonly columns: readonly Float64Array[];
+    readonly variables: readonly string[];
+}
+export interface ScalarBatchTaskRow {
+    readonly candidateIndex: number;
+    readonly values: Float64Array;
+    readonly valid: Uint8Array;
+    readonly allValid: boolean;
+}
+export interface ScalarBatchTaskResult {
+    readonly rows: readonly ScalarBatchTaskRow[];
+}
+/** Evaluates every tree of `task` over its columns, in order. */
+export declare function runScalarBatchTask(task: ScalarBatchTask): ScalarBatchTaskResult;
+export {};
+//# sourceMappingURL=scalar-batch-task.d.ts.map

package/dist/scalar-batch-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-batch-task.d.ts","sourceRoot":"","sources":["../src/scalar-batch-task.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEzE,wEAAwE;AACxE,eAAO,MAAM,2BAA2B,mBAAmB,CAAC;AAE5D,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC9C;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,CAqB/E"}

package/dist/scalar-batch.worker.js

@@ -0,0 +1,34 @@
+import { n as runScalarBatchTask } from "./scalar-batch-task-CZd6LPg9.js";
+//#region src/scalar-batch.worker.ts
+const isNode = typeof process !== "undefined" && process.versions?.node !== void 0;
+let nodeParentPort = null;
+function sendMessage(message) {
+	if (isNode) nodeParentPort?.postMessage(message);
+	else postMessage(message);
+}
+function handleMessage(message) {
+	try {
+		const result = runScalarBatchTask(message.data);
+		sendMessage({
+			id: message.id,
+			type: "result",
+			data: result
+		});
+	} catch (error) {
+		sendMessage({
+			id: message.id,
+			type: "error",
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+if (isNode) import("worker_threads").then(({ parentPort }) => {
+	if (!parentPort) throw new Error("scalar-batch.worker: missing parentPort");
+	nodeParentPort = parentPort;
+	parentPort.on("message", handleMessage);
+});
+else addEventListener("message", (event) => {
+	handleMessage(event.data);
+});
+//#endregion
+export {};

package/dist/scalar-compile.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Batch evaluation of {@link ScalarNode} trees over `Float64Array` columns.
+ *
+ * {@link compileScalar} builds a register tape once; {@link CompiledScalar.evaluate}
+ * runs every row with a per-row validity mask aligned with {@link evaluateScalar}.
+ *
+ * @packageDocumentation
+ */
+import type { LoweredScalarFn, ScalarNode, ScalarOperator } from '@danielsimonjr/mathts-expression';
+type TapeInstr = {
+    readonly tag: 'const';
+    readonly dest: number;
+    readonly value: number;
+} | {
+    readonly tag: 'column';
+    readonly dest: number;
+    readonly index: number;
+} | {
+    readonly tag: 'param';
+    readonly dest: number;
+    readonly index: number;
+} | {
+    readonly tag: 'mov';
+    readonly dest: number;
+    readonly src: number;
+} | {
+    readonly tag: 'bin';
+    readonly dest: number;
+    readonly op: ScalarOperator;
+    readonly left: number;
+    readonly right: number;
+} | {
+    readonly tag: 'unary';
+    readonly dest: number;
+    readonly fn: LoweredScalarFn;
+    readonly arg: number;
+};
+/**
+ * Bindings for {@link compileScalar}.
+ *
+ * `variables` is the column order. `parameters` are free constants supplied
+ * to each `evaluate` call (still `symbol` nodes in the tree).
+ * `constants` are fixed numbers, for example `{ pi: Math.PI }`.
+ *
+ * A name may occur in only one of those three. Symbol lookup then follows
+ * `evaluateScalar`: parameter, else column, else constant, else a numeric
+ * literal spelling (`'2'`, `'-1'`, `'1e-3'`), else a compile-time
+ * {@link ScalarEvalError}. `pi` and `e` are not literals.
+ *
+ * The node must already be a `ScalarNode`. A formula string, a
+ * `transcendental` node, or an `abs` node is rejected; normalize with
+ * `scalar.from` first.
+ *
+ * @example
+ * ```ts
+ * import { compileScalar, scalar } from '@danielsimonjr/mathts-functions';
+ * const node = scalar.op('*', [scalar.symbol('x'), scalar.symbol('x')]);
+ * compileScalar(node, { variables: ['x'], parameters: ['a'] }).parameters; // ['a']
+ * ```
+ */
+export interface CompileScalarOptions {
+    readonly variables: readonly string[];
+    readonly parameters?: readonly string[];
+    readonly constants?: Readonly<Record<string, number>>;
+}
+/**
+ * One batch. `values[i]` equals `evaluateScalar` for that row when `valid[i]`
+ * is 1, including a stored `NaN`, `±Infinity`, or `-0` on a bare number or
+ * symbol. `values[i]` is `NaN` when `valid[i]` is 0, which is exactly when
+ * `evaluateScalar` throws. `allValid` is true when every `valid` byte is 1,
+ * including when there are zero rows.
+ *
+ * @example
+ * ```ts
+ * import { compileScalar, scalar } from '@danielsimonjr/mathts-functions';
+ * const compiled = compileScalar(scalar.call('ln', scalar.symbol('x')), { variables: ['x'] });
+ * const { values, valid } = compiled.evaluate([new Float64Array([1, -1])]);
+ * [...valid]; // [1, 0]
+ * values[1]; // NaN
+ * ```
+ */
+export interface ScalarBatchResult {
+    readonly values: Float64Array;
+    readonly valid: Uint8Array;
+    readonly allValid: boolean;
+}
+/**
+ * A compiled scalar. `variables` and `parameters` are copies made at compile time.
+ *
+ * @example
+ * ```ts
+ * import { compileScalar, scalar } from '@danielsimonjr/mathts-functions';
+ * const compiled = compileScalar(
+ *   scalar.op('*', [scalar.symbol('x'), scalar.symbol('x')]),
+ *   { variables: ['x'] }
+ * );
+ * [...compiled.evaluate([new Float64Array([2, 3])]).values]; // [4, 9]
+ * compiled.evaluateRow([2]); // 4
+ * ```
+ */
+export interface CompiledScalar {
+    readonly variables: readonly string[];
+    readonly parameters: readonly string[];
+    /**
+     * Evaluate every row. Does not throw because a row is non-finite.
+     * Throws {@link ScalarEvalError} for a column or parameter mismatch, a bad
+     * `out` length, or a non-number parameter or row binding that is not a
+     * `Float64Array` column.
+     * When `out.length ===` the row count, `values` is `out` and no second value
+     * buffer is allocated.
+     *
+     * @example
+     * ```ts
+     * import { compileScalar, scalar } from '@danielsimonjr/mathts-functions';
+     * const compiled = compileScalar(
+     *   scalar.op('*', [scalar.symbol('x'), scalar.symbol('x')]),
+     *   { variables: ['x'] }
+     * );
+     * [...compiled.evaluate([new Float64Array([2, 3])]).values].join(','); // '4,9'
+     * ```
+     */
+    evaluate(columns: readonly Float64Array[], params?: ArrayLike<number>, out?: Float64Array): ScalarBatchResult;
+    /**
+     * One row, in `variables` order. Returns the same number `evaluateScalar`
+     * would, including non-finite bare values. Throws {@link ScalarEvalError}
+     * when the row is invalid or the binding is the wrong shape.
+     *
+     * @example
+     * ```ts
+     * import { compileScalar, scalar, ScalarEvalError } from '@danielsimonjr/mathts-functions';
+     * const compiled = compileScalar(scalar.call('ln', scalar.symbol('x')), { variables: ['x'] });
+     * try {
+     *   compiled.evaluateRow([-1]);
+     * } catch (e) {
+     *   e instanceof ScalarEvalError; // true — 'compileScalar: row produced a non-finite value.'
+     * }
+     * ```
+     */
+    evaluateRow(row: ArrayLike<number>, params?: ArrayLike<number>): number;
+}
+/**
+ * Batch primal values and exact parameter gradients of a compiled scalar.
+ * `grad[r * nParams + p]` is ∂f/∂`parameters[p]` at row `r`. Uses the same
+ * register tape as {@link compileScalar} with one forward lane per parameter.
+ *
+ * @example
+ * ```ts
+ * import { compileScalarGradient, scalar } from '@danielsimonjr/mathts-functions';
+ * const node = scalar.op('+', [
+ *   scalar.op('*', [scalar.symbol('a'), scalar.symbol('x')]),
+ *   scalar.symbol('b'),
+ * ]);
+ * const g = compileScalarGradient(node, { variables: ['x'], parameters: ['a', 'b'] });
+ * const { values, grad } = g.evaluate([new Float64Array([3])], [2, -1]);
+ * values[0]; // 5
+ * [...grad]; // 3, 1 — ∂/∂a = x, ∂/∂b = 1
+ * ```
+ */
+export interface CompiledScalarGradient {
+    readonly variables: readonly string[];
+    readonly parameters: readonly string[];
+    /**
+     * Evaluate every row. Invalid rows store `NaN` in `values` and every
+     * gradient entry for that row. The mask matches {@link compileScalar} except
+     * when a consumed `^` partial is not finite (a live child lane of `0^0`, or
+     * `ln` of a negative base with a live exponent): those rows are extra-invalid.
+     * Throws {@link ScalarEvalError} for binding mismatches or bad `out` lengths.
+     *
+     * @example
+     * ```ts
+     * import { compileScalarGradient, scalar } from '@danielsimonjr/mathts-functions';
+     * const node = scalar.op('+', [
+     *   scalar.op('*', [scalar.symbol('a'), scalar.symbol('x')]),
+     *   scalar.symbol('b'),
+     * ]);
+     * const compiled = compileScalarGradient(node, {
+     *   variables: ['x'],
+     *   parameters: ['a', 'b'],
+     * });
+     * const outV = new Float64Array(1);
+     * const outG = new Float64Array(2);
+     * compiled.evaluate([new Float64Array([3])], [2, -1], { values: outV, grad: outG });
+     * outV[0]; // 5
+     * [...outG]; // 3, 1
+     * ```
+     */
+    evaluate(columns: readonly Float64Array[], params: ArrayLike<number>, out?: {
+        values?: Float64Array;
+        grad?: Float64Array;
+    }): ScalarBatchResult & {
+        readonly grad: Float64Array;
+    };
+}
+/**
+ * Run a compiled register tape over every row. Shared by {@link compileScalar} and the
+ * scalar batch worker (M14); not re-exported from the package barrel.
+ */
+export declare function evaluateScalarTape(tape: readonly TapeInstr[], rootReg: number, nRegs: number, columns: readonly Float64Array[], variables: readonly string[], params: ArrayLike<number>, parameters: readonly string[], messagePrefix: string, out?: Float64Array, scratch?: Float64Array): ScalarBatchResult;
+export declare function buildTape(node: ScalarNode, options: CompileScalarOptions, messagePrefix: string): {
+    tape: readonly TapeInstr[];
+    rootReg: number;
+    nRegs: number;
+    variables: string[];
+    parameters: string[];
+};
+export declare function compileScalar(node: ScalarNode, options: CompileScalarOptions): CompiledScalar;
+/**
+ * Compile `node` once for batch primal values and exact parameter gradients.
+ * Shares the M3 register tape; adds one forward lane per parameter via
+ * {@link DUAL_UNARY_RULES} and explicit `^` partials. Not reentrant.
+ *
+ * @example
+ * ```ts
+ * import { compileScalarGradient, scalar } from '@danielsimonjr/mathts-functions';
+ * const node = scalar.op('+', [
+ *   scalar.op('*', [scalar.symbol('a'), scalar.symbol('x')]),
+ *   scalar.symbol('b'),
+ * ]);
+ * const g = compileScalarGradient(node, { variables: ['x'], parameters: ['a', 'b'] });
+ * const { values, grad } = g.evaluate([new Float64Array([3])], [2, -1]);
+ * values[0]; // 5
+ * [...grad]; // 3, 1
+ * ```
+ */
+export declare function compileScalarGradient(node: ScalarNode, options: CompileScalarOptions): CompiledScalarGradient;
+export {};
+//# sourceMappingURL=scalar-compile.d.ts.map

package/dist/scalar-compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-compile.d.ts","sourceRoot":"","sources":["../src/scalar-compile.ts"],"names":[],"mappings":"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"}

package/dist/scalar-dimension.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SI dimension inference and parameter-dimension solving over {@link ScalarNode}.
+ *
+ * {@link inferScalarDimension} walks a scalar tree with rational exponents on the
+ * seven base dimensions. {@link solveParameterDimensions} extends that walk with
+ * linear forms and {@link rationalNullspace}.
+ *
+ * @packageDocumentation
+ */
+import type { ScalarNode } from '@danielsimonjr/mathts-expression';
+import { type SiDimensionVector } from '@danielsimonjr/mathts-core';
+/** SI dimension vector with exact {@link Fraction} exponents. */
+export type RationalDimension = SiDimensionVector;
+/** Result of {@link inferScalarDimension}. */
+export type DimensionInference = {
+    readonly ok: true;
+    readonly dimension: RationalDimension;
+} | {
+    readonly ok: false;
+    readonly violation: 'add-mismatch' | 'transcendental-arg-not-dimensionless' | 'non-literal-exponent-on-dimensional-base' | 'unknown-symbol';
+    readonly path: readonly number[];
+};
+/** Result of {@link solveParameterDimensions}. */
+export type ParameterDimensionResult = {
+    readonly solved: Readonly<Record<string, RationalDimension>>;
+} | {
+    readonly underdetermined: readonly string[];
+} | {
+    readonly inconsistent: true;
+};
+/**
+ * Infer the SI dimension of a scalar tree, or report a structural violation.
+ */
+export declare function inferScalarDimension(node: ScalarNode, dims: Readonly<Record<string, RationalDimension>>): DimensionInference;
+/**
+ * Solve unknown parameter dimensions so the tree matches a target dimension.
+ *
+ * One walk of the tree collects, for each SI component, the equations that the
+ * parameters must satisfy: both sides of a `+` or `-` agree, the argument of a
+ * transcendental call and a non-literal exponent are dimensionless, and the root
+ * equals `target`. `x + c` with a length `x` therefore solves `c` as a length,
+ * and `sin(c * t)` solves `c` as one over `t`. The seven component systems are
+ * solved exactly with {@link rationalNullspace}.
+ *
+ * The result is `solved` (every parameter has one value), `underdetermined` (the
+ * named parameters are not fixed by the equations, or one sits in an exponent,
+ * which this solver does not treat as linear), or `inconsistent` (no values can
+ * satisfy the tree, including a symbol that is neither in `dims` nor in
+ * `parameters`).
+ */
+export declare function solveParameterDimensions(node: ScalarNode, dims: Readonly<Record<string, RationalDimension>>, target: RationalDimension, parameters: readonly string[], options?: {
+    readonly dimensionlessOnly?: boolean;
+}): ParameterDimensionResult;
+//# sourceMappingURL=scalar-dimension.d.ts.map

package/dist/scalar-dimension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-dimension.d.ts","sourceRoot":"","sources":["../src/scalar-dimension.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAiC,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAInG,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAElD,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;CAAE,GAC5D;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,SAAS,EACd,cAAc,GACd,sCAAsC,GACtC,0CAA0C,GAC1C,gBAAgB,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAEN,kDAAkD;AAClD,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAA;CAAE,CAAC;AAwVpC;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,GAChD,kBAAkB,CASpB;AA2ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,EACjD,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,wBAAwB,CA+D1B"}

package/dist/scalar-eval.d.ts

@@ -27,6 +27,13 @@ export declare const scalar: import("@danielsimonjr/mathts-expression").ScalarBu
 export declare class ScalarEvalError extends Error {
     constructor(message: string);
 }
+/**
+ * Decimal spellings both evaluators bind as symbol names (`'2'`, `'1e-3'`).
+ * Hex, blank, `Infinity`, `NaN`, and underscores do not match. A match is
+ * bound only when `Number(name)` is finite (`'1e309'` matches and is rejected).
+ * Internal: not re-exported from `index.ts`.
+ */
+export declare const NUMERIC_LITERAL: RegExp;
 /**
  * Evaluate `node` with MathTS scalar functions.
  *

package/dist/scalar-eval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar-eval.d.ts","sourceRoot":"","sources":["../src/scalar-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,MAAM,0DAAwB,CAAC;AAE5C,4CAA4C;AAC5C,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAwGD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAE,WAAgB,GAAG,MAAM,CAU7E"}
+{"version":3,"file":"scalar-eval.d.ts","sourceRoot":"","sources":["../src/scalar-eval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AA0BH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE3D,wFAAwF;AACxF,eAAO,MAAM,MAAM,0DAAwB,CAAC;AAE5C,4CAA4C;AAC5C,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAgBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAgD,CAAC;AAuF7E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,GAAE,WAAgB,GAAG,MAAM,CAU7E"}

package/dist/scalar-mutate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Mutation and crossover operators over {@link ScalarNode} trees.
+ *
+ * @packageDocumentation
+ */
+import { type ScalarGrammar, type ScalarNode } from '@danielsimonjr/mathts-expression';
+import type { SeededRng } from '@danielsimonjr/mathts-core';
+/** Probability of negating a perturbed constant when mutating a numeric leaf. */
+export declare const MUTATE_CONSTANT_NEGATE_PROBABILITY = 0.00743;
+/** Default mutation weights (optimize/backsolve omitted). Draw order. */
+export declare const DEFAULT_MUTATION_WEIGHTS: {
+    readonly rotateTree: 4.26;
+    readonly addNode: 2.47;
+    readonly deleteNode: 0.87;
+    readonly mutateOperator: 0.293;
+    readonly identity: 0.273;
+    readonly swapOperands: 0.198;
+    readonly mutateFeature: 0.1;
+    readonly mutateConstant: 0.0346;
+    readonly insertNode: 0.0112;
+    readonly simplifyConstants: 0.00209;
+    readonly randomizeTree: 0.000502;
+};
+export type MutationWeightKey = keyof typeof DEFAULT_MUTATION_WEIGHTS;
+/** Context for mutation operators (no hidden defaults). */
+export interface ScalarMutationContext {
+    readonly grammar: ScalarGrammar;
+    readonly perturbationFactor: number;
+    readonly temperature: number;
+}
+export type ScalarMutationOperator = (node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext) => ScalarNode | null;
+/**
+ * Returns the input unchanged. Does not consume `rng`. The weight key is `identity`;
+ * the export carries a longer name because
+ * `@danielsimonjr/mathts-functions` already exports the matrix `identity`.
+ */
+export declare function identityMutation(node: ScalarNode, _rng?: SeededRng, _ctx?: ScalarMutationContext): ScalarNode | null;
+/** Perturb one numeric leaf; `null` when none or grammar rejects. */
+export declare function mutateConstant(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Replace one operator or call name; `null` on failure. */
+export declare function mutateOperator(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Replace one symbol leaf with another allowed name. */
+export declare function mutateFeature(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Swap the two operands of one binary operator. */
+export declare function swapOperands(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Replace a subtree with a binary op or unary call over it and a new leaf. */
+export declare function addNode(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/**
+ * Insert a binary operator between a parent (an operator or a call) and one of
+ * its children. A single-node tree has no parent edge and returns `null`.
+ */
+export declare function insertNode(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/**
+ * Replace a binary operator with one of its children. A tree that is a single
+ * node has no operator to delete and returns `null`.
+ */
+export declare function deleteNode(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** One left or right rotation at a nested binary node. */
+export declare function rotateTree(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Replace the tree with a random grammar-constrained tree. */
+export declare function randomizeTree(node: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Fold numeric-only subtrees via {@link evaluateScalar}. */
+export declare function simplifyConstants(node: ScalarNode): ScalarNode;
+/** Subtree crossover between two individuals. */
+export declare function crossoverSubtrees(left: ScalarNode, right: ScalarNode, rng: SeededRng, ctx: ScalarMutationContext): ScalarNode | null;
+/** Draw a mutation operator key from weighted defaults or overrides. */
+export declare function drawMutationOperator(rng: SeededRng, weights?: Readonly<Record<MutationWeightKey, number>>): MutationWeightKey;
+/** Combine mutation operators with {@link DEFAULT_MUTATION_WEIGHTS}. */
+export declare function weightedMutation(weights?: Readonly<Record<MutationWeightKey, number>>): ScalarMutationOperator;
+//# sourceMappingURL=scalar-mutate.d.ts.map

package/dist/scalar-mutate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-mutate.d.ts","sourceRoot":"","sources":["../src/scalar-mutate.ts"],"names":[],"mappings":"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"}

package/dist/scalar-node-bridge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert between {@link ScalarNode} trees and wired expression {@link MathNode}s.
+ *
+ * @packageDocumentation
+ */
+import type { MathNode, ScalarNode, StringOptions } from '@danielsimonjr/mathts-expression';
+import type { SimplifyOptions } from '../types/index.js';
+export type { MathNode, StringOptions, SimplifyOptions };
+type ConstantCtor = new (value: number) => MathNode;
+type SymbolCtor = new (name: string) => MathNode;
+type OperatorCtor = new (op: string, fn: string, args: MathNode[], implicit?: boolean, isPercentage?: boolean) => MathNode;
+type FunctionCtor = new (fn: string, args: MathNode[]) => MathNode;
+export interface ScalarNodeBridgeDeps {
+    ConstantNode: ConstantCtor;
+    SymbolNode: SymbolCtor;
+    OperatorNode: OperatorCtor;
+    FunctionNode: FunctionCtor;
+    simplify: (node: MathNode, ...rest: unknown[]) => MathNode;
+}
+/**
+ * Wire {@link scalarToNode}, {@link nodeToScalar}, {@link simplifyScalar}, and
+ * {@link scalarToTex} to the expression node classes and `simplify` from the factory graph.
+ */
+export declare function createScalarNodeBridge(deps: ScalarNodeBridgeDeps): {
+    scalarToNode: (node: ScalarNode) => MathNode;
+    nodeToScalar: (node: MathNode) => ScalarNode;
+    simplifyScalar: (node: ScalarNode, options?: SimplifyOptions) => ScalarNode;
+    scalarToTex: (node: ScalarNode, options?: StringOptions) => string;
+};
+//# sourceMappingURL=scalar-node-bridge.d.ts.map

package/dist/scalar-node-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-node-bridge.d.ts","sourceRoot":"","sources":["../src/scalar-node-bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAEV,QAAQ,EACR,UAAU,EACV,aAAa,EACd,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASzD,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAmCzD,KAAK,YAAY,GAAG,KAAK,KAAK,EAAE,MAAM,KAAK,QAAQ,CAAC;AACpD,KAAK,UAAU,GAAG,KAAK,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC;AACjD,KAAK,YAAY,GAAG,KAClB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,QAAQ,EAAE,EAChB,QAAQ,CAAC,EAAE,OAAO,EAClB,YAAY,CAAC,EAAE,OAAO,KACnB,QAAQ,CAAC;AACd,KAAK,YAAY,GAAG,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,QAAQ,CAAC;AAEnE,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,YAAY,CAAC;IAC3B,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,CAAC;CAC5D;AAwMD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,oBAAoB;yBAenC,UAAU,KAAG,QAAQ;yBAiBrB,QAAQ,KAAG,UAAU;2BAsBnB,UAAU,YAAY,eAAe,KAAG,UAAU;wBA+BrD,UAAU,YAAY,aAAa,KAAG,MAAM;EAMxE"}