@reicek/neataptic-ts 0.1.0

package/src/architecture/network/network.activate.ts

@@ -0,0 +1,223 @@
+import type Network from '../network';
+import { activationArrayPool } from '../activationArrayPool';
+
+/**
+ * Network activation helpers (forward pass utilities).
+ *
+ * This module provides progressively lower–overhead entry points for performing
+ * forward propagation through a {@link Network}. The emphasis is on:
+ *  1. Educative clarity – each step is documented so newcomers can follow the
+ *     life‑cycle of a forward pass in a neural network graph.
+ *  2. Performance – fast paths avoid unnecessary allocation and bookkeeping when
+ *     gradients / evolution traces are not needed.
+ *  3. Safety – pooled buffers are never exposed directly to the public API.
+ *
+ * Exported functions:
+ *  - {@link noTraceActivate}: ultra‑light inference (no gradients, minimal allocation).
+ *  - {@link activateRaw}: thin semantic alias around the canonical Network.activate path.
+ *  - {@link activateBatch}: simple mini‑batch loop utility.
+ *
+ * Design terminology used below:
+ *  - Topological order: a sequence of nodes such that all directed connections flow forward.
+ *  - Slab: a contiguous typed‑array structure packing node activations for vectorized math.
+ *  - Trace / gradient bookkeeping: auxiliary data (e.g. eligibility traces, derivative caches)
+ *    required for training algorithms; skipped in inference‑only modes.
+ *  - Pool: an object managing reusable arrays to reduce garbage collection pressure.
+ *
+ * @module network.activate
+ */
+
+/**
+ * Perform a forward pass without creating or updating any training / gradient traces.
+ *
+ * This is the most allocation‑sensitive activation path. Internally it will attempt
+ * to leverage a compact "fast slab" routine (an optimized, vectorized broadcast over
+ * contiguous activation buffers) when the Network instance indicates that such a path
+ * is currently valid. If that attempt fails (for instance because the slab is stale
+ * after a structural mutation) execution gracefully falls back to a node‑by‑node loop.
+ *
+ * Algorithm outline:
+ *  1. (Optional) Refresh cached topological order if the network enforces acyclicity
+ *     and a structural change marked the order as dirty.
+ *  2. Validate the input dimensionality.
+ *  3. Try the fast slab path; if it throws, continue with the standard path.
+ *  4. Acquire a pooled output buffer sized to the number of output neurons.
+ *  5. Iterate all nodes in their internal order:
+ *       - Input nodes: directly assign provided input values.
+ *       - Hidden nodes: compute activation via Node.noTraceActivate (no bookkeeping).
+ *       - Output nodes: compute activation and store it (in sequence) inside the
+ *         pooled output buffer.
+ *  6. Copy the pooled buffer into a fresh array (detaches user from the pool) and
+ *     release the pooled buffer back to the pool.
+ *
+ * Complexity considerations:
+ *  - Time: O(N + E) where N = number of nodes, E = number of inbound edges processed
+ *    inside each Node.noTraceActivate call (not explicit here but inside the node).
+ *  - Space: O(O) transient (O = number of outputs) due to the pooled output buffer.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param input - Flat numeric vector whose length must equal network.input.
+ * @returns Array of output neuron activations (length == network.output).
+ * @throws {Error} If the provided input vector length mismatches the network's input size.
+ * @example
+ * const out = net.noTraceActivate([0.1, 0.2, 0.3]);
+ * console.log(out); // => e.g. [0.5123, 0.0441]
+ * @remarks Safe for inference hot paths; not suitable when gradients / training traces are required.
+ */
+export function noTraceActivate(this: Network, input: number[]): number[] {
+  /**
+   * Reference to the network instance cast to any so internal/private helper properties
+   * (underscored fields & fast path flags) can be accessed without TypeScript complaints.
+   */
+  const self = this as any;
+
+  // Step 1: Ensure that if we require an acyclic graph, our cached topological
+  // ordering of nodes is current. A fresh order guarantees deterministic forward propagation.
+  if (self._enforceAcyclic && self._topoDirty)
+    (this as any)._computeTopoOrder();
+
+  // Step 2: Basic validation – mismatched length typically indicates a user error.
+  if (!Array.isArray(input) || input.length !== this.input) {
+    throw new Error(
+      `Input size mismatch: expected ${this.input}, got ${
+        input ? (input as any).length : 'undefined'
+      }`
+    );
+  }
+
+  // Step 3: Attempt a zero‑allocation vectorized activation over a packed slab. We wrap
+  // the call in a try/catch to avoid penalizing typical paths with conditional prechecks.
+  if ((this as any)._canUseFastSlab(false)) {
+    try {
+      return (this as any)._fastSlabActivate(input);
+    } catch {
+      // Silent fallback – correctness first; performance is opportunistic here.
+    }
+  }
+
+  // Step 4: Acquire a pooled typed array (or array‑like) sized to the number of outputs.
+  /** Pooled buffer to collect output activations in order. */
+  /**
+   * Pooled activation output buffer sized to the number of output neurons; will be cloned
+   * into a plain array before returning to the caller to avoid external mutation of pooled memory.
+   */
+  const output = activationArrayPool.acquire(this.output);
+
+  // Maintain a manual write index to decouple node iteration order from output layout.
+  /**
+   * Sequential index into the pooled output buffer. Increments each time we process
+   * an output node so we produce a dense, zero‑gap array matching logical output order.
+   */
+  /** Sequential write index into the pooled output buffer. */
+  let outIndex = 0;
+
+  // Step 5: Iterate every node once. For hidden nodes we simply invoke noTraceActivate;
+  // its internal logic will read predecessor activations already set during earlier steps.
+  this.nodes.forEach((node, index) => {
+    // Input nodes: feed value directly from the corresponding slot in the provided input vector.
+    if (node.type === 'input') node.noTraceActivate(input[index]);
+    // Output nodes: compute their activation (which implicitly uses upstream hidden/input nodes) and store.
+    else if (node.type === 'output')
+      (output as any)[outIndex++] = node.noTraceActivate();
+    // Hidden nodes: just activate (value stored internally on the node itself).
+    else node.noTraceActivate();
+  });
+
+  // Step 6: Copy pooled buffer to a fresh standard array so external callers cannot mutate
+  // the pooled object after it's released (which would create hard‑to‑trace bugs).
+  /** Detached plain array containing final output activations. */
+  /** Final detached output activation vector. */
+  const result = Array.from(output as any) as number[];
+
+  // Always release pooled resources promptly to keep memory pressure low for future calls.
+  activationArrayPool.release(output);
+
+  return result;
+}
+
+/**
+ * Thin semantic alias to the network's main activation path.
+ *
+ * At present this simply forwards to {@link Network.activate}. The indirection is useful for:
+ *  - Future differentiation between raw (immediate) activation and a mode that performs reuse /
+ *    staged batching logic.
+ *  - Providing a stable exported symbol for external tooling / instrumentation.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param input - Input vector (length == network.input).
+ * @param training - Whether to retain training traces / gradients (delegated downstream).
+ * @param maxActivationDepth - Guard against runaway recursion / cyclic activation attempts.
+ * @returns Implementation-defined result of Network.activate (typically an output vector).
+ * @example
+ * const y = net.activateRaw([0,1,0]);
+ * @remarks Keep this wrapper lightweight; heavy logic should live inside Network.activate itself.
+ */
+export function activateRaw(
+  this: Network,
+  input: number[],
+  training = false,
+  maxActivationDepth = 1000
+): any {
+  /** Access internal flags / helpers (private-ish) via a loose cast. */
+  const self = this as any;
+
+  // If the network is not reusing activation arrays there's nothing special to do – delegate.
+  if (!self._reuseActivationArrays)
+    return (this as any).activate(input, training, maxActivationDepth);
+
+  // Even when reuse is enabled we currently still just delegate; hook point for future optimization.
+  return (this as any).activate(input, training, maxActivationDepth);
+}
+
+/**
+ * Activate the network over a mini‑batch (array) of input vectors, returning a 2‑D array of outputs.
+ *
+ * This helper simply loops, invoking {@link Network.activate} (or its bound variant) for each
+ * sample. It is intentionally naive: no attempt is made to fuse operations across the batch.
+ * For very large batch sizes or performance‑critical paths consider implementing a custom
+ * vectorized backend that exploits SIMD, GPU kernels, or parallel workers.
+ *
+ * Input validation occurs per row to surface the earliest mismatch with a descriptive index.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param inputs - Array of input vectors; each must have length == network.input.
+ * @param training - Whether each activation should keep training traces.
+ * @returns 2‑D array: outputs[i] is the activation result for inputs[i].
+ * @throws {Error} If inputs is not an array, or any contained vector has an incorrect length.
+ * @example
+ * const batchOut = net.activateBatch([[0,0,1],[1,0,0],[0,1,0]]);
+ * console.log(batchOut.length); // 3 rows
+ * @remarks For small batches this is perfectly adequate and clear.
+ */
+export function activateBatch(
+  this: Network,
+  inputs: number[][],
+  training = false
+): number[][] {
+  // Global validation – ensure we can iterate as expected.
+  if (!Array.isArray(inputs))
+    throw new Error('inputs must be an array of input arrays');
+
+  /** Preallocate the output matrix at the correct height (one row per input). */
+  /** Output matrix (row-major) where each row corresponds to activation of one input vector. */
+  const out: number[][] = new Array(inputs.length);
+
+  // Iterate sequentially – early exit behavior (via throw) will surface the first invalid row.
+  for (let i = 0; i < inputs.length; i++) {
+    /** Current input vector under evaluation. */
+    /** Input vector at batch index i currently being processed. */
+    const x = inputs[i];
+    // Validate row dimensionality with a descriptive index for easier debugging.
+    if (!Array.isArray(x) || x.length !== this.input) {
+      throw new Error(
+        `Input[${i}] size mismatch: expected ${this.input}, got ${
+          x ? x.length : 'undefined'
+        }`
+      );
+    }
+    // Delegate to the network's activation (may perform tracing if training=true).
+    out[i] = (this as any).activate(x, training);
+  }
+
+  return out;
+}

package/src/architecture/network/network.connect.ts

@@ -0,0 +1,157 @@
+import type Network from '../network';
+import Node from '../node';
+import Connection from '../connection';
+
+/**
+ * Network structural mutation helpers (connect / disconnect).
+ *
+ * This module centralizes the logic for adding and removing edges (connections) between
+ * nodes in a {@link Network}. By isolating the book‑keeping here we keep the primary
+ * Network class lean and ensure consistent handling of:
+ *  - Acyclic constraints
+ *  - Multiple low‑level connections returned by composite node operations
+ *  - Gating & self‑connection invariants
+ *  - Cache invalidation (topological order + packed activation slabs)
+ *
+ * Exported functions:
+ *  - {@link connect}: Create one or more connections from a source node to a target node.
+ *  - {@link disconnect}: Remove (at most) one direct connection from source to target.
+ *
+ * Key terminology:
+ *  - Self‑connection: An edge where from === to (loop). Usually disallowed under acyclicity.
+ *  - Gating: A mechanism where a third node modulates (gates) the weight / influence of a connection.
+ *  - Slab: Packed typed‑array representation of connections for vectorized forward passes.
+ *
+ * @module network.connect
+ */
+
+/**
+ * Create and register one (or multiple) directed connection objects between two nodes.
+ *
+ * Some node types (or future composite structures) may return several low‑level connections when
+ * their {@link Node.connect} is invoked (e.g., expanded recurrent templates). For that reason this
+ * function always treats the result as an array and appends each edge to the appropriate collection.
+ *
+ * Algorithm outline:
+ *  1. (Acyclic guard) If acyclicity is enforced and the source node appears after the target node in
+ *     the network's node ordering, abort early and return an empty array (prevents back‑edge creation).
+ *  2. Delegate to sourceNode.connect(targetNode, weight) to build the raw Connection object(s).
+ *  3. For each created connection:
+ *       a. If it's a self‑connection: either ignore (acyclic mode) or store in selfconns.
+ *       b. Otherwise store in standard connections array.
+ *  4. If any connection was added, mark structural caches dirty (_topoDirty & _slabDirty) so lazy
+ *     rebuild can occur before the next forward pass.
+ *
+ * Complexity:
+ *  - Time: O(k) where k is the number of low‑level connections returned (typically 1).
+ *  - Space: O(k) new Connection instances (delegated to Node.connect).
+ *
+ * Edge cases & invariants:
+ *  - Acyclic mode silently refuses back‑edges instead of throwing (makes evolutionary search easier).
+ *  - Self‑connections are skipped entirely when acyclicity is enforced.
+ *  - Weight initialization policy is delegated to Node.connect if not explicitly provided.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param from - Source node (emits signal).
+ * @param to - Target node (receives signal).
+ * @param weight - Optional explicit initial weight value.
+ * @returns Array of created {@link Connection} objects (possibly empty if acyclicity rejected the edge).
+ * @example
+ * const [edge] = net.connect(nodeA, nodeB, 0.5);
+ * @remarks For bulk layer-to-layer wiring see higher-level utilities that iterate groups.
+ */
+export function connect(
+  this: Network,
+  from: Node,
+  to: Node,
+  weight?: number
+): Connection[] {
+  // Step 1: Acyclic pre‑check – prevents cycles by disallowing edges that point "backwards" in order.
+  if (
+    (this as any)._enforceAcyclic &&
+    this.nodes.indexOf(from) > this.nodes.indexOf(to)
+  )
+    return [];
+
+  // Step 2: Delegate creation to the node. May return >1 low‑level connections (treat generically).
+  /** Array of new connection objects produced by the source node. */
+  const connections = from.connect(to, weight);
+
+  // Step 3: Register each new connection in the appropriate collection.
+  for (const c of connections) {
+    // c: individual low‑level connection
+    if (from !== to) {
+      // Standard edge (feed‑forward or recurrent) tracked in 'connections'.
+      this.connections.push(c);
+    } else {
+      // Self‑connection: only valid when acyclicity is not enforced.
+      if ((this as any)._enforceAcyclic) continue; // Skip silently to preserve invariant.
+      this.selfconns.push(c);
+    }
+  }
+
+  // Step 4: Invalidate caches if we materially changed structure (at least one edge added).
+  if (connections.length) {
+    (this as any)._topoDirty = true; // Topological ordering must be recomputed lazily.
+    (this as any)._slabDirty = true; // Packed connection slab requires rebuild for fast activation path.
+  }
+
+  return connections; // Return created edges so caller can inspect / further manipulate (e.g., gating).
+}
+
+/**
+ * Remove (at most) one directed connection from source 'from' to target 'to'.
+ *
+ * Only a single direct edge is removed because typical graph configurations maintain at most
+ * one logical connection between a given pair of nodes (excluding potential future multi‑edge
+ * semantics). If the target edge is gated we first call {@link Network.ungate} to maintain
+ * gating invariants (ensuring the gater node's internal gate list remains consistent).
+ *
+ * Algorithm outline:
+ *  1. Choose the correct list (selfconns vs connections) based on whether from === to.
+ *  2. Linear scan to find the first edge with matching endpoints.
+ *  3. If gated, ungate to detach gater bookkeeping.
+ *  4. Splice the edge out; exit loop (only one expected).
+ *  5. Delegate per‑node cleanup via from.disconnect(to) (clears reverse references, traces, etc.).
+ *  6. Mark structural caches dirty for lazy recomputation.
+ *
+ * Complexity:
+ *  - Time: O(m) where m is length of the searched list (connections or selfconns).
+ *  - Space: O(1) extra.
+ *
+ * Idempotence: If no such edge exists we still perform node-level disconnect and flag caches dirty –
+ * this conservative approach simplifies callers (they need not pre‑check existence).
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param from - Source node.
+ * @param to - Target node.
+ * @example
+ * net.disconnect(nodeA, nodeB);
+ * @remarks For removing many edges consider higher‑level bulk utilities to avoid repeated scans.
+ */
+export function disconnect(this: Network, from: Node, to: Node): void {
+  // Step 1: Select list to search: selfconns for loops, otherwise normal connections.
+  /** Candidate list of connections to inspect for removal. */
+  const list = from === to ? this.selfconns : this.connections;
+
+  // Step 2: Linear scan – lists are typically small relative to node count; acceptable trade‑off.
+  for (let i = 0; i < list.length; i++) {
+    /** Connection currently inspected. */
+    const c = list[i];
+    if (c.from === from && c.to === to) {
+      // Found target edge
+      // Step 3: If gated, maintain gating invariants by ungating before removal.
+      if (c.gater) this.ungate(c);
+      // Step 4: Remove and exit (only one expected between a pair of nodes).
+      list.splice(i, 1);
+      break;
+    }
+  }
+
+  // Step 5: Node-level cleanup (clears internal references, derivative / eligibility traces, etc.).
+  from.disconnect(to);
+
+  // Step 6: Structural mutation => mark caches dirty so next activation can rebuild fast-path artifacts.
+  (this as any)._topoDirty = true;
+  (this as any)._slabDirty = true;
+}

package/src/architecture/network/network.deterministic.ts

@@ -0,0 +1,167 @@
+import type Network from '../network';
+
+/**
+ * Deterministic pseudo‑random number generation (PRNG) utilities for {@link Network}.
+ *
+ * Why this module exists:
+ *  - Facilitates reproducible evolutionary runs / gradient training by allowing explicit seeding.
+ *  - Centralizes RNG state management & snapshot/restore operations (useful for rollbacks or
+ *    deterministic tests around mutation sequences).
+ *  - Keeps the core Network class focused by extracting ancillary RNG concerns.
+ *
+ * Implementation notes:
+ *  - Uses a small, fast 32‑bit xorshift / mix style generator (same semantics as the legacy inline version)
+ *    combining an additive Weyl sequence step plus a few avalanche-style integer mixes.
+ *  - Not cryptographically secure. Do not use for security / fairness sensitive applications.
+ *  - Produces floating point numbers in [0,1) with 2^32 (~4.29e9) discrete possible mantissa states.
+ *
+ * Public surface:
+ *  - {@link setSeed}: Initialize deterministic generator with a numeric seed.
+ *  - {@link snapshotRNG}: Capture current training step + raw internal RNG state.
+ *  - {@link restoreRNG}: Provide an externally saved RNG function (advanced) & clear stored state.
+ *  - {@link getRNGState} / {@link setRNGState}: Low-level accessors for the internal 32‑bit state word.
+ *  - {@link getRandomFn}: Retrieve the active random() function reference (primarily for tests / tooling).
+ *
+ * Design rationale:
+ *  - Storing both a state integer (_rngState) and a function (_rand) allows hot-swapping alternative
+ *    RNG implementations (e.g., for benchmarking or pluggable randomness strategies) without rewriting
+ *    callsites inside Network algorithms.
+ *
+ * @module network.deterministic
+ */
+
+/** Shape of an RNG snapshot object. */
+export interface RNGSnapshot {
+  step: number | undefined;
+  state: number | undefined;
+}
+
+/**
+ * Seed the internal PRNG and install a deterministic random() implementation on the Network instance.
+ *
+ * Process:
+ *  1. Coerce the provided seed to an unsigned 32‑bit integer (>>> 0) for predictable wraparound behavior.
+ *  2. Define an inline closure that advances an internal 32‑bit state using:
+ *       a. A Weyl increment (adding constant 0x6D2B79F5 each call) ensuring full-period traversal of
+ *          the 32‑bit space when combined with mixing.
+ *       b. Two rounds of xorshift / integer mixing (xor, shifts, multiplications) to decorrelate bits.
+ *       c. Normalization to [0,1) by dividing the final 32‑bit unsigned integer by 2^32.
+ *
+ * Bit-mixing explanation (rough intuition):
+ *  - XOR with shifted versions spreads high-order entropy to lower bits.
+ *  - Multiplication (Math.imul) with carefully chosen odd constants introduces non-linear mixing.
+ *  - The final right shift & xor avalanche aims to reduce sequential correlation.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param seed - Any finite number; only its lower 32 bits are used.
+ * @example
+ * net.setSeed(1234);
+ * const a = net.getRandomFn()(); // deterministic given the seed
+ * net.setSeed(1234);
+ * const b = net.getRandomFn()(); // a === b
+ */
+export function setSeed(this: Network, seed: number): void {
+  // Store 32-bit unsigned state (bitwise ops in JS operate on signed 32-bit but we keep consistency via >>> 0).
+  (this as any)._rngState = seed >>> 0;
+  // Install PRNG closure referencing _rngState by name for mutation on each invocation.
+  (this as any)._rand = () => {
+    // Add Weyl constant (chosen odd constant) & coerce to uint32 wraparound.
+    (this as any)._rngState = ((this as any)._rngState + 0x6d2b79f5) >>> 0;
+    // First mix: xor with shifted self and multiply (Math.imul preserves 32-bit overflow semantics).
+    let r = Math.imul(
+      (this as any)._rngState ^ ((this as any)._rngState >>> 15),
+      1 | (this as any)._rngState
+    );
+    // Second mix: avalanche style bit diffusion.
+    r ^= r + Math.imul(r ^ (r >>> 7), 61 | r);
+    // Final xor/shift; convert to unsigned, then scale to [0,1).
+    return ((r ^ (r >>> 14)) >>> 0) / 4294967296; // 2^32
+  };
+}
+
+/**
+ * Capture a snapshot of the RNG state together with the network's training step.
+ *
+ * Useful for implementing speculative evolutionary mutations where you may revert both the
+ * structural change and the randomness timeline if accepting/rejecting a candidate.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @returns Object containing current training step & 32‑bit RNG state (both possibly undefined if unseeded).
+ * @example
+ * const snap = net.snapshotRNG();
+ * // ... perform operations
+ * net.setRNGState(snap.state!);
+ */
+export function snapshotRNG(this: Network): RNGSnapshot {
+  return { step: (this as any)._trainingStep, state: (this as any)._rngState };
+}
+
+/**
+ * Restore a previously captured RNG function implementation (advanced usage).
+ *
+ * This does NOT rehydrate _rngState (it explicitly sets it to undefined). Intended for scenarios
+ * where a caller has customly serialized a full RNG closure or wants to inject a deterministic stub.
+ * If you only need to restore the raw state word produced by {@link snapshotRNG}, prefer
+ * {@link setRNGState} instead.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param fn - Function returning a pseudo‑random number in [0,1). Caller guarantees determinism if required.
+ * @example
+ * const original = net.getRandomFn();
+ * net.restoreRNG(() => 0.5); // force constant RNG for a test
+ * // ... test invariants ...
+ * net.restoreRNG(original); // restore
+ */
+export function restoreRNG(this: Network, fn: () => number): void {
+  (this as any)._rand = fn;
+  (this as any)._rngState = undefined;
+}
+
+/**
+ * Get the current internal 32‑bit RNG state value.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @returns Unsigned 32‑bit state integer or undefined if generator not yet seeded or was reset.
+ */
+export function getRNGState(this: Network): number | undefined {
+  return (this as any)._rngState as number | undefined;
+}
+
+/**
+ * Explicitly set (override) the internal 32‑bit RNG state without changing the generator function.
+ *
+ * This is a low‑level operation; typical clients should call {@link setSeed}. Provided for advanced
+ * replay functionality where the same PRNG algorithm is assumed but you want to resume exactly at a
+ * known state word.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @param state - Any finite number (only low 32 bits used). Ignored if not numeric.
+ */
+export function setRNGState(this: Network, state: number): void {
+  if (typeof state === 'number') (this as any)._rngState = state >>> 0;
+}
+
+/**
+ * Retrieve the active random function reference (for testing, instrumentation, or swapping).
+ *
+ * Mutating the returned function's closure variables (if any) is not recommended; prefer using
+ * higher-level APIs (setSeed / restoreRNG) to manage state.
+ *
+ * @param this - Bound {@link Network} instance.
+ * @returns Function producing numbers in [0,1). May be undefined if never seeded (call setSeed first).
+ */
+export function getRandomFn(this: Network): (() => number) | undefined {
+  return (this as any)._rand as () => number;
+}
+
+/**
+ * Default export bundle for convenient named imports.
+ */
+export default {
+  setSeed,
+  snapshotRNG,
+  restoreRNG,
+  getRNGState,
+  setRNGState,
+  getRandomFn,
+};