adjointly 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1390 @@
+// src/primitives.ts
+function unary(name, value, deriv) {
+	return Object.freeze({
+		name,
+		value,
+		deriv
+	});
+}
+function binary(name, value, da, db) {
+	return Object.freeze({
+		name,
+		value,
+		da,
+		db
+	});
+}
+/** Whether `a` or `b` is `NaN`: the one case where neither `a <= b` nor `a > b` holds. */
+function eitherNaN(a, b) {
+	return Number.isNaN(a) || Number.isNaN(b);
+}
+/**
+* Logistic sigmoid `1 / (1 + e^-x)`, evaluated without overflow for any `x`: `exp` is only ever
+* called on `-|x|`.
+*/
+function sigmoidValue(x) {
+	if (x >= 0) return 1 / (1 + Math.exp(-x));
+	const e = Math.exp(x);
+	return e / (1 + e);
+}
+/**
+* `sigmoid'(x) = sigmoid(x) * sigmoid(-x) = e / (1 + e)^2` with `e = exp(-|x|)`. Computed from `x`
+* rather than as `y * (1 - y)`, which loses all precision for large positive `x` where `y` rounds
+* to 1.
+*/
+function sigmoidDeriv(x) {
+	const e = Math.exp(-Math.abs(x));
+	const s = 1 + e;
+	return e / (s * s);
+}
+/**
+* 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
+* ```
+*/
+const primitives = Object.freeze({
+	/** `-x`. */
+	neg: unary("neg", (x) => -x, () => -1),
+	/** `a + b`. */
+	add: binary("add", (a, b) => a + b, () => 1, () => 1),
+	/** `a - b`. */
+	sub: binary("sub", (a, b) => a - b, () => 1, () => -1),
+	/** `a * b`. */
+	mul: binary("mul", (a, b) => a * b, (_a, b) => b, (a) => a),
+	/** `a / b`. */
+	div: binary("div", (a, b) => a / b, (_a, b) => 1 / b, (_a, b, y) => -y / b),
+	/** `1 / x`. */
+	recip: unary("recip", (x) => 1 / x, (_x, y) => -y * y),
+	/** `x * x`. */
+	square: unary("square", (x) => x * x, (x) => 2 * x),
+	/** `sqrt(x)`; derivative `+Infinity` at `0` and at `-0`. */
+	sqrt: unary("sqrt", (x) => Math.sqrt(x), (_x, y) => .5 / (y + 0)),
+	/** `e^x`. */
+	exp: unary("exp", (x) => Math.exp(x), (_x, y) => y),
+	/** `e^x - 1`, accurate near `0`. */
+	expm1: unary("expm1", (x) => Math.expm1(x), (x) => Math.exp(x)),
+	/** Natural logarithm. */
+	log: unary("log", (x) => Math.log(x), (x) => 1 / x),
+	/** `log(1 + x)`, accurate near `0`. */
+	log1p: unary("log1p", (x) => Math.log1p(x), (x) => 1 / (1 + x)),
+	/**
+	* `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: binary("pow", (a, b) => Math.pow(a, b), (a, b) => b === 0 ? 0 : b * Math.pow(a, b - 1), (a, _b, y) => a > 0 ? y * Math.log(a) : 0),
+	/** `|x|`; derivative `0` at `0`. */
+	abs: unary("abs", (x) => Math.abs(x), (x) => x > 0 ? 1 : x < 0 ? -1 : x === 0 ? 0 : NaN),
+	/**
+	* 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: binary("min", (a, b) => Math.min(a, b), (a, b) => a <= b ? 1 : eitherNaN(a, b) ? NaN : 0, (a, b) => a <= b ? 0 : eitherNaN(a, b) ? NaN : 1),
+	/**
+	* 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: binary("max", (a, b) => Math.max(a, b), (a, b) => a >= b ? 1 : eitherNaN(a, b) ? NaN : 0, (a, b) => a >= b ? 0 : eitherNaN(a, b) ? NaN : 1),
+	/** Sine. */
+	sin: unary("sin", (x) => Math.sin(x), (x) => Math.cos(x)),
+	/** Cosine. */
+	cos: unary("cos", (x) => Math.cos(x), (x) => -Math.sin(x)),
+	/** Hyperbolic tangent. */
+	tanh: unary("tanh", (x) => Math.tanh(x), (x) => {
+		const e = Math.exp(-2 * Math.abs(x));
+		const s = 1 + e;
+		return 4 * e / (s * s);
+	}),
+	/** Logistic sigmoid `1 / (1 + e^-x)`, stable for any `x`. */
+	sigmoid: unary("sigmoid", sigmoidValue, sigmoidDeriv),
+	/**
+	* 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: unary("softplus", (x) => x > 0 ? x + Math.log1p(Math.exp(-x)) : Math.log1p(Math.exp(x)), (x) => sigmoidValue(x))
+});
+/** The names of the one-argument primitives, in table order. */
+const unaryNames = [
+	"neg",
+	"recip",
+	"square",
+	"sqrt",
+	"exp",
+	"expm1",
+	"log",
+	"log1p",
+	"abs",
+	"sin",
+	"cos",
+	"tanh",
+	"sigmoid",
+	"softplus"
+];
+/** The names of the two-argument primitives, in table order. */
+const binaryNames = [
+	"add",
+	"sub",
+	"mul",
+	"div",
+	"pow",
+	"min",
+	"max"
+];
+// src/arithmetic.ts
+/**
+* The operations with a plain-number operand, each the binary primitive `of` with one operand a
+* constant: the first one when `constantFirst`, otherwise the second. Their values and partials
+* are that primitive's, from the table.
+*/
+const constantOperandOps = {
+	addc: {
+		of: "add",
+		constantFirst: false
+	},
+	subc: {
+		of: "sub",
+		constantFirst: false
+	},
+	csub: {
+		of: "sub",
+		constantFirst: true
+	},
+	mulc: {
+		of: "mul",
+		constantFirst: false
+	},
+	divc: {
+		of: "div",
+		constantFirst: false
+	},
+	cdiv: {
+		of: "div",
+		constantFirst: true
+	},
+	powc: {
+		of: "pow",
+		constantFirst: false
+	}
+};
+/**
+* {@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
+* ```
+*/
+const plain = {
+	constant: (x) => x,
+	value: (a) => a,
+	neg: primitives.neg.value,
+	add: primitives.add.value,
+	sub: primitives.sub.value,
+	mul: primitives.mul.value,
+	div: primitives.div.value,
+	recip: primitives.recip.value,
+	square: primitives.square.value,
+	sqrt: primitives.sqrt.value,
+	exp: primitives.exp.value,
+	expm1: primitives.expm1.value,
+	log: primitives.log.value,
+	log1p: primitives.log1p.value,
+	pow: primitives.pow.value,
+	abs: primitives.abs.value,
+	min: primitives.min.value,
+	max: primitives.max.value,
+	sin: primitives.sin.value,
+	cos: primitives.cos.value,
+	tanh: primitives.tanh.value,
+	sigmoid: primitives.sigmoid.value,
+	softplus: primitives.softplus.value,
+	addc: primitives.add.value,
+	subc: primitives.sub.value,
+	csub: primitives.sub.value,
+	mulc: primitives.mul.value,
+	divc: primitives.div.value,
+	cdiv: primitives.div.value,
+	powc: primitives.pow.value
+};
+// src/capacity.ts
+/** `capacity` if it is a positive integer, the default if it is not given; otherwise throws. */
+function initialCapacity(capacity, owner) {
+	if (capacity === void 0) return 1024;
+	if (!Number.isInteger(capacity) || capacity < 1) throw new RangeError(`${owner}: capacity must be a positive integer, not ${String(capacity)}`);
+	return capacity;
+}
+// src/debug.ts
+/** Indices fit in 31 bits (parents are stored in an Int32Array). */
+const STRIDE = 2 ** 31;
+/** Epochs run from 1 to EPOCHS - 1, so that a handle stays below 2^52, an exact integer. */
+const EPOCHS = 2 ** 21;
+let lastEpoch = 0;
+/**
+* A fresh epoch, unique among all debug tapes and Forwards until 2^21 - 1 epochs have been used,
+* after which numbering wraps around; a stale handle could then be mistaken for a live one only if
+* it were used exactly that many clears later, at the same index.
+*/
+function nextEpoch() {
+	lastEpoch = lastEpoch % (EPOCHS - 1) + 1;
+	return lastEpoch;
+}
+/** The handles of one debug Tape or Forward: issuing them and checking them. */
+var Handles = class {
+	epoch = 0;
+	/** Every epoch this instance has used, to tell its own stale handles from another's. */
+	own = /* @__PURE__ */ new Set();
+	/** The epoch each slot was last written in. */
+	slotEpoch = /* @__PURE__ */ new Int32Array(64);
+	kind;
+	first;
+	target;
+	constructor(kind, first, target) {
+		this.kind = kind;
+		this.first = first;
+		this.target = target;
+		this.begin();
+	}
+	/** Start a new epoch: handles issued from now on are told apart from earlier ones. */
+	begin() {
+		this.epoch = nextEpoch();
+		this.own.add(this.epoch);
+	}
+	/** The handle for the slot `index` just written. */
+	issue(index) {
+		while (index >= this.slotEpoch.length) {
+			const grown = new Int32Array(this.slotEpoch.length * 2);
+			grown.set(this.slotEpoch);
+			this.slotEpoch = grown;
+		}
+		this.slotEpoch[index] = this.epoch;
+		return this.epoch * STRIDE + index;
+	}
+	/**
+	* Throw if `value`, given where a plain number belongs, is one of this instance's variables: what
+	* a variable mistaken for a number looks like, typically after a `typeof x === 'number'` test,
+	* which every variable passes. Only this instance's handles are recognised, so that no ordinary
+	* number is ever refused: a handle is a whole number of 2^31 or more, encoding an epoch of this
+	* instance and a slot written in that epoch.
+	*/
+	checkNumber(value, where) {
+		if (typeof value !== "number" || !Number.isSafeInteger(value)) return;
+		const epoch = Math.floor(value / STRIDE);
+		const index = value - epoch * STRIDE;
+		if (this.own.has(epoch) && this.slotEpoch[index] === epoch) throw new RangeError(`${where} is a variable, where a plain number belongs. A variable is a number at run time, so typeof x === 'number' is true for it too: keep variables and numbers apart instead.`);
+	}
+	/** The slot index of `handle`, or a `RangeError` saying what is wrong with it. */
+	resolve(handle, where) {
+		if (typeof handle !== "number" || !Number.isSafeInteger(handle) || handle < 0) throw new RangeError(`${where} is not a variable (it is ${String(handle)})`);
+		const epoch = Math.floor(handle / STRIDE);
+		const index = handle - epoch * STRIDE;
+		if (epoch === 0) throw new RangeError(`${where} is the plain number ${String(handle)}, not a variable of this ${this.kind}. Numbers enter through constant() or input(), or as the number operand of addc(), mulc() and the like. Do not tell variables from numbers with typeof: both are numbers.`);
+		if (!this.own.has(epoch)) throw new RangeError(`${where} is a variable of another Tape or Forward`);
+		if (index >= this.first + this.target.size || this.slotEpoch[index] !== epoch) throw new RangeError(`${where} is stale: its node was discarded by clear() or rewind()`);
+		return index;
+	}
+};
+const arithmetic = {
+	constant: [["n"], "v"],
+	value: [["v"], "-"]
+};
+for (const name of unaryNames) arithmetic[name] = [["v"], "v"];
+for (const name of binaryNames) arithmetic[name] = [["v", "v"], "v"];
+for (const [name, { constantFirst }] of Object.entries(constantOperandOps)) arithmetic[name] = [constantFirst ? ["n", "v"] : ["v", "n"], "v"];
+const signatures = {
+	Tape: {
+		...arithmetic,
+		input: [["n"], "v"],
+		inputs: [["ns"], "vs"],
+		backward: [["v", "n"], "-"],
+		vjp: [["vs", "-"], "-"],
+		adjoint: [["v"], "-"],
+		adjoints: [["vs", "-"], "-"],
+		gradient: [[
+			"v",
+			"vs",
+			"-"
+		], "-"]
+	},
+	Forward: {
+		...arithmetic,
+		input: [["n", "n"], "v"],
+		tangent: [["v"], "-"]
+	}
+};
+/**
+* Turn `target`, a freshly constructed Tape or Forward, into its debug version. `first` is the
+* index of its first slot (1 for a Tape, whose slot 0 is reserved; 0 for a Forward).
+*/
+function installChecks(target, kind, first) {
+	const handles = new Handles(kind, first, target);
+	const self = target;
+	const proto = Object.getPrototypeOf(target);
+	const element = (where, k) => `${where}, element ${String(k + 1)}`;
+	const decode = (arg, value, where) => {
+		switch (arg) {
+			case "v": return handles.resolve(value, where);
+			case "vs": return value.map((h, k) => handles.resolve(h, element(where, k)));
+			case "n":
+				handles.checkNumber(value, where);
+				return value;
+			case "ns":
+				Array.from(value, (x, k) => {
+					handles.checkNumber(x, element(where, k));
+				});
+				return value;
+			case "-": return value;
+		}
+	};
+	const encode = (arg, value) => arg === "v" ? handles.issue(value) : arg === "vs" ? value.map((i) => handles.issue(i)) : value;
+	for (const [name, [args, result]] of Object.entries(signatures[kind])) {
+		const run = name === "gradient" ? (output, inputs, out) => {
+			proto.backward.call(target, output);
+			return proto.adjoints.call(target, inputs, out);
+		} : (...decoded) => proto[name].apply(target, decoded);
+		self[name] = (...params) => {
+			const decoded = params.map((p, i) => decode(args[i] ?? "-", p, `${kind}.${name}: argument ${String(i + 1)}`));
+			return encode(result, run(...decoded));
+		};
+	}
+	self.clear = () => {
+		proto.clear.call(target);
+		handles.begin();
+	};
+	if (kind === "Tape") self.rewind = (mark) => {
+		proto.rewind.call(target, mark);
+		handles.begin();
+	};
+}
+// src/tape.ts
+/**
+* Slot 0 of every array is a sink, not a node: leaves name it as both parents, and unary nodes as
+* their second, always with a zero partial. Every parent index is therefore a valid slot, and the
+* backward sweep's zero rule never writes to the sink.
+*/
+const SINK = 0;
+/**
+* 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)
+* ```
+*/
+var Tape = class {
+	val;
+	pa;
+	pb;
+	da;
+	db;
+	adj;
+	/** The next free slot; nodes occupy slots 1 to n - 1. */
+	n = 1;
+	/** An empty tape; see {@link TapeOptions}. */
+	constructor(options = {}) {
+		const cap = initialCapacity(options.capacity, "Tape") + 1;
+		this.val = new Float64Array(cap);
+		this.pa = new Int32Array(cap);
+		this.pb = new Int32Array(cap);
+		this.da = new Float64Array(cap);
+		this.db = new Float64Array(cap);
+		this.adj = new Float64Array(cap);
+		if (options.debug === true) installChecks(this, "Tape", 1);
+	}
+	/** The number of nodes recorded so far. */
+	get size() {
+		return this.n - 1;
+	}
+	/** The number of nodes the tape can hold before it next grows. */
+	get capacity() {
+		return this.val.length - 1;
+	}
+	/** Forget every node, keeping the storage. Every `Var` previously issued becomes invalid. */
+	clear() {
+		this.n = 1;
+	}
+	/**
+	* 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() {
+		return this.n;
+	}
+	/**
+	* 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) {
+		if (mark > this.n || mark < 1) throw new RangeError(`Tape.rewind: mark ${mark} is outside the tape (size ${this.size})`);
+		this.n = mark;
+	}
+	/**
+	* 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) {
+		return this.push(x, SINK, 0, SINK, 0);
+	}
+	inputs(xs) {
+		return Array.from(xs, (x) => this.push(x, SINK, 0, SINK, 0));
+	}
+	/**
+	* 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) {
+		return this.push(x, SINK, 0, SINK, 0);
+	}
+	/**
+	* 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) {
+		return this.val[a];
+	}
+	/**
+	* 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, seed = 1) {
+		if (output < 1 || output >= this.n) throw new RangeError(`Tape.backward: ${output} is not a node of this tape (size ${this.size})`);
+		const adj = this.adj;
+		adj.fill(0, 0, output + 1);
+		adj[output] = seed;
+		this.sweep(output);
+	}
+	/**
+	* 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, weights) {
+		if (outputs.length !== weights.length) throw new RangeError(`Tape.vjp: ${outputs.length} outputs but ${weights.length} weights`);
+		let top = 0;
+		for (const o of outputs) {
+			if (o < 1 || o >= this.n) throw new RangeError(`Tape.vjp: ${o} is not a node of this tape (size ${this.size})`);
+			top = Math.max(top, o);
+		}
+		const adj = this.adj;
+		if (outputs.length === 0) {
+			adj.fill(0);
+			return;
+		}
+		adj.fill(0, 0, top + 1);
+		outputs.forEach((o, k) => {
+			adj[o] = adj[o] + weights[k];
+		});
+		this.sweep(top);
+	}
+	/**
+	* 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) {
+		return this.adj[v];
+	}
+	/**
+	* 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, out = new Float64Array(vars.length)) {
+		const adj = this.adj;
+		vars.forEach((v, k) => {
+			out[k] = adj[v];
+		});
+		return out;
+	}
+	/**
+	* `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, inputs, out) {
+		this.backward(output);
+		return this.adjoints(inputs, out);
+	}
+	sweep(top) {
+		const adj = this.adj, pa = this.pa, pb = this.pb, da = this.da, db = this.db;
+		for (let i = top; i > SINK; i--) {
+			const g = adj[i];
+			if (g === 0) continue;
+			const dA = da[i];
+			if (dA !== 0) {
+				const a = pa[i];
+				adj[a] = adj[a] + dA * g;
+			}
+			const dB = db[i];
+			if (dB !== 0) {
+				const b = pb[i];
+				adj[b] = adj[b] + dB * g;
+			}
+		}
+	}
+	push(y, a, dA, b, dB) {
+		const i = this.n;
+		if (i === this.val.length) this.grow();
+		this.val[i] = y;
+		this.pa[i] = a;
+		this.da[i] = dA;
+		this.pb[i] = b;
+		this.db[i] = dB;
+		this.n = i + 1;
+		return i;
+	}
+	grow() {
+		const cap = this.val.length * 2;
+		const val = new Float64Array(cap);
+		val.set(this.val);
+		this.val = val;
+		const pa = new Int32Array(cap);
+		pa.set(this.pa);
+		this.pa = pa;
+		const pb = new Int32Array(cap);
+		pb.set(this.pb);
+		this.pb = pb;
+		const da = new Float64Array(cap);
+		da.set(this.da);
+		this.da = da;
+		const db = new Float64Array(cap);
+		db.set(this.db);
+		this.db = db;
+		const adj = new Float64Array(cap);
+		adj.set(this.adj);
+		this.adj = adj;
+	}
+	/** `-a`. */
+	neg(a) {
+		const x = this.val[a];
+		const y = primitives.neg.value(x);
+		return this.push(y, a, primitives.neg.deriv(x, y), SINK, 0);
+	}
+	/** `a + b`. */
+	add(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.add.value(x, z);
+		return this.push(y, a, primitives.add.da(x, z, y), b, primitives.add.db(x, z, y));
+	}
+	/** `a - b`. */
+	sub(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.sub.value(x, z);
+		return this.push(y, a, primitives.sub.da(x, z, y), b, primitives.sub.db(x, z, y));
+	}
+	/** `a * b`. */
+	mul(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.mul.value(x, z);
+		return this.push(y, a, primitives.mul.da(x, z, y), b, primitives.mul.db(x, z, y));
+	}
+	/** `a / b`. */
+	div(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.div.value(x, z);
+		return this.push(y, a, primitives.div.da(x, z, y), b, primitives.div.db(x, z, y));
+	}
+	/** `1 / a`. */
+	recip(a) {
+		const x = this.val[a];
+		const y = primitives.recip.value(x);
+		return this.push(y, a, primitives.recip.deriv(x, y), SINK, 0);
+	}
+	/** `a * a`, one node instead of a `mul` of `a` with itself. */
+	square(a) {
+		const x = this.val[a];
+		const y = primitives.square.value(x);
+		return this.push(y, a, primitives.square.deriv(x, y), SINK, 0);
+	}
+	/** `sqrt(a)`; its derivative at `0` is `+Infinity`. */
+	sqrt(a) {
+		const x = this.val[a];
+		const y = primitives.sqrt.value(x);
+		return this.push(y, a, primitives.sqrt.deriv(x, y), SINK, 0);
+	}
+	/** `e^a`. */
+	exp(a) {
+		const x = this.val[a];
+		const y = primitives.exp.value(x);
+		return this.push(y, a, primitives.exp.deriv(x, y), SINK, 0);
+	}
+	/** `e^a - 1`, accurate for small `a`. */
+	expm1(a) {
+		const x = this.val[a];
+		const y = primitives.expm1.value(x);
+		return this.push(y, a, primitives.expm1.deriv(x, y), SINK, 0);
+	}
+	/** Natural logarithm. */
+	log(a) {
+		const x = this.val[a];
+		const y = primitives.log.value(x);
+		return this.push(y, a, primitives.log.deriv(x, y), SINK, 0);
+	}
+	/** `log(1 + a)`, accurate for small `a`. */
+	log1p(a) {
+		const x = this.val[a];
+		const y = primitives.log1p.value(x);
+		return this.push(y, a, primitives.log1p.deriv(x, y), SINK, 0);
+	}
+	/**
+	* `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, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.pow.value(x, z);
+		return this.push(y, a, primitives.pow.da(x, z, y), b, primitives.pow.db(x, z, y));
+	}
+	/** `|a|`; its derivative at `0` is `0`. */
+	abs(a) {
+		const x = this.val[a];
+		const y = primitives.abs.value(x);
+		return this.push(y, a, primitives.abs.deriv(x, y), SINK, 0);
+	}
+	/** The smaller of `a` and `b`; on a tie the derivative flows to `a`. */
+	min(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.min.value(x, z);
+		return this.push(y, a, primitives.min.da(x, z, y), b, primitives.min.db(x, z, y));
+	}
+	/** The larger of `a` and `b`; on a tie the derivative flows to `a`. */
+	max(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const y = primitives.max.value(x, z);
+		return this.push(y, a, primitives.max.da(x, z, y), b, primitives.max.db(x, z, y));
+	}
+	/** Sine. */
+	sin(a) {
+		const x = this.val[a];
+		const y = primitives.sin.value(x);
+		return this.push(y, a, primitives.sin.deriv(x, y), SINK, 0);
+	}
+	/** Cosine. */
+	cos(a) {
+		const x = this.val[a];
+		const y = primitives.cos.value(x);
+		return this.push(y, a, primitives.cos.deriv(x, y), SINK, 0);
+	}
+	/** Hyperbolic tangent. */
+	tanh(a) {
+		const x = this.val[a];
+		const y = primitives.tanh.value(x);
+		return this.push(y, a, primitives.tanh.deriv(x, y), SINK, 0);
+	}
+	/** Logistic sigmoid `1 / (1 + e^-a)`, stable for any `a`. */
+	sigmoid(a) {
+		const x = this.val[a];
+		const y = primitives.sigmoid.value(x);
+		return this.push(y, a, primitives.sigmoid.deriv(x, y), SINK, 0);
+	}
+	/** Softplus `log(1 + e^a)`, stable for any `a`; its derivative is `sigmoid(a)`. */
+	softplus(a) {
+		const x = this.val[a];
+		const y = primitives.softplus.value(x);
+		return this.push(y, a, primitives.softplus.deriv(x, y), SINK, 0);
+	}
+	/**
+	* `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, c) {
+		const x = this.val[a];
+		const y = primitives.add.value(x, c);
+		return this.push(y, a, primitives.add.da(x, c, y), SINK, 0);
+	}
+	/** `a - c` for a plain number `c`; `sub(a, constant(c))` in one node. */
+	subc(a, c) {
+		const x = this.val[a];
+		const y = primitives.sub.value(x, c);
+		return this.push(y, a, primitives.sub.da(x, c, y), SINK, 0);
+	}
+	/** `c - a` for a plain number `c`; `sub(constant(c), a)` in one node. */
+	csub(c, a) {
+		const x = this.val[a];
+		const y = primitives.sub.value(c, x);
+		return this.push(y, a, primitives.sub.db(c, x, y), SINK, 0);
+	}
+	/** `a * c` for a plain number `c`; `mul(a, constant(c))` in one node. */
+	mulc(a, c) {
+		const x = this.val[a];
+		const y = primitives.mul.value(x, c);
+		return this.push(y, a, primitives.mul.da(x, c, y), SINK, 0);
+	}
+	/** `a / c` for a plain number `c`; `div(a, constant(c))` in one node. */
+	divc(a, c) {
+		const x = this.val[a];
+		const y = primitives.div.value(x, c);
+		return this.push(y, a, primitives.div.da(x, c, y), SINK, 0);
+	}
+	/** `c / a` for a plain number `c`; `div(constant(c), a)` in one node. */
+	cdiv(c, a) {
+		const x = this.val[a];
+		const y = primitives.div.value(c, x);
+		return this.push(y, a, primitives.div.db(c, x, y), SINK, 0);
+	}
+	/**
+	* `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, c) {
+		const x = this.val[a];
+		const y = primitives.pow.value(x, c);
+		return this.push(y, a, primitives.pow.da(x, c, y), SINK, 0);
+	}
+};
+// src/forward.ts
+/**
+* One term of the chain rule, `d * t`, except that a zero factor makes the term zero even when the
+* other factor is infinite or `NaN`. The tape's backward sweep applies the same rule.
+*/
+function times(d, t) {
+	return d === 0 || t === 0 ? 0 : d * t;
+}
+/**
+* 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)
+* ```
+*/
+var Forward = class {
+	val;
+	tan;
+	n = 0;
+	/** An empty forward-mode context; see {@link ForwardOptions}. */
+	constructor(options = {}) {
+		const cap = initialCapacity(options.capacity, "Forward");
+		this.val = new Float64Array(cap);
+		this.tan = new Float64Array(cap);
+		if (options.debug === true) installChecks(this, "Forward", 0);
+	}
+	/** The number of values created so far. */
+	get size() {
+		return this.n;
+	}
+	/** Forget every value, keeping the storage. Every `Dual` previously issued becomes invalid. */
+	clear() {
+		this.n = 0;
+	}
+	/** An input with value `x` and tangent (seed) `tangent`: its component of the direction. */
+	input(x, tangent) {
+		return this.push(x, tangent);
+	}
+	/**
+	* 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) {
+		return this.push(x, 0);
+	}
+	/**
+	* 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) {
+		return this.val[a];
+	}
+	/** The tangent of `a`: its derivative along the direction the inputs were seeded with. */
+	tangent(a) {
+		return this.tan[a];
+	}
+	push(y, t) {
+		const i = this.n;
+		if (i === this.val.length) this.grow();
+		this.val[i] = y;
+		this.tan[i] = t;
+		this.n = i + 1;
+		return i;
+	}
+	grow() {
+		const cap = this.val.length * 2;
+		const val = new Float64Array(cap);
+		val.set(this.val);
+		this.val = val;
+		const tan = new Float64Array(cap);
+		tan.set(this.tan);
+		this.tan = tan;
+	}
+	/** `-a`. */
+	neg(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.neg.value(x);
+		return this.push(y, primitives.neg.deriv(x, y) * ta);
+	}
+	/** `a + b`. */
+	add(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.add.value(x, z);
+		return this.push(y, primitives.add.da(x, z, y) * ta + primitives.add.db(x, z, y) * tb);
+	}
+	/** `a - b`. */
+	sub(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.sub.value(x, z);
+		return this.push(y, primitives.sub.da(x, z, y) * ta + primitives.sub.db(x, z, y) * tb);
+	}
+	/** `a * b`. */
+	mul(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.mul.value(x, z);
+		return this.push(y, times(primitives.mul.da(x, z, y), ta) + times(primitives.mul.db(x, z, y), tb));
+	}
+	/** `a / b`. */
+	div(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.div.value(x, z);
+		return this.push(y, times(primitives.div.da(x, z, y), ta) + times(primitives.div.db(x, z, y), tb));
+	}
+	/** `1 / a`. */
+	recip(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.recip.value(x);
+		return this.push(y, times(primitives.recip.deriv(x, y), ta));
+	}
+	/** `a * a`, one node instead of a `mul` of `a` with itself. */
+	square(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.square.value(x);
+		return this.push(y, times(primitives.square.deriv(x, y), ta));
+	}
+	/** `sqrt(a)`; its derivative at `0` is `+Infinity`. */
+	sqrt(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.sqrt.value(x);
+		return this.push(y, times(primitives.sqrt.deriv(x, y), ta));
+	}
+	/** `e^a`. */
+	exp(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.exp.value(x);
+		return this.push(y, times(primitives.exp.deriv(x, y), ta));
+	}
+	/** `e^a - 1`, accurate for small `a`. */
+	expm1(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.expm1.value(x);
+		return this.push(y, times(primitives.expm1.deriv(x, y), ta));
+	}
+	/** Natural logarithm. */
+	log(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.log.value(x);
+		return this.push(y, times(primitives.log.deriv(x, y), ta));
+	}
+	/** `log(1 + a)`, accurate for small `a`. */
+	log1p(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.log1p.value(x);
+		return this.push(y, times(primitives.log1p.deriv(x, y), ta));
+	}
+	/**
+	* `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, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.pow.value(x, z);
+		return this.push(y, times(primitives.pow.da(x, z, y), ta) + times(primitives.pow.db(x, z, y), tb));
+	}
+	/** `|a|`; its derivative at `0` is `0`. */
+	abs(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.abs.value(x);
+		return this.push(y, times(primitives.abs.deriv(x, y), ta));
+	}
+	/** The smaller of `a` and `b`; on a tie the derivative flows to `a`. */
+	min(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.min.value(x, z);
+		return this.push(y, times(primitives.min.da(x, z, y), ta) + times(primitives.min.db(x, z, y), tb));
+	}
+	/** The larger of `a` and `b`; on a tie the derivative flows to `a`. */
+	max(a, b) {
+		const x = this.val[a];
+		const z = this.val[b];
+		const ta = this.tan[a];
+		const tb = this.tan[b];
+		const y = primitives.max.value(x, z);
+		return this.push(y, times(primitives.max.da(x, z, y), ta) + times(primitives.max.db(x, z, y), tb));
+	}
+	/** Sine. */
+	sin(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.sin.value(x);
+		return this.push(y, times(primitives.sin.deriv(x, y), ta));
+	}
+	/** Cosine. */
+	cos(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.cos.value(x);
+		return this.push(y, times(primitives.cos.deriv(x, y), ta));
+	}
+	/** Hyperbolic tangent. */
+	tanh(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.tanh.value(x);
+		return this.push(y, times(primitives.tanh.deriv(x, y), ta));
+	}
+	/** Logistic sigmoid `1 / (1 + e^-a)`, stable for any `a`. */
+	sigmoid(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.sigmoid.value(x);
+		return this.push(y, times(primitives.sigmoid.deriv(x, y), ta));
+	}
+	/** Softplus `log(1 + e^a)`, stable for any `a`; its derivative is `sigmoid(a)`. */
+	softplus(a) {
+		const x = this.val[a];
+		const ta = this.tan[a];
+		const y = primitives.softplus.value(x);
+		return this.push(y, times(primitives.softplus.deriv(x, y), ta));
+	}
+	/**
+	* `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, c) {
+		const x = this.val[a];
+		const y = primitives.add.value(x, c);
+		return this.push(y, times(primitives.add.da(x, c, y), this.tan[a]));
+	}
+	/** `a - c` for a plain number `c`; `sub(a, constant(c))` in one node. */
+	subc(a, c) {
+		const x = this.val[a];
+		const y = primitives.sub.value(x, c);
+		return this.push(y, times(primitives.sub.da(x, c, y), this.tan[a]));
+	}
+	/** `c - a` for a plain number `c`; `sub(constant(c), a)` in one node. */
+	csub(c, a) {
+		const x = this.val[a];
+		const y = primitives.sub.value(c, x);
+		return this.push(y, times(primitives.sub.db(c, x, y), this.tan[a]));
+	}
+	/** `a * c` for a plain number `c`; `mul(a, constant(c))` in one node. */
+	mulc(a, c) {
+		const x = this.val[a];
+		const y = primitives.mul.value(x, c);
+		return this.push(y, times(primitives.mul.da(x, c, y), this.tan[a]));
+	}
+	/** `a / c` for a plain number `c`; `div(a, constant(c))` in one node. */
+	divc(a, c) {
+		const x = this.val[a];
+		const y = primitives.div.value(x, c);
+		return this.push(y, times(primitives.div.da(x, c, y), this.tan[a]));
+	}
+	/** `c / a` for a plain number `c`; `div(constant(c), a)` in one node. */
+	cdiv(c, a) {
+		const x = this.val[a];
+		const y = primitives.div.value(c, x);
+		return this.push(y, times(primitives.div.db(c, x, y), this.tan[a]));
+	}
+	/**
+	* `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, c) {
+		const x = this.val[a];
+		const y = primitives.pow.value(x, c);
+		return this.push(y, times(primitives.pow.da(x, c, y), this.tan[a]));
+	}
+};
+// src/composites.ts
+/**
+* The sum of `xs`, added left to right; `A.constant(0)` for an empty list.
+*
+* @example
+* ```ts
+* sum(plain, [1, 2, 3]); //=> 6
+* ```
+*/
+function sum(A, xs) {
+	if (xs.length === 0) return A.constant(0);
+	let s = xs[0];
+	for (let i = 1; i < xs.length; i++) s = A.add(s, xs[i]);
+	return s;
+}
+/**
+* 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
+* ```
+*/
+function dot(A, xs, ys) {
+	if (xs.length !== ys.length) throw new RangeError(`dot: lengths differ (${xs.length} and ${ys.length})`);
+	if (xs.length === 0) return A.constant(0);
+	let s = A.mul(xs[0], ys[0]);
+	for (let i = 1; i < xs.length; i++) s = A.add(s, A.mul(xs[i], ys[i]));
+	return s;
+}
+/** The largest of the values of `xs` as a plain number; `NaN` if any of them is `NaN`. */
+function largest(A, xs) {
+	let m = -Infinity;
+	for (const x of xs) m = Math.max(m, A.value(x));
+	return m;
+}
+/**
+* `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]
+* ```
+*/
+function logsumexp(A, xs) {
+	if (xs.length === 0) throw new RangeError("logsumexp: empty list");
+	const m = largest(A, xs);
+	if (m === Infinity || m === -Infinity) {
+		const top = xs.filter((x) => A.value(x) === m);
+		return A.add(A.mul(sum(A, top), A.constant(1 / top.length)), A.constant(Math.log(top.length)));
+	}
+	const c = A.constant(m);
+	let s = A.exp(A.sub(xs[0], c));
+	for (let i = 1; i < xs.length; i++) s = A.add(s, A.exp(A.sub(xs[i], c)));
+	return A.add(c, A.log(s));
+}
+/**
+* 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]
+* ```
+*/
+function softmax(A, xs) {
+	if (xs.length === 0) throw new RangeError("softmax: empty list");
+	const m = largest(A, xs);
+	if (m === Infinity || m === -Infinity) {
+		const k = xs.filter((x) => A.value(x) === m).length;
+		return xs.map((x) => A.constant(A.value(x) === m ? 1 / k : 0));
+	}
+	const c = A.constant(m);
+	const es = xs.map((x) => A.exp(A.sub(x, c)));
+	const inv = A.recip(sum(A, es));
+	return es.map((e) => A.mul(e, inv));
+}
+// src/convenience.ts
+/**
+* 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
+* ```
+*/
+function evaluate(f, at) {
+	return f(plain, at);
+}
+/**
+* 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] }
+* ```
+*/
+function gradient(f, at, tape = new Tape()) {
+	tape.clear();
+	const xs = tape.inputs(at);
+	const y = f(tape, xs);
+	tape.backward(y);
+	return {
+		value: tape.value(y),
+		gradient: xs.map((x) => tape.adjoint(x))
+	};
+}
+/**
+* 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 }
+* ```
+*/
+function jvp(f, at, direction, forward = new Forward()) {
+	if (direction.length !== at.length) throw new RangeError(`jvp: ${at.length} inputs but a direction of length ${direction.length}`);
+	forward.clear();
+	const y = f(forward, at.map((x, i) => forward.input(x, direction[i])));
+	return {
+		value: forward.value(y),
+		derivative: forward.tangent(y)
+	};
+}
+// src/check.ts
+/**
+* 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.
+*/
+const DEFAULT_STEP = 6e-6;
+/**
+* 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]
+* ```
+*/
+function finiteDifference(f, at, h = DEFAULT_STEP) {
+	return centralDifferences(f, at, h).map((d) => d.slope);
+}
+/** Units in the last place of error allowed for in each evaluation of `f`. */
+const ROUNDING_ULPS = 4;
+/**
+* Each component's central difference, and an estimate of the error that rounding in the two
+* evaluations of `f` puts into it: `ROUNDING_ULPS * eps * (|f(x + h)| + |f(x - h)|) / (2 h)`.
+*/
+function centralDifferences(f, at, h) {
+	const x = at.slice();
+	const point = x;
+	return at.map((xi, i) => {
+		const step = h * Math.max(1, Math.abs(xi));
+		x[i] = xi + step;
+		const up = f(plain, point);
+		x[i] = xi - step;
+		const down = f(plain, point);
+		x[i] = xi;
+		const span = xi + step - (xi - step);
+		return {
+			slope: (up - down) / span,
+			roundoff: ROUNDING_ULPS * Number.EPSILON * (Math.abs(up) + Math.abs(down)) / span
+		};
+	});
+}
+/**
+* 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
+* ```
+*/
+function checkGradient(f, at, options = {}) {
+	const { h = DEFAULT_STEP, rtol = 1e-5, atol = 1e-8 } = options;
+	const { value, gradient: analytic } = gradient(f, at);
+	const differences = centralDifferences(f, at, h);
+	const numeric = differences.map((d) => d.slope);
+	let ok = true;
+	let worst = {
+		index: -1,
+		analytic: NaN,
+		numeric: NaN,
+		error: 0,
+		allowed: 0,
+		roundoff: 0
+	};
+	let worstRatio = -1;
+	for (let i = 0; i < analytic.length; i++) {
+		const a = analytic[i];
+		const n = numeric[i];
+		const roundoff = differences[i].roundoff;
+		const error = Math.abs(a - n);
+		const allowed = atol + rtol * Math.max(Math.abs(a), Math.abs(n)) + roundoff;
+		const ratio = Number.isNaN(error) ? Infinity : error === 0 ? 0 : error / allowed;
+		if (!(error <= allowed)) ok = false;
+		if (ratio > worstRatio) {
+			worstRatio = ratio;
+			worst = {
+				index: i,
+				analytic: a,
+				numeric: n,
+				error,
+				allowed,
+				roundoff
+			};
+		}
+	}
+	return {
+		ok,
+		value,
+		analytic,
+		numeric,
+		worst
+	};
+}
+export { DEFAULT_STEP, Forward, Tape, binaryNames, checkGradient, dot, evaluate, finiteDifference, gradient, jvp, logsumexp, plain, primitives, softmax, sum, unaryNames };
+
+//# sourceMappingURL=index.js.map