adjointly 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,868 @@
+/**
+ * Scalar arithmetic over a value type `T`. Write a function once against this interface, generic
+ * in `T`, and run it three ways: on plain numbers ({@link plain}), recording a tape for gradients
+ * ({@link Tape}), or carrying tangents for directional derivatives ({@link Forward}).
+ *
+ * Every operation on a `T` must go through these methods. A `T` is opaque: for `Tape` and
+ * `Forward` it is an index into storage, and `Math.exp(x)` or `x * y` on it computes nonsense
+ * (the branded types make most such mistakes compile errors). Numbers enter through
+ * {@link Arithmetic.constant} and leave through {@link Arithmetic.value}.
+ *
+ * The values every implementation computes come from the same {@link primitives} table, so a
+ * function's value is bit-for-bit identical under all of them. Subgradient conventions (`abs` at
+ * `0`, ties in `max`/`min`, `pow` with a non-positive base) are documented there.
+ *
+ * @typeParam T - the value type: `number` for `plain`, `Var` for `Tape`, `Dual` for `Forward`.
+ *
+ * @example
+ * ```ts
+ * import { type Arithmetic, plain, gradient } from 'adjointly';
+ *
+ * // f(x, y) = x * e^y + 3
+ * function f<T>(A: Arithmetic<T>, [x, y]: readonly [T, T]): T {
+ *   return A.addc(A.mul(x, A.exp(y)), 3);
+ * }
+ * f(plain, [2, 0]);   //=> 5
+ * gradient(f, [2, 0]); //=> { value: 5, gradient: [1, 2] }
+ * ```
+ */
+interface Arithmetic<T> {
+  /**
+   * Lift a number into `T` as a constant: its derivative with respect to every input is zero.
+   * On a `Tape` it still appends a node (constants are leaves of the tape).
+   */
+  constant(x: number): T;
+  /**
+   * The current numeric value of `a`. Use it to branch (`if (A.value(x) > 0)`), to log, or to
+   * return a result. The number it returns carries no derivative information: anything computed
+   * from it with ordinary arithmetic is a constant as far as differentiation is concerned.
+   */
+  value(a: T): number;
+  /** `-a`. */
+  neg(a: T): T;
+  /** `a + b`. */
+  add(a: T, b: T): T;
+  /** `a - b`. */
+  sub(a: T, b: T): T;
+  /** `a * b`. */
+  mul(a: T, b: T): T;
+  /** `a / b`. */
+  div(a: T, b: T): T;
+  /** `1 / a`. */
+  recip(a: T): T;
+  /** `a * a`, one node instead of a `mul` of `a` with itself. */
+  square(a: T): T;
+  /** `sqrt(a)`; its derivative at `0` is `+Infinity`. */
+  sqrt(a: T): T;
+  /** `e^a`. */
+  exp(a: T): T;
+  /** `e^a - 1`, accurate for small `a`. */
+  expm1(a: T): T;
+  /** Natural logarithm. */
+  log(a: T): T;
+  /** `log(1 + a)`, accurate for small `a`. */
+  log1p(a: T): T;
+  /**
+   * `a ** b`, differentiable in both arguments. The derivative with respect to `b` is `0` wherever
+   * `a <= 0`; the derivative with respect to `a` is `0` wherever `b === 0`. For a fixed numeric
+   * exponent use {@link Arithmetic.powc}; for `b = 2` prefer {@link Arithmetic.square}, for
+   * `b = 0.5` prefer {@link Arithmetic.sqrt}.
+   */
+  pow(a: T, b: T): T;
+  /** `|a|`; its derivative at `0` is `0`. */
+  abs(a: T): T;
+  /** The smaller of `a` and `b`; on a tie the derivative flows to `a`. */
+  min(a: T, b: T): T;
+  /** The larger of `a` and `b`; on a tie the derivative flows to `a`. */
+  max(a: T, b: T): T;
+  /** Sine. */
+  sin(a: T): T;
+  /** Cosine. */
+  cos(a: T): T;
+  /** Hyperbolic tangent. */
+  tanh(a: T): T;
+  /** Logistic sigmoid `1 / (1 + e^-a)`, stable for any `a`. */
+  sigmoid(a: T): T;
+  /** Softplus `log(1 + e^a)`, stable for any `a`; its derivative is `sigmoid(a)`. */
+  softplus(a: T): T;
+  /**
+   * `a + c` for a plain number `c`: `add(a, constant(c))` without the constant's tape node. Same
+   * value and derivative, bit for bit.
+   */
+  addc(a: T, c: number): T;
+  /** `a - c` for a plain number `c`; `sub(a, constant(c))` in one node. */
+  subc(a: T, c: number): T;
+  /** `c - a` for a plain number `c`; `sub(constant(c), a)` in one node. */
+  csub(c: number, a: T): T;
+  /** `a * c` for a plain number `c`; `mul(a, constant(c))` in one node. */
+  mulc(a: T, c: number): T;
+  /** `a / c` for a plain number `c`; `div(a, constant(c))` in one node. */
+  divc(a: T, c: number): T;
+  /** `c / a` for a plain number `c`; `div(constant(c), a)` in one node. */
+  cdiv(c: number, a: T): T;
+  /**
+   * `a ** c` for a plain number `c`; `pow(a, constant(c))` in one node, with the same conventions
+   * (the derivative is `0` when `c === 0`).
+   */
+  powc(a: T, c: number): T;
+}
+/**
+ * The inputs of a {@link ScalarFunction}: one `T` for each number in the point `X`. For a point
+ * written as a literal, `[3, 4]`, that is the tuple `readonly [T, T]`, so destructured inputs need
+ * no non-null assertions; for a `number[]` it is `readonly T[]`.
+ */
+type Inputs<T, X extends readonly number[]> = { readonly [K in keyof X]: T; };
+/**
+ * A function of several inputs written once against {@link Arithmetic}, the shape the
+ * conveniences ({@link gradient}, {@link jvp}, {@link evaluate}, {@link checkGradient}) accept.
+ * The input array has exactly as many elements as the point it is evaluated at; `X` is the type of
+ * that point, so `ScalarFunction<[number, number]>` takes two inputs.
+ *
+ * @example
+ * ```ts
+ * const rosenbrock: ScalarFunction<[number, number]> = (A, [x, y]) =>
+ *   A.add(
+ *     A.square(A.csub(1, x)),
+ *     A.mulc(A.square(A.sub(y, A.square(x))), 100),
+ *   );
+ * evaluate(rosenbrock, [1, 1]); //=> 0
+ * gradient(rosenbrock, [0, 0]).gradient; //=> [-2, 0]
+ * ```
+ */
+type ScalarFunction<X extends readonly number[] = readonly number[]> = <T>(A: Arithmetic<T>, xs: Inputs<T, X>) => T;
+/**
+ * {@link Arithmetic} on ordinary numbers: computes values only, with nothing recorded. Use it to
+ * evaluate a differentiable function at full speed when no derivative is needed.
+ *
+ * @example
+ * ```ts
+ * import { plain } from 'adjointly';
+ * plain.add(plain.constant(1), plain.exp(0)); //=> 2
+ * ```
+ */
+export declare const plain: Arithmetic<number>;
+/** A primitive of one argument: `y = value(x)`, `dy/dx = deriv(x, y)`. */
+interface UnaryPrimitive {
+  /** The primitive's name, equal to its key in {@link primitives} and its method on `Arithmetic`. */
+  readonly name: string;
+  /** The value of the operation at `x`. */
+  readonly value: (x: number) => number;
+  /** The derivative `dy/dx` at `x`, given `y = value(x)`. */
+  readonly deriv: (x: number, y: number) => number;
+}
+/** A primitive of two arguments: `y = value(a, b)`, with partials `da = dy/da` and `db = dy/db`. */
+interface BinaryPrimitive {
+  /** The primitive's name, equal to its key in {@link primitives} and its method on `Arithmetic`. */
+  readonly name: string;
+  /** The value of the operation at `(a, b)`. */
+  readonly value: (a: number, b: number) => number;
+  /** The partial derivative `dy/da` at `(a, b)`, given `y = value(a, b)`. */
+  readonly da: (a: number, b: number, y: number) => number;
+  /** The partial derivative `dy/db` at `(a, b)`, given `y = value(a, b)`. */
+  readonly db: (a: number, b: number, y: number) => number;
+}
+/**
+ * Every primitive, keyed by name. Subgradient conventions at points where the derivative does not
+ * exist are part of the contract:
+ *
+ * | primitive | convention |
+ * |---|---|
+ * | `abs` | derivative at `0` is `0` |
+ * | `max`, `min` | on a tie (`a === b`) the whole derivative goes to the first argument `a` |
+ * | `pow` | `d/db` is `0` wherever `a <= 0`; `d/da` is `0` wherever `b === 0` |
+ * | `sqrt` | derivative at `0` (and `-0`) is `+Infinity` (the true one-sided limit) |
+ * | `max`, `min` | if either argument is `NaN`, the value and both partials are `NaN`, as for `abs` |
+ *
+ * Everywhere else the partials are the ordinary analytic derivatives, and outside a function's
+ * domain (`log` of a negative, `sqrt` of a negative) the value and partials are whatever IEEE
+ * arithmetic produces, usually `NaN`.
+ *
+ * @example
+ * ```ts
+ * import { primitives } from 'adjointly';
+ * const x = 0.5;
+ * const y = primitives.tanh.value(x); //=> tanh(0.5)
+ * const dy = primitives.tanh.deriv(x, y); //=> 1 - tanh(0.5) ** 2
+ * ```
+ */
+export declare const primitives: Readonly<{
+  /** `-x`. */
+  neg: UnaryPrimitive;
+  /** `a + b`. */
+  add: BinaryPrimitive;
+  /** `a - b`. */
+  sub: BinaryPrimitive;
+  /** `a * b`. */
+  mul: BinaryPrimitive;
+  /** `a / b`. */
+  div: BinaryPrimitive;
+  /** `1 / x`. */
+  recip: UnaryPrimitive;
+  /** `x * x`. */
+  square: UnaryPrimitive;
+  /** `sqrt(x)`; derivative `+Infinity` at `0` and at `-0`. */
+  sqrt: UnaryPrimitive;
+  /** `e^x`. */
+  exp: UnaryPrimitive;
+  /** `e^x - 1`, accurate near `0`. */
+  expm1: UnaryPrimitive;
+  /** Natural logarithm. */
+  log: UnaryPrimitive;
+  /** `log(1 + x)`, accurate near `0`. */
+  log1p: UnaryPrimitive;
+  /**
+   * `a ** b`, differentiable in both. `d/da = b * a^(b-1)`, taken as `0` when `b === 0` (so
+   * `0^0` does not produce `0 * Infinity`). `d/db = a^b * log(a)` for `a > 0` and `0` for
+   * `a <= 0`, where the real power is not differentiable in the exponent.
+   */
+  pow: BinaryPrimitive;
+  /** `|x|`; derivative `0` at `0`. */
+  abs: UnaryPrimitive;
+  /**
+   * The smaller of `a` and `b`; on a tie the derivative goes to `a`. If either is `NaN`, the value
+   * and both partials are `NaN`.
+   */
+  min: BinaryPrimitive;
+  /**
+   * The larger of `a` and `b`; on a tie the derivative goes to `a`. If either is `NaN`, the value
+   * and both partials are `NaN`.
+   */
+  max: BinaryPrimitive;
+  /** Sine. */
+  sin: UnaryPrimitive;
+  /** Cosine. */
+  cos: UnaryPrimitive;
+  /** Hyperbolic tangent. */
+  tanh: UnaryPrimitive;
+  /** Logistic sigmoid `1 / (1 + e^-x)`, stable for any `x`. */
+  sigmoid: UnaryPrimitive;
+  /**
+   * Softplus `log(1 + e^x)`, stable for any `x`: computed as `x + log1p(e^-x)` for positive `x`
+   * and `log1p(e^x)` otherwise, so it neither overflows nor rounds to `0` for very negative `x`.
+   * Its derivative is `sigmoid(x)`.
+   */
+  softplus: UnaryPrimitive;
+}>;
+/** Names of the one-argument primitives. */
+type UnaryName = { [K in keyof typeof primitives]: (typeof primitives)[K] extends {
+  deriv: unknown;
+} ? K : never; }[keyof typeof primitives];
+/** Names of the two-argument primitives. */
+type BinaryName = Exclude<keyof typeof primitives, UnaryName>;
+/** The names of the one-argument primitives, in table order. */
+export declare const unaryNames: readonly UnaryName[];
+/** The names of the two-argument primitives, in table order. */
+export declare const binaryNames: readonly BinaryName[];
+declare const varBrand: unique symbol;
+declare const markBrand: unique symbol;
+/**
+ * A variable on a {@link Tape}: at run time a plain integer, the index of its node. The brand makes
+ * it a compile-time error to pass a raw number where a `Var` is expected, or to use a `Var` from a
+ * {@link Forward} where a tape's is expected; numbers enter a tape through
+ * {@link Tape.input} or {@link Tape.constant}.
+ *
+ * A `Var` is only meaningful on the tape that created it, and only until that tape is cleared or
+ * rewound past it. Neither is checked at run time.
+ *
+ * Because it is a number underneath, `x + y` on two `Var`s type-checks (TypeScript allows
+ * arithmetic on number subtypes) and silently adds two indices. Always use `tape.add(x, y)`.
+ */
+type Var = number & {
+  readonly [varBrand]: 'adjointly.Var';
+};
+/** A checkpoint on a {@link Tape}, returned by {@link Tape.mark} and consumed by {@link Tape.rewind}. */
+type Mark = number & {
+  readonly [markBrand]: 'adjointly.Mark';
+};
+/** Options for constructing a {@link Tape}. */
+interface TapeOptions {
+  /**
+   * Initial capacity in nodes, a positive integer (default 1024; anything else throws a
+   * `RangeError`). The tape doubles whenever it fills, so this only matters to avoid the first few
+   * reallocations when the size of the computation is known.
+   */
+  readonly capacity?: number;
+  /**
+   * Check every operand (default `false`). Each method then verifies that its variables are live
+   * variables of this Tape, and throws a `RangeError` naming the method and the argument for a
+   * plain number, a variable from before `clear()` or `rewind()`, or one from another Tape or Forward.
+   * Off, nothing is checked and nothing is slower: a debug Tape is a separate set of methods on
+   * that one instance. Its variables are no longer small integers (they encode which recording
+   * they belong to), which is invisible unless they are used as numbers.
+   *
+   * @example
+   * ```ts
+   * const t = new Tape({ debug: true });
+   * t.input(5);
+   * let caught = '';
+   * try {
+   *   t.exp(1 as Var);
+   * } catch (e) {
+   *   caught = (e as Error).message.split(',')[0]!;
+   * }
+   * caught; //=> 'Tape.exp: argument 1 is the plain number 1'
+   * ```
+   */
+  readonly debug?: boolean;
+}
+/**
+ * Reverse-mode automatic differentiation: an {@link Arithmetic} over {@link Var} that records
+ * every operation as a node on a tape, then computes the derivative of one output with respect to
+ * every node in a single backward sweep.
+ *
+ * Each node stores its value, up to two parent indices and the local partial derivatives with
+ * respect to them, computed when the node is recorded, and its adjoint: six typed arrays, 40
+ * bytes a node. They double when full, so recording does not allocate once the tape has grown to
+ * the size of the computation, and a tape reused across evaluations (via {@link Tape.clear} or
+ * {@link Tape.rewind}) never allocates again.
+ *
+ * The backward sweep visits nodes from the output down to the first, adding
+ * `partial * adjoint(child)` into each parent's adjoint, under the zero rule: if the partial or
+ * the adjoint is exactly 0 the term is 0, even when the other is infinite or `NaN`, so an unused
+ * `sqrt(0)` or `log(0)` does not poison the gradient.
+ *
+ * @example
+ * ```ts
+ * import { Tape } from 'adjointly';
+ * const t = new Tape();
+ * const x = t.input(2);
+ * const y = t.input(3);
+ * const f = t.mul(x, t.sin(y)); // x * sin(y)
+ * t.backward(f);
+ * t.adjoint(x); //=> sin(3)
+ * t.adjoint(y); //=> 2 * cos(3)
+ * ```
+ */
+export declare class Tape implements Arithmetic<Var> {
+  private val;
+  private pa;
+  private pb;
+  private da;
+  private db;
+  private adj;
+  /** The next free slot; nodes occupy slots 1 to n - 1. */
+  private n;
+  /** An empty tape; see {@link TapeOptions}. */
+  constructor(options?: TapeOptions);
+  /** The number of nodes recorded so far. */
+  get size(): number;
+  /** The number of nodes the tape can hold before it next grows. */
+  get capacity(): number;
+  /** Forget every node, keeping the storage. Every `Var` previously issued becomes invalid. */
+  clear(): void;
+  /**
+   * A checkpoint at the current end of the tape. {@link Tape.rewind} to it discards everything
+   * recorded after it and keeps everything before, so a shared prefix (inputs, parameters,
+   * precomputed features) is recorded once and reused across many evaluations.
+   *
+   * @example
+   * ```ts
+   * const t = new Tape();
+   * const w = t.input(0.5);
+   * const m = t.mark();
+   * let grad = 0;
+   * for (const x of [1, 2, 3]) {
+   *   t.rewind(m); // drop the previous sample's nodes, keep w
+   *   const loss = t.square(t.subc(t.mulc(w, x), 1));
+   *   t.backward(loss);
+   *   grad += t.adjoint(w);
+   * }
+   * grad; //=> 2 * ((0.5 - 1) * 1 + (1 - 1) * 2 + (1.5 - 1) * 3)
+   * t.size; //=> 4
+   * ```
+   */
+  mark(): Mark;
+  /**
+   * Truncate the tape back to `mark`. Vars created before the mark stay valid with their values;
+   * Vars created after it become invalid. Throws if `mark` is beyond the current end (the tape was
+   * already cleared or rewound further back).
+   */
+  rewind(mark: Mark): void;
+  /**
+   * Record an independent variable with value `x`. Identical to {@link Tape.constant} on the tape
+   * (both are leaves and both accumulate an adjoint); the separate name says which leaves you
+   * intend to read a gradient for.
+   */
+  input(x: number): Var;
+  /**
+   * Record several independent variables at once; see {@link Tape.input}. For a tuple of numbers
+   * the result is a tuple of the same length, so it destructures without non-null assertions.
+   *
+   * @example
+   * ```ts
+   * const t = new Tape();
+   * const [x, y] = t.inputs([2, 3]);
+   * t.value(t.mul(x, y)); //=> 6
+   * ```
+   */
+  inputs<const X extends readonly number[]>(xs: X): { -readonly [K in keyof X]: Var; };
+  inputs(xs: ArrayLike<number>): Var[];
+  /**
+   * Lift a number into `T` as a constant: its derivative with respect to every input is zero.
+   * On a `Tape` it still appends a node (constants are leaves of the tape).
+   */
+  constant(x: number): Var;
+  /**
+   * The current numeric value of `a`. Use it to branch (`if (A.value(x) > 0)`), to log, or to
+   * return a result. The number it returns carries no derivative information: anything computed
+   * from it with ordinary arithmetic is a constant as far as differentiation is concerned.
+   */
+  value(a: Var): number;
+  /**
+   * Run one backward sweep from `output`, seeding its adjoint with `seed` (default 1). Afterwards
+   * {@link Tape.adjoint} of any node `v` is `seed * d(output)/d(v)`. Every call starts from zero
+   * adjoints, so call it once per output whose gradient you want; the recorded tape is not
+   * changed and can be swept any number of times.
+   */
+  backward(output: Var, seed?: number): void;
+  /**
+   * Vector-Jacobian product: one backward sweep seeded with `weights[k]` at `outputs[k]`.
+   * Afterwards {@link Tape.adjoint} of `v` is `sum_k weights[k] * d(outputs[k])/d(v)`. An output
+   * listed twice gets the sum of its weights; with no outputs every adjoint is zero.
+   *
+   * @example
+   * ```ts
+   * const t = new Tape();
+   * const x = t.input(1);
+   * const f = t.square(x); // df/dx = 2x
+   * const g = t.exp(x); // dg/dx = e^x
+   * t.vjp([f, g], [2, 3]); // gradient of 2f + 3g in one sweep
+   * t.adjoint(x); //=> 2 * 2 + 3 * E
+   * ```
+   */
+  vjp(outputs: readonly Var[], weights: ArrayLike<number>): void;
+  /**
+   * The adjoint of `v` from the last {@link Tape.backward} or {@link Tape.vjp}: the derivative of
+   * the seeded output(s) with respect to `v`. Zero for a node the output does not depend on.
+   * Meaningless for a node recorded after the output of that sweep.
+   */
+  adjoint(v: Var): number;
+  /**
+   * Read the adjoints of `vars` into `out` (allocated if not given) and return it: the gradient
+   * restricted to those variables, in their order.
+   */
+  adjoints(vars: readonly Var[], out?: Float64Array): Float64Array;
+  /**
+   * `backward(output)` then `adjoints(inputs, out)`: the gradient of `output` with respect to
+   * `inputs`, in their order.
+   *
+   * @example
+   * ```ts
+   * const t = new Tape();
+   * const [x, y] = t.inputs([1, 2]);
+   * t.gradient(t.mul(x, y), [x, y]); //=> [2, 1]
+   * ```
+   */
+  gradient(output: Var, inputs: readonly Var[], out?: Float64Array): Float64Array;
+  private sweep;
+  private push;
+  private grow;
+  /** `-a`. */
+  neg(a: Var): Var;
+  /** `a + b`. */
+  add(a: Var, b: Var): Var;
+  /** `a - b`. */
+  sub(a: Var, b: Var): Var;
+  /** `a * b`. */
+  mul(a: Var, b: Var): Var;
+  /** `a / b`. */
+  div(a: Var, b: Var): Var;
+  /** `1 / a`. */
+  recip(a: Var): Var;
+  /** `a * a`, one node instead of a `mul` of `a` with itself. */
+  square(a: Var): Var;
+  /** `sqrt(a)`; its derivative at `0` is `+Infinity`. */
+  sqrt(a: Var): Var;
+  /** `e^a`. */
+  exp(a: Var): Var;
+  /** `e^a - 1`, accurate for small `a`. */
+  expm1(a: Var): Var;
+  /** Natural logarithm. */
+  log(a: Var): Var;
+  /** `log(1 + a)`, accurate for small `a`. */
+  log1p(a: Var): Var;
+  /**
+   * `a ** b`, differentiable in both arguments. The derivative with respect to `b` is `0` wherever
+   * `a <= 0`; the derivative with respect to `a` is `0` wherever `b === 0`. For a fixed numeric
+   * exponent use {@link Arithmetic.powc}; for `b = 2` prefer {@link Arithmetic.square}, for
+   * `b = 0.5` prefer {@link Arithmetic.sqrt}.
+   */
+  pow(a: Var, b: Var): Var;
+  /** `|a|`; its derivative at `0` is `0`. */
+  abs(a: Var): Var;
+  /** The smaller of `a` and `b`; on a tie the derivative flows to `a`. */
+  min(a: Var, b: Var): Var;
+  /** The larger of `a` and `b`; on a tie the derivative flows to `a`. */
+  max(a: Var, b: Var): Var;
+  /** Sine. */
+  sin(a: Var): Var;
+  /** Cosine. */
+  cos(a: Var): Var;
+  /** Hyperbolic tangent. */
+  tanh(a: Var): Var;
+  /** Logistic sigmoid `1 / (1 + e^-a)`, stable for any `a`. */
+  sigmoid(a: Var): Var;
+  /** Softplus `log(1 + e^a)`, stable for any `a`; its derivative is `sigmoid(a)`. */
+  softplus(a: Var): Var;
+  /**
+   * `a + c` for a plain number `c`: `add(a, constant(c))` without the constant's tape node. Same
+   * value and derivative, bit for bit.
+   */
+  addc(a: Var, c: number): Var;
+  /** `a - c` for a plain number `c`; `sub(a, constant(c))` in one node. */
+  subc(a: Var, c: number): Var;
+  /** `c - a` for a plain number `c`; `sub(constant(c), a)` in one node. */
+  csub(c: number, a: Var): Var;
+  /** `a * c` for a plain number `c`; `mul(a, constant(c))` in one node. */
+  mulc(a: Var, c: number): Var;
+  /** `a / c` for a plain number `c`; `div(a, constant(c))` in one node. */
+  divc(a: Var, c: number): Var;
+  /** `c / a` for a plain number `c`; `div(constant(c), a)` in one node. */
+  cdiv(c: number, a: Var): Var;
+  /**
+   * `a ** c` for a plain number `c`; `pow(a, constant(c))` in one node, with the same conventions
+   * (the derivative is `0` when `c === 0`).
+   */
+  powc(a: Var, c: number): Var;
+}
+declare const dualBrand: unique symbol;
+/**
+ * A value in a {@link Forward} computation: at run time a plain integer, the index of its slot.
+ * Branded separately from `Var`, so a forward value cannot be passed to a `Tape` or vice versa, and
+ * a raw number cannot be passed where a `Dual` is expected.
+ *
+ * Valid only on the `Forward` that created it, and only until that `Forward` is cleared.
+ */
+type Dual = number & {
+  readonly [dualBrand]: 'adjointly.Dual';
+};
+/** Options for constructing a {@link Forward}. */
+interface ForwardOptions {
+  /**
+   * Initial capacity in values, a positive integer (default 1024; anything else throws a
+   * `RangeError`); storage doubles whenever it fills.
+   */
+  readonly capacity?: number;
+  /**
+   * Check every operand (default `false`). Each method then verifies that its variables are live
+   * variables of this Forward, and throws a `RangeError` naming the method and the argument for a
+   * plain number, a variable from before `clear()`, or one from another Tape or Forward.
+   * Off, nothing is checked and nothing is slower: a debug Forward is a separate set of methods on
+   * that one instance. Its variables are no longer small integers (they encode which recording
+   * they belong to), which is invisible unless they are used as numbers.
+   *
+   * @example
+   * ```ts
+   * const t = new Forward({ debug: true });
+   * t.input(5, 1);
+   * let caught = '';
+   * try {
+   *   t.exp(1 as Dual);
+   * } catch (e) {
+   *   caught = (e as Error).message.split(',')[0]!;
+   * }
+   * caught; //=> 'Forward.exp: argument 1 is the plain number 1'
+   * ```
+   */
+  readonly debug?: boolean;
+}
+/**
+ * Forward-mode automatic differentiation: an {@link Arithmetic} over {@link Dual} where every value
+ * carries a tangent, its derivative along one direction chosen when the inputs are created. One
+ * evaluation gives the directional derivative `grad f(x) . v` (a Jacobian-vector product) for every
+ * output at once, with no backward sweep and nothing kept but a value and a tangent per slot.
+ *
+ * Tangents propagate as `t(y) = da * t(a) + db * t(b)` using the same partials the {@link Tape}
+ * records, under the same zero rule: if a partial or a tangent is exactly 0 the term is 0, even when
+ * the other is infinite or `NaN`, so an infinite partial such as `sqrt` at `0` does not turn a zero
+ * tangent into `NaN`.
+ *
+ * Use forward mode when there are few inputs (or one direction) and many outputs; use the tape
+ * when there are many inputs and one output.
+ *
+ * @example
+ * ```ts
+ * import { Forward } from 'adjointly';
+ * const F = new Forward();
+ * const x = F.input(2, 1); // seed: direction (1, 0)
+ * const y = F.input(3, 0);
+ * const f = F.mul(x, F.sin(y)); // x * sin(y)
+ * F.value(f); //=> 2 * sin(3)
+ * F.tangent(f); //=> sin(3)
+ * ```
+ */
+export declare class Forward implements Arithmetic<Dual> {
+  private val;
+  private tan;
+  private n;
+  /** An empty forward-mode context; see {@link ForwardOptions}. */
+  constructor(options?: ForwardOptions);
+  /** The number of values created so far. */
+  get size(): number;
+  /** Forget every value, keeping the storage. Every `Dual` previously issued becomes invalid. */
+  clear(): void;
+  /** An input with value `x` and tangent (seed) `tangent`: its component of the direction. */
+  input(x: number, tangent: number): Dual;
+  /**
+   * Lift a number into `T` as a constant: its derivative with respect to every input is zero.
+   * On a `Tape` it still appends a node (constants are leaves of the tape).
+   */
+  constant(x: number): Dual;
+  /**
+   * The current numeric value of `a`. Use it to branch (`if (A.value(x) > 0)`), to log, or to
+   * return a result. The number it returns carries no derivative information: anything computed
+   * from it with ordinary arithmetic is a constant as far as differentiation is concerned.
+   */
+  value(a: Dual): number;
+  /** The tangent of `a`: its derivative along the direction the inputs were seeded with. */
+  tangent(a: Dual): number;
+  private push;
+  private grow;
+  /** `-a`. */
+  neg(a: Dual): Dual;
+  /** `a + b`. */
+  add(a: Dual, b: Dual): Dual;
+  /** `a - b`. */
+  sub(a: Dual, b: Dual): Dual;
+  /** `a * b`. */
+  mul(a: Dual, b: Dual): Dual;
+  /** `a / b`. */
+  div(a: Dual, b: Dual): Dual;
+  /** `1 / a`. */
+  recip(a: Dual): Dual;
+  /** `a * a`, one node instead of a `mul` of `a` with itself. */
+  square(a: Dual): Dual;
+  /** `sqrt(a)`; its derivative at `0` is `+Infinity`. */
+  sqrt(a: Dual): Dual;
+  /** `e^a`. */
+  exp(a: Dual): Dual;
+  /** `e^a - 1`, accurate for small `a`. */
+  expm1(a: Dual): Dual;
+  /** Natural logarithm. */
+  log(a: Dual): Dual;
+  /** `log(1 + a)`, accurate for small `a`. */
+  log1p(a: Dual): Dual;
+  /**
+   * `a ** b`, differentiable in both arguments. The derivative with respect to `b` is `0` wherever
+   * `a <= 0`; the derivative with respect to `a` is `0` wherever `b === 0`. For a fixed numeric
+   * exponent use {@link Arithmetic.powc}; for `b = 2` prefer {@link Arithmetic.square}, for
+   * `b = 0.5` prefer {@link Arithmetic.sqrt}.
+   */
+  pow(a: Dual, b: Dual): Dual;
+  /** `|a|`; its derivative at `0` is `0`. */
+  abs(a: Dual): Dual;
+  /** The smaller of `a` and `b`; on a tie the derivative flows to `a`. */
+  min(a: Dual, b: Dual): Dual;
+  /** The larger of `a` and `b`; on a tie the derivative flows to `a`. */
+  max(a: Dual, b: Dual): Dual;
+  /** Sine. */
+  sin(a: Dual): Dual;
+  /** Cosine. */
+  cos(a: Dual): Dual;
+  /** Hyperbolic tangent. */
+  tanh(a: Dual): Dual;
+  /** Logistic sigmoid `1 / (1 + e^-a)`, stable for any `a`. */
+  sigmoid(a: Dual): Dual;
+  /** Softplus `log(1 + e^a)`, stable for any `a`; its derivative is `sigmoid(a)`. */
+  softplus(a: Dual): Dual;
+  /**
+   * `a + c` for a plain number `c`: `add(a, constant(c))` without the constant's tape node. Same
+   * value and derivative, bit for bit.
+   */
+  addc(a: Dual, c: number): Dual;
+  /** `a - c` for a plain number `c`; `sub(a, constant(c))` in one node. */
+  subc(a: Dual, c: number): Dual;
+  /** `c - a` for a plain number `c`; `sub(constant(c), a)` in one node. */
+  csub(c: number, a: Dual): Dual;
+  /** `a * c` for a plain number `c`; `mul(a, constant(c))` in one node. */
+  mulc(a: Dual, c: number): Dual;
+  /** `a / c` for a plain number `c`; `div(a, constant(c))` in one node. */
+  divc(a: Dual, c: number): Dual;
+  /** `c / a` for a plain number `c`; `div(constant(c), a)` in one node. */
+  cdiv(c: number, a: Dual): Dual;
+  /**
+   * `a ** c` for a plain number `c`; `pow(a, constant(c))` in one node, with the same conventions
+   * (the derivative is `0` when `c === 0`).
+   */
+  powc(a: Dual, c: number): Dual;
+}
+/**
+ * The sum of `xs`, added left to right; `A.constant(0)` for an empty list.
+ *
+ * @example
+ * ```ts
+ * sum(plain, [1, 2, 3]); //=> 6
+ * ```
+ */
+export declare function sum<T>(A: Arithmetic<T>, xs: readonly T[]): T;
+/**
+ * The dot product `sum_i xs[i] * ys[i]`; `A.constant(0)` for empty lists. Throws if the lengths
+ * differ.
+ *
+ * @example
+ * ```ts
+ * dot(plain, [1, 2], [3, 4]); //=> 11
+ * ```
+ */
+export declare function dot<T>(A: Arithmetic<T>, xs: readonly T[], ys: readonly T[]): T;
+/**
+ * `log(sum_i exp(xs[i]))`, computed stably as `m + log(sum_i exp(xs[i] - m))` where `m` is the
+ * largest value. `m` enters as a constant: the identity holds for any `m`, so its derivative
+ * through `m` is zero and leaving it out keeps the gradient exact (it is `softmax(xs)`).
+ * Throws on an empty list.
+ *
+ * Infinite inputs give the limit of the finite case. If the largest input is `+Infinity`, or every
+ * input is `-Infinity`, the value is that infinity and the gradient is shared equally by the inputs
+ * equal to it, `0` elsewhere; a `-Infinity` among finite inputs has weight `0`. A `NaN` input
+ * makes everything `NaN`.
+ *
+ * @example
+ * ```ts
+ * // The naive log(exp(1000) + exp(1000)) overflows to Infinity.
+ * logsumexp(plain, [1000, 1000]); //=> 1000 + log(2)
+ * gradient((A, xs) => logsumexp(A, xs), [Infinity, 0]).gradient; //=> [1, 0]
+ * ```
+ */
+export declare function logsumexp<T>(A: Arithmetic<T>, xs: readonly T[]): T;
+/**
+ * The softmax `exp(xs[i]) / sum_j exp(xs[j])`, computed stably by first subtracting the largest
+ * value as a constant (softmax is invariant to the shift, so the gradient stays exact). Throws on
+ * an empty list.
+ *
+ * Infinite inputs give the limit of the finite case. If the largest input is `+Infinity`, or every
+ * input is `-Infinity`, the weights are `1/k` on the `k` inputs equal to it and `0` elsewhere,
+ * returned as constants: the Jacobian there is `0`, which is also its limit. A `-Infinity` among
+ * finite inputs gets weight `0`. A `NaN` input makes every weight `NaN`.
+ *
+ * @example
+ * ```ts
+ * softmax(plain, [0, Math.log(3)]); //=> [0.25, 0.75]
+ * softmax(plain, [Infinity, 0, Infinity]); //=> [0.5, 0, 0.5]
+ * ```
+ */
+export declare function softmax<T>(A: Arithmetic<T>, xs: readonly T[]): T[];
+/** The result of {@link gradient}. */
+interface GradientResult {
+  /** `f(at)`. */
+  readonly value: number;
+  /** `df/d(at[i])` for each `i`. */
+  readonly gradient: number[];
+}
+/** The result of {@link jvp}. */
+interface JvpResult {
+  /** `f(at)`. */
+  readonly value: number;
+  /** The directional derivative `sum_i df/d(at[i]) * direction[i]`. */
+  readonly derivative: number;
+}
+/**
+ * Evaluate `f` at `at` on plain numbers, recording nothing. The value is bit-for-bit the one
+ * {@link gradient} and {@link jvp} report.
+ *
+ * @example
+ * ```ts
+ * evaluate((A, [x]) => A.exp(x), [0]); //=> 1
+ * ```
+ */
+export declare function evaluate<const X extends readonly number[]>(f: ScalarFunction<X>, at: X): number;
+/**
+ * The value and gradient of `f` at `at`, by reverse mode: one forward pass recording a tape and
+ * one backward sweep, whatever the number of inputs.
+ *
+ * Pass `tape` to reuse its storage across calls in a loop; it is cleared first and left holding
+ * this evaluation.
+ *
+ * @example
+ * ```ts
+ * gradient((A, [x, y]) => A.mul(x, y), [3, 4]); //=> { value: 12, gradient: [4, 3] }
+ * ```
+ */
+export declare function gradient<const X extends readonly number[]>(f: ScalarFunction<X>, at: X, tape?: Tape): GradientResult;
+/**
+ * The value of `f` at `at` and its derivative along `direction` (a Jacobian-vector product), by
+ * forward mode: one pass, no tape. Throws if `direction` and `at` differ in length.
+ *
+ * @example
+ * ```ts
+ * jvp((A, [x, y]) => A.mul(x, y), [3, 4], [1, 0]); //=> { value: 12, derivative: 4 }
+ * ```
+ */
+export declare function jvp<const X extends readonly number[]>(f: ScalarFunction<X>, at: X, direction: readonly number[], forward?: Forward): JvpResult;
+/**
+ * Default relative step for {@link finiteDifference}: about the cube root of machine epsilon,
+ * which balances the central difference's `O(h^2)` truncation error against rounding error.
+ */
+export declare const DEFAULT_STEP = 0.000006;
+/**
+ * The gradient of `f` at `at` by central differences on plain numbers:
+ * `(f(x + h_i e_i) - f(x - h_i e_i)) / (2 h_i)` with `h_i = h * max(1, |at[i]|)`.
+ * Costs two evaluations per input; expect agreement with the true gradient to roughly 1e-8
+ * relative for a smooth, well-scaled function, and nothing useful across a kink or a branch.
+ *
+ * @param h - relative step, default {@link DEFAULT_STEP}.
+ *
+ * @example
+ * ```ts
+ * finiteDifference((A, [x]) => A.square(x), [3]); //=> ~[6]
+ * ```
+ */
+export declare function finiteDifference<const X extends readonly number[]>(f: ScalarFunction<X>, at: X, h?: number): number[];
+/** Options for {@link checkGradient}. */
+interface CheckGradientOptions {
+  /** Relative finite-difference step; default {@link DEFAULT_STEP}. */
+  readonly h?: number;
+  /** Relative tolerance; default `1e-5`. */
+  readonly rtol?: number;
+  /** Absolute tolerance; default `1e-8`. */
+  readonly atol?: number;
+}
+/** The result of {@link checkGradient}. */
+interface GradientCheck {
+  /** Whether every component is within tolerance (and none is `NaN`). */
+  readonly ok: boolean;
+  /** `f(at)`. */
+  readonly value: number;
+  /** The gradient by reverse mode. */
+  readonly analytic: number[];
+  /** The gradient by central differences. */
+  readonly numeric: number[];
+  /**
+   * The component furthest out of tolerance relative to its allowance (`-1` index when `at` is
+   * empty). `error` is `|analytic - numeric|`; `roundoff` the estimated rounding error of the
+   * finite difference; `allowed` is `atol + rtol * max(|analytic|, |numeric|) + roundoff`.
+   */
+  readonly worst: {
+    readonly index: number;
+    readonly analytic: number;
+    readonly numeric: number;
+    readonly error: number;
+    readonly allowed: number;
+    readonly roundoff: number;
+  };
+}
+/**
+ * Compare `f`'s reverse-mode gradient at `at` with central finite differences. Component `i`
+ * passes when `|analytic - numeric| <= atol + rtol * max(|analytic|, |numeric|) + roundoff`.
+ *
+ * `roundoff` allows for the rounding error of the finite difference itself, which grows with
+ * `|f|` and shrinks with the step: `4 * eps * (|f(x + h)| + |f(x - h)|) / (2 h)`, four units in the
+ * last place for each evaluation. Without it an exact gradient of a function whose value is large
+ * next to its slope (`1e5 + 1e-3 * x`) would fail.
+ *
+ * Use it in your own tests to verify a function written against `Arithmetic`, typically at a few
+ * random points away from kinks and branch boundaries, where finite differences are meaningless.
+ *
+ * @example
+ * ```ts
+ * const loss: ScalarFunction = (A, xs) => logsumexp(A, xs.map((x) => A.square(x)));
+ * const r = checkGradient(loss, [0.3, -1.2, 2]);
+ * if (!r.ok) {
+ *   const { index, analytic, numeric } = r.worst;
+ *   throw new Error(`component ${String(index)}: ${String(analytic)} vs ${String(numeric)}`);
+ * }
+ * r.ok; //=> true
+ * ```
+ */
+export declare function checkGradient<const X extends readonly number[]>(f: ScalarFunction<X>, at: X, options?: CheckGradientOptions): GradientCheck;
+export type { Arithmetic, BinaryName, BinaryPrimitive, CheckGradientOptions, Dual, ForwardOptions, GradientCheck, GradientResult, Inputs, JvpResult, Mark, ScalarFunction, TapeOptions, UnaryName, UnaryPrimitive, Var };
+//# sourceMappingURL=index.d.ts.map