@danielsimonjr/mathts-core 0.1.5 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TypedInstance, TypedFunction } from 'typed-function';
+import { TypedInstance, ReferTo, ReferToSelf, TypedFunction, SignatureFunction } from 'typed-function';
 export { ReferTo, ReferToSelf, SignatureFunction, TypedFunction, TypedInstance, create, default as typed } from 'typed-function';
 
 /**
@@ -416,6 +416,84 @@ declare const COMPLEX_ZERO: Complex;
 declare const COMPLEX_ONE: Complex;
 declare const COMPLEX_NEG_ONE: Complex;
 
+/**
+ * Dual number for forward-mode automatic differentiation.
+ *
+ * A dual number `a + b·ε` (with ε² = 0) carries a value and its first
+ * derivative. Evaluating a function built from the overloaded elementary
+ * operations on `Dual.variable(x)` propagates the derivative automatically:
+ *
+ *   derivative(x => multiply(sin(x), x), 2)
+ *     // sin(2)·1 + 2·cos(2)  — exact, no finite differences
+ *
+ * The derivative rules live here as methods so the typed-function signatures in
+ * the `functions` package are one-liners (e.g. `Dual: (a) => a.sin()`).
+ */
+declare class Dual {
+    /** Function value (the real part). */
+    readonly value: number;
+    /** First derivative (the ε coefficient). */
+    readonly deriv: number;
+    constructor(value: number, deriv?: number);
+    /** A constant (derivative 0). */
+    static constant(v: number): Dual;
+    /** A seed variable (derivative 1) — the point of differentiation. */
+    static variable(v: number): Dual;
+    add(o: Dual): Dual;
+    sub(o: Dual): Dual;
+    mul(o: Dual): Dual;
+    div(o: Dual): Dual;
+    neg(): Dual;
+    /** Power with a constant real exponent: d(xᵏ) = k·xᵏ⁻¹·dx. */
+    powConst(k: number): Dual;
+    /** General power a^b: d = a^b·(b'·ln a + b·a'/a). */
+    pow(o: Dual): Dual;
+    sin(): Dual;
+    cos(): Dual;
+    tan(): Dual;
+    exp(): Dual;
+    log(): Dual;
+    sqrt(): Dual;
+    square(): Dual;
+    abs(): Dual;
+    sinh(): Dual;
+    cosh(): Dual;
+    tanh(): Dual;
+    toString(): string;
+}
+/** Type guard for {@link Dual}. */
+declare function isDual(x: unknown): x is Dual;
+
+/**
+ * Named mathematical constants (plain `number`).
+ *
+ * These mirror the constants documented in `docs/reference/constants.md` and the
+ * familiar `Math.*` values, exported as first-class named bindings so callers can
+ * `import { PI, E, TAU } from '@danielsimonjr/mathts-core'`. The imaginary unit
+ * `I` and the type-specific constants (`COMPLEX_*`, `BIGNUMBER_*`, `FRACTION_*`)
+ * live with their respective types.
+ */
+/** Ratio of a circle's circumference to its diameter. */
+declare const PI: number;
+/** Euler's number, the base of the natural logarithm. */
+declare const E: number;
+/** Full-circle constant, `2·PI`. */
+declare const TAU: number;
+/** Golden ratio, `(1 + √5) / 2`. */
+declare const PHI: number;
+/** Square root of 2. */
+declare const SQRT2: number;
+/** Square root of one-half. */
+declare const SQRT1_2: number;
+/** Natural logarithm of 2. */
+declare const LN2: number;
+/** Natural logarithm of 10. */
+declare const LN10: number;
+/** Base-2 logarithm of E. */
+declare const LOG2E: number;
+/** Base-10 logarithm of E. */
+declare const LOG10E: number;
+
 /**
  * Fraction (rational number) implementation
  * @module @danielsimonjr/mathts-core/types/fraction
@@ -1300,6 +1378,41 @@ declare function initTypedWasm(options?: {
  */
 declare function isTypedWasmAvailable(): boolean;
 
+/**
+ * Any concrete implementation accepted when *declaring* a typed signature.
+ *
+ * typed-function's published `SignatureFunction` is `(...args: unknown[]) =>
+ * unknown`, which is correct for *internal/output* positions (where the stored
+ * impl is later CALLED with validated args) but wrong as an *input* type:
+ * under `strictFunctionTypes`, function parameters are contravariant, so a
+ * concrete impl such as `(a: number, b: number) => number` is NOT assignable
+ * to an `unknown[]` parameter list (`unknown` is not assignable to `number`).
+ * The correct top-type for "any function" in an input position uses `never`
+ * parameters — every function is assignable to it because `never` is
+ * assignable to every parameter type. This is exactly the set of values
+ * typed-function genuinely accepts when declaring signatures.
+ */
+type SignatureImpl = (...args: never[]) => unknown;
+/** Signature record accepted by the MathTS typed factory (see {@link SignatureImpl}). */
+type SignatureRecord = Record<string, SignatureImpl | ReferTo | ReferToSelf>;
+/**
+ * The MathTS typed-function factory type.
+ *
+ * Structurally identical to typed-function's {@link TypedInstance} except its
+ * call signatures accept implementations declared with concrete parameter
+ * types (see {@link SignatureImpl}). All instance methods are inherited
+ * unchanged via `Omit<TypedInstance, never>` (a mapped type, which drops the
+ * overly-strict published call signatures while preserving every method).
+ */
+interface MathTSTyped extends Omit<TypedInstance, never> {
+    (name: string, signatures: SignatureRecord): TypedFunction;
+    (signatures: SignatureRecord): TypedFunction;
+    (...args: Array<string | SignatureRecord | TypedFunction | (SignatureImpl & {
+        signature: string;
+    })>): TypedFunction;
+    referToSelf: (callback: (self: TypedFunction) => SignatureImpl) => ReferToSelf;
+    referTo: (...args: [...string[], (...fns: SignatureFunction[]) => SignatureImpl]) => ReferTo;
+}
 /**
  * Type definition for typed-function
  */
@@ -1406,7 +1519,7 @@ declare function createMathTSTyped(): TypedInstance;
  * add(1, new Complex(2, 3));              // Complex(3, 3) - auto-converts
  * ```
  */
-declare const mathTyped: TypedInstance;
+declare const mathTyped: MathTSTyped;
 
 /**
  * TypeRegistry class for managing custom type registrations
@@ -1600,4 +1713,4 @@ declare const math: {
 
 declare const VERSION = "0.1.0";
 
-export { ALL_UNITS, BASE_UNITS, BEST_PREFIXES, BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, DERIVED_UNITS, DIMENSIONLESS, DimensionMismatchError, type Dimensions, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericType, type RoundingMode, SI_PREFIXES, type Scalar, type TypeDef, TypeRegistry, UNIT_ALIASES, Unit, type UnitDef, UnitParseError, VERSION, createFactory, createMathTSTyped, createTypedFunction, dim, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isFraction, isFunction, isMatrix, isNull, isNumber, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, isUnit$1 as isUnitValue, math, mathTyped, registerNativeTypes, registry };
+export { ALL_UNITS, BASE_UNITS, BEST_PREFIXES, BIGNUMBER_E, BIGNUMBER_LN10, BIGNUMBER_LN2, BIGNUMBER_NEG_ONE, BIGNUMBER_ONE, BIGNUMBER_PI, BIGNUMBER_TEN, BIGNUMBER_ZERO, type BackendType, BigNumber, type BigNumberConfig, COMPLEX_NEG_ONE, COMPLEX_ONE, COMPLEX_ZERO, Complex, type ConversionDef, DEFAULT_CONFIG, DERIVED_UNITS, DIMENSIONLESS, DimensionMismatchError, type Dimensions, Dual, E, FRACTION_HALF, FRACTION_NEG_ONE, FRACTION_ONE, FRACTION_QUARTER, FRACTION_THIRD, FRACTION_ZERO, type FactoryDependencies, type FactoryFunction, type FactoryImport, Fraction, FunctionRegistry, I, type IBigNumber, type IComplex, type IFraction, type IMatrix, LN10, LN2, LOG10E, LOG2E, MATHTS_CONVERSIONS, MATHTS_TYPES, type MathTSConfig, type MathTSValue, type MatrixBackend, type MatrixDimensions, type NumericType, PHI, PI, type RoundingMode, SI_PREFIXES, SQRT1_2, SQRT2, type Scalar, TAU, type TypeDef, TypeRegistry, UNIT_ALIASES, Unit, type UnitDef, UnitParseError, VERSION, createFactory, createMathTSTyped, createTypedFunction, dim, getPrefix, getUnitDef, initTypedWasm, isArray, isBigInt, isBigNumber, isBoolean, isComplex, isDenseMatrix, isDual, isFraction, isFunction, isMatrix, isNull, isNumber, isObject, isSparseMatrix, isString, isTypedWasmAvailable, isUndefined, isUnit, isUnit$1 as isUnitValue, math, mathTyped, registerNativeTypes, registry };

package/dist/index.js

@@ -553,6 +553,109 @@ var COMPLEX_ZERO = new Complex(0, 0);
 var COMPLEX_ONE = new Complex(1, 0);
 var COMPLEX_NEG_ONE = new Complex(-1, 0);
 
+// src/types/dual.ts
+var Dual = class _Dual {
+  /** Function value (the real part). */
+  value;
+  /** First derivative (the ε coefficient). */
+  deriv;
+  constructor(value, deriv = 0) {
+    this.value = value;
+    this.deriv = deriv;
+  }
+  /** A constant (derivative 0). */
+  static constant(v) {
+    return new _Dual(v, 0);
+  }
+  /** A seed variable (derivative 1) — the point of differentiation. */
+  static variable(v) {
+    return new _Dual(v, 1);
+  }
+  // --- arithmetic ----------------------------------------------------------
+  add(o) {
+    return new _Dual(this.value + o.value, this.deriv + o.deriv);
+  }
+  sub(o) {
+    return new _Dual(this.value - o.value, this.deriv - o.deriv);
+  }
+  mul(o) {
+    return new _Dual(this.value * o.value, this.deriv * o.value + this.value * o.deriv);
+  }
+  div(o) {
+    const d = (this.deriv * o.value - this.value * o.deriv) / (o.value * o.value);
+    return new _Dual(this.value / o.value, d);
+  }
+  neg() {
+    return new _Dual(-this.value, -this.deriv);
+  }
+  /** Power with a constant real exponent: d(xᵏ) = k·xᵏ⁻¹·dx. */
+  powConst(k) {
+    return new _Dual(Math.pow(this.value, k), this.deriv * k * Math.pow(this.value, k - 1));
+  }
+  /** General power a^b: d = a^b·(b'·ln a + b·a'/a). */
+  pow(o) {
+    const v = Math.pow(this.value, o.value);
+    const d = v * (o.deriv * Math.log(this.value) + o.value * this.deriv / this.value);
+    return new _Dual(v, d);
+  }
+  // --- elementary functions ------------------------------------------------
+  sin() {
+    return new _Dual(Math.sin(this.value), this.deriv * Math.cos(this.value));
+  }
+  cos() {
+    return new _Dual(Math.cos(this.value), -this.deriv * Math.sin(this.value));
+  }
+  tan() {
+    const c = Math.cos(this.value);
+    return new _Dual(Math.tan(this.value), this.deriv / (c * c));
+  }
+  exp() {
+    const e = Math.exp(this.value);
+    return new _Dual(e, this.deriv * e);
+  }
+  log() {
+    return new _Dual(Math.log(this.value), this.deriv / this.value);
+  }
+  sqrt() {
+    const s = Math.sqrt(this.value);
+    return new _Dual(s, this.deriv / (2 * s));
+  }
+  square() {
+    return new _Dual(this.value * this.value, 2 * this.value * this.deriv);
+  }
+  abs() {
+    return new _Dual(Math.abs(this.value), this.deriv * Math.sign(this.value));
+  }
+  sinh() {
+    return new _Dual(Math.sinh(this.value), this.deriv * Math.cosh(this.value));
+  }
+  cosh() {
+    return new _Dual(Math.cosh(this.value), this.deriv * Math.sinh(this.value));
+  }
+  tanh() {
+    const t = Math.tanh(this.value);
+    return new _Dual(t, this.deriv * (1 - t * t));
+  }
+  toString() {
+    return `Dual(${this.value}, ${this.deriv})`;
+  }
+};
+function isDual(x) {
+  return x instanceof Dual;
+}
+
+// src/constants.ts
+var PI = Math.PI;
+var E = Math.E;
+var TAU = 2 * Math.PI;
+var PHI = (1 + Math.sqrt(5)) / 2;
+var SQRT2 = Math.SQRT2;
+var SQRT1_2 = Math.SQRT1_2;
+var LN2 = Math.LN2;
+var LN10 = Math.LN10;
+var LOG2E = Math.LOG2E;
+var LOG10E = Math.LOG10E;
+
 // src/types/fraction.ts
 function isFraction(value) {
   return value instanceof Fraction;
@@ -840,7 +943,7 @@ var Fraction = class _Fraction {
       return this.inverse().pow(-exp);
     }
     let result = new _Fraction(1n, 1n);
-    let base = this;
+    let base = this.clone();
     let e = exp;
     while (e > 0n) {
       if (e % 2n === 1n) {
@@ -1564,7 +1667,7 @@ var BigNumber = class _BigNumber {
       return _BigNumber.fromNumber(1).divide(this.pow(-exp));
     }
     let result = _BigNumber.fromNumber(1);
-    let base = this;
+    let base = this.clone();
     let e = exp;
     while (e > 0) {
       if (e % 2 === 1) {
@@ -2972,7 +3075,8 @@ var MATHTS_TYPES = [
   { name: "SparseMatrix", test: isSparseMatrix },
   { name: "Matrix", test: isMatrix },
   // Other types
-  { name: "Unit", test: isUnit2 }
+  { name: "Unit", test: isUnit2 },
+  { name: "Dual", test: isDual }
 ];
 var MATHTS_CONVERSIONS = [
   // -------------------------------------------------------------------------
@@ -3408,6 +3512,8 @@ export {
   DERIVED_UNITS,
   DIMENSIONLESS,
   DimensionMismatchError,
+  Dual,
+  E,
   FRACTION_HALF,
   FRACTION_NEG_ONE,
   FRACTION_ONE,
@@ -3417,9 +3523,18 @@ export {
   Fraction,
   FunctionRegistry,
   I,
+  LN10,
+  LN2,
+  LOG10E,
+  LOG2E,
   MATHTS_CONVERSIONS,
   MATHTS_TYPES,
+  PHI,
+  PI,
   SI_PREFIXES,
+  SQRT1_2,
+  SQRT2,
+  TAU,
   TypeRegistry,
   UNIT_ALIASES,
   Unit,
@@ -3439,6 +3554,7 @@ export {
   isBoolean,
   isComplex,
   isDenseMatrix,
+  isDual,
   isFraction,
   isFunction,
   isMatrix,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-core",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Core types, utilities, and configuration for MathTS",
   "author": "Daniel Simon Jr.",
   "license": "MIT",