@reicek/neataptic-ts 0.1.0

package/src/neat/neat.lineage.ts

@@ -0,0 +1,220 @@
+/**
+ * Lineage / ancestry analysis helpers for NEAT populations.
+ *
+ * These utilities were migrated from the historical implementation inside `src/neat.ts`
+ * to keep core NEAT logic lean while still exposing educational metrics for users who
+ * want to introspect evolutionary diversity.
+ *
+ * Glossary:
+ *  - Genome: An individual network encoding (has a unique `_id` and optional `_parents`).
+ *  - Ancestor Window: A shallow breadth‑first window (default depth = 4) over the lineage graph.
+ *  - Jaccard Distance: 1 - |A ∩ B| / |A ∪ B|, measuring dissimilarity between two sets.
+ */
+
+/**
+ * Minimal shape assumed for a genome inside the NEAT population. Additional properties are
+ * intentionally left open (index signature) because user implementations may extend genomes.
+ */
+export interface GenomeLike {
+  /** Unique numeric identifier assigned when the genome is created. */
+  _id: number;
+  /** Optional list of parent genome IDs (could be 1 or 2 for sexual reproduction, or more in custom ops). */
+  _parents?: number[];
+  /** Allow arbitrary extra properties without forcing casts. */
+  [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+
+/** Expected `this` context for lineage helpers (a subset of the NEAT instance). */
+export interface NeatLineageContext {
+  /** Current evolutionary population (array of genomes). */
+  population: GenomeLike[];
+  /** RNG provider returning a PRNG function; shape taken from core NEAT implementation. */
+  _getRNG: () => () => number;
+}
+
+/**
+ * Depth window (in breadth-first layers) used when gathering ancestor IDs.
+ * A small window keeps the metric inexpensive while still capturing recent lineage diversity.
+ *
+ * Rationale: Deep full ancestry can grow quickly and become O(N * lineage depth). Empirically,
+ * a window of 4 gives a stable signal about short‑term innovation mixing without large cost.
+ *
+ * You can fork and increase this constant if you need deeper lineage metrics, but note that
+ * performance will degrade roughly proportionally to the number of enqueued ancestor nodes.
+ *
+ * Example (changing the window):
+ *   // (NOT exported) – modify locally before building docs
+ *   // const ANCESTOR_DEPTH_WINDOW = 6; // capture deeper history
+ */
+const ANCESTOR_DEPTH_WINDOW = 4;
+
+/**
+ * Build the (shallow) ancestor ID set for a single genome using breadth‑first traversal.
+ *
+ * Traversal Strategy:
+ * 1. Seed queue with the genome's parent IDs (depth = 1).
+ * 2. Repeatedly dequeue, record its ID, and enqueue its parents with incremented depth.
+ * 3. Stop exploring a branch once the configured depth window is exceeded.
+ *
+ * This bounded BFS gives a quick, memory‑friendly approximation of a genome's lineage neighborhood
+ * that works well for diversity/uniqueness metrics without the expense of full historical graphs.
+ *
+ * Edge Cases:
+ *  - Missing or empty `_parents` array ⇒ returns an empty set.
+ *  - Orphan parent IDs (not found in population) are still added (their ID), but no further expansion occurs.
+ *
+ * Complexity (worst case): O(B^D) where B is average branching factor of parent links (usually <= 2)
+ * and D = ANCESTOR_DEPTH_WINDOW (default 4) – so effectively constant for typical NEAT usage.
+ *
+ * @param this NEAT / evolutionary context; must provide `population` (array) for ID lookups.
+ * @param genome Genome whose shallow ancestor set you want to compute.
+ * @returns A Set of numeric ancestor IDs (deduplicated).
+ *
+ * @example
+ * // Assuming `neat` is your NEAT instance and `g` a genome inside `neat.population`:
+ * import { buildAnc } from 'neataptic';
+ * const ancestorIds = buildAnc.call(neat, g);
+ * console.log([...ancestorIds]); // -> e.g. [12, 4, 9]
+ */
+export function buildAnc(
+  this: NeatLineageContext,
+  genome: GenomeLike
+): Set<number> {
+  // Initialize ancestor ID accumulator.
+  const ancestorSet = new Set<number>();
+
+  // Fast exit if the genome has no recorded parents.
+  if (!Array.isArray(genome._parents)) return ancestorSet;
+
+  /**
+   * BFS queue entries carrying the ancestor ID, current depth within the window,
+   * and a direct reference to the ancestor genome (if located) so we can expand its parents.
+   */
+  const queue: { id: number; depth: number; genomeRef?: GenomeLike }[] = [];
+
+  // Seed: enqueue each direct parent at depth = 1.
+  for (const parentId of genome._parents) {
+    queue.push({
+      id: parentId,
+      depth: 1,
+      genomeRef: this.population.find((gm) => gm._id === parentId),
+    });
+  }
+
+  // Breadth‑first expansion within the fixed depth window.
+  while (queue.length) {
+    // Dequeue (FIFO) to ensure breadth‑first order.
+    const current = queue.shift()!;
+
+    // Skip nodes that exceed the depth window limit.
+    if (current.depth > ANCESTOR_DEPTH_WINDOW) continue;
+
+    // Record ancestor ID (dedup automatically handled by Set semantics).
+    if (current.id != null) ancestorSet.add(current.id);
+
+    // If we have a concrete genome reference with parents, enqueue them for the next layer.
+    if (current.genomeRef && Array.isArray(current.genomeRef._parents)) {
+      for (const parentId of current.genomeRef._parents) {
+        queue.push({
+          id: parentId,
+          // Depth increases as we move one layer further away from the focal genome.
+          depth: current.depth + 1,
+          genomeRef: this.population.find((gm) => gm._id === parentId),
+        });
+      }
+    }
+  }
+  return ancestorSet;
+}
+
+/** Maximum number of distinct genome pairs to sample when computing uniqueness. */
+const MAX_UNIQUENESS_SAMPLE_PAIRS = 30;
+
+/**
+ * Compute an "ancestor uniqueness" diversity metric for the current population.
+ *
+ * The metric = mean Jaccard distance between shallow ancestor sets of randomly sampled genome pairs.
+ * A higher value indicates that individuals trace back to more distinct recent lineages (i.e. less
+ * overlap in their ancestor windows), while a lower value indicates convergence toward similar ancestry.
+ *
+ * Why Jaccard Distance? It is scale‑independent: adding unrelated ancestors to both sets simultaneously
+ * does not change the proportion of shared ancestry, and distance stays within [0,1].
+ *
+ * Sampling Strategy:
+ *  - Uniformly sample up to N = min(30, populationPairs) distinct unordered pairs (with replacement on pair selection, but indices are adjusted to avoid self‑pairs).
+ *  - For each pair, construct ancestor sets via `buildAnc` and accumulate their Jaccard distance.
+ *  - Return the average (rounded to 3 decimal places) or 0 if insufficient samples.
+ *
+ * Edge Cases:
+ *  - Population < 2 ⇒ returns 0 (cannot form pairs).
+ *  - Both ancestor sets empty ⇒ pair skipped (no information about uniqueness).
+ *
+ * Performance: O(S * W) where S is sampled pair count (≤ 30) and W is bounded ancestor set size
+ * (kept small by the depth window). This is intentionally lightweight for per‑generation telemetry.
+ *
+ * @param this NEAT context (`population` and `_getRNG` must exist).
+ * @returns Mean Jaccard distance in [0,1]. Higher ⇒ more lineage uniqueness / diversity.
+ *
+ * @example
+ * import { computeAncestorUniqueness } from 'neataptic';
+ * // inside an evolutionary loop, with `neat` as your NEAT instance:
+ * const uniqueness = computeAncestorUniqueness.call(neat);
+ * console.log('Ancestor uniqueness:', uniqueness); // e.g. 0.742
+ */
+export function computeAncestorUniqueness(this: NeatLineageContext): number {
+  // Bind builder once for clarity & micro‑efficiency.
+  const buildAncestorSet = buildAnc.bind(this);
+
+  // Accumulators for (distance sum, sampled pair count).
+  let sampledPairCount = 0;
+  let jaccardDistanceSum = 0;
+
+  /**
+   * Maximum number of pair samples respecting both the cap constant and the total
+   * possible distinct unordered pairs nC2 = n(n-1)/2.
+   */
+  const maxSamplePairs = Math.min(
+    MAX_UNIQUENESS_SAMPLE_PAIRS,
+    (this.population.length * (this.population.length - 1)) / 2
+  );
+
+  // Main sampling loop.
+  for (let t = 0; t < maxSamplePairs; t++) {
+    if (this.population.length < 2) break; // not enough genomes to form pairs
+
+    // Randomly pick first genome index.
+    const indexA = Math.floor(this._getRNG()() * this.population.length);
+    // Pick second index (avoid identical -> simple offset if collision).
+    let indexB = Math.floor(this._getRNG()() * this.population.length);
+    if (indexB === indexA) indexB = (indexB + 1) % this.population.length;
+
+    // Build ancestor sets for the pair.
+    const ancestorSetA = buildAncestorSet(this.population[indexA]);
+    const ancestorSetB = buildAncestorSet(this.population[indexB]);
+
+    // Skip if both sets are empty (no lineage info to compare yet).
+    if (ancestorSetA.size === 0 && ancestorSetB.size === 0) continue;
+
+    // Compute intersection size.
+    let intersectionCount = 0;
+    for (const id of ancestorSetA)
+      if (ancestorSetB.has(id)) intersectionCount++;
+
+    // Union size = |A| + |B| - |A ∩ B| (guard against divide-by-zero).
+    const unionSize =
+      ancestorSetA.size + ancestorSetB.size - intersectionCount || 1;
+
+    // Jaccard distance = 1 - similarity.
+    const jaccardDistance = 1 - intersectionCount / unionSize;
+
+    // Accumulate for averaging.
+    jaccardDistanceSum += jaccardDistance;
+    sampledPairCount++;
+  }
+
+  // Average (3 decimal places) or 0 if no valid samples.
+  const ancestorUniqueness = sampledPairCount
+    ? +(jaccardDistanceSum / sampledPairCount).toFixed(3)
+    : 0;
+  return ancestorUniqueness;
+}

package/src/neat/neat.multiobjective.ts

@@ -0,0 +1,260 @@
+/**
+ * Multi-objective helpers (fast non-dominated sorting + crowding distance).
+ * Extracted from `neat.ts` to keep the core class slimmer.
+ */
+import type Network from '../architecture/network';
+
+/**
+ * Shape of an objective descriptor used by the Neat instance.
+ * - `accessor` extracts a numeric objective from a genome
+ * - `direction` optionally indicates whether the objective is maximized or
+ *   minimized (defaults to 'max')
+ */
+type ObjectiveDescriptor = {
+  accessor: (genome: Network) => number;
+  direction?: 'max' | 'min';
+};
+
+/**
+ * Perform fast non-dominated sorting and compute crowding distances for a
+ * population of networks (genomes). This implements a standard NSGA-II style
+ * non-dominated sorting followed by crowding distance assignment.
+ *
+ * The function annotates genomes with two fields used elsewhere in the codebase:
+ * - `_moRank`: integer Pareto front rank (0 = best/frontier)
+ * - `_moCrowd`: numeric crowding distance (higher is better; Infinity for
+ *   boundary solutions)
+ *
+ * Example
+ * ```ts
+ * // inside a Neat class that exposes `_getObjectives()` and `options`
+ * const fronts = fastNonDominated.call(neatInstance, population);
+ * // fronts[0] is the Pareto-optimal set
+ * ```
+ *
+ * Notes for documentation generation:
+ * - Each objective descriptor returned by `_getObjectives()` must have an
+ *   `accessor(genome: Network): number` function and may include
+ *   `direction: 'max' | 'min'` to indicate optimization direction.
+ * - Accessor failures are guarded and will yield a default value of 0.
+ *
+ * @param this - Neat instance providing `_getObjectives()`, `options` and
+ *   `_paretoArchive` fields (function is meant to be invoked using `.call`)
+ * @param pop - population array of `Network` genomes to be ranked
+ * @returns Array of Pareto fronts; each front is an array of `Network` genomes.
+ */
+export function fastNonDominated(this: any, pop: Network[]): Network[][] {
+  /**
+   * const: objective descriptors array
+   * Short description: descriptors returned by the Neat instance that define
+   * how to extract objective values from genomes and whether each objective is
+   * maximized or minimized.
+   *
+   * Each descriptor must provide:
+   * - `accessor(genome: Network): number` — returns numeric score for genome
+   * - `direction?: 'max' | 'min'` — optional optimization direction (default 'max')
+   */
+  const objectiveDescriptors: ObjectiveDescriptor[] = this._getObjectives();
+
+  /**
+   * const: objective values matrix
+   * Short description: precomputed numeric values of each objective for every
+   * genome in the population. This avoids repeated accessor calls during
+   * pairwise domination checks.
+   *
+   * Shape: `[population.length][objectives.length]` where row i contains the
+   * objective vector for `pop[i]`.
+   */
+  const valuesMatrix: number[][] = pop.map((genomeItem: Network) =>
+    objectiveDescriptors.map((descriptor: any) => {
+      try {
+        return descriptor.accessor(genomeItem);
+      } catch {
+        // If an objective accessor fails, treat the value as neutral (0).
+        return 0;
+      }
+    })
+  );
+
+  /**
+   * const: dominance predicate
+   * Short description: returns true when vector `valuesA` Pareto-dominates
+   * vector `valuesB`.
+   *
+   * Detailed behavior:
+   * - For each objective the comparator respects the objective's `direction`.
+   * - `a` must be at least as good in all objectives and strictly better in at
+   *   least one objective to be considered dominating.
+   *
+   * @param valuesA - objective value vector for candidate A
+   * @param valuesB - objective value vector for candidate B
+   * @returns boolean whether A dominates B
+   *
+   * Example:
+   * ```ts
+   * vectorDominates([1,2], [1,3]) // false when both objectives are 'max'
+   * ```
+   */
+  const vectorDominates = (valuesA: number[], valuesB: number[]) => {
+    let strictlyBetter = false;
+    // Compare each objective, honoring the objective's optimization direction.
+    for (
+      let objectiveIndex = 0;
+      objectiveIndex < valuesA.length;
+      objectiveIndex++
+    ) {
+      const direction = objectiveDescriptors[objectiveIndex].direction || 'max';
+      if (direction === 'max') {
+        // For maximization, higher is better.
+        if (valuesA[objectiveIndex] < valuesB[objectiveIndex]) return false;
+        if (valuesA[objectiveIndex] > valuesB[objectiveIndex])
+          strictlyBetter = true;
+      } else {
+        // For minimization, lower is better.
+        if (valuesA[objectiveIndex] > valuesB[objectiveIndex]) return false;
+        if (valuesA[objectiveIndex] < valuesB[objectiveIndex])
+          strictlyBetter = true;
+      }
+    }
+    return strictlyBetter;
+  };
+
+  /**
+   * const: paretoFronts
+   * Short description: accumulates discovered Pareto fronts during sorting.
+   *
+   * Each element is a front (array of `Network`) in ascending rank order.
+   */
+  const paretoFronts: Network[][] = [];
+
+  /**
+   * const: dominationCounts
+   * Short description: for each genome index, the count of other genomes that
+   * currently dominate it (used to detect front membership when count reaches 0).
+   */
+  const dominationCounts: number[] = new Array(pop.length).fill(0);
+
+  /**
+   * const: dominatesIndicesList
+   * Short description: adjacency list where index p maps to a list of indices q
+   * such that genome p dominates genome q. This accelerates propagation when
+   * removing a front.
+   */
+  const dominatedIndicesByIndex: number[][] = pop.map(() => []);
+
+  /**
+   * const: nonDominatedIndices
+   * Short description: temporary buffer containing indices of genomes that are
+   * not dominated by any other genome — i.e., members of the first front.
+   */
+  const firstFrontIndices: number[] = [];
+
+  // Build domination relationships between every pair of genomes.
+  // Step: for each pair (p,q) compute who (if any) dominates who, using the
+  // precomputed valuesMatrix to avoid repeated accessor calls.
+  for (let pIndex = 0; pIndex < pop.length; pIndex++) {
+    for (let qIndex = 0; qIndex < pop.length; qIndex++) {
+      if (pIndex === qIndex) continue;
+      if (vectorDominates(valuesMatrix[pIndex], valuesMatrix[qIndex]))
+        dominatedIndicesByIndex[pIndex].push(qIndex);
+      else if (vectorDominates(valuesMatrix[qIndex], valuesMatrix[pIndex]))
+        dominationCounts[pIndex]++;
+    }
+    if (dominationCounts[pIndex] === 0) firstFrontIndices.push(pIndex);
+  }
+
+  // Assign genomes to Pareto fronts using a breadth-like ranking algorithm.
+  let currentFrontIndices = firstFrontIndices;
+  let currentFrontRank = 0;
+  while (currentFrontIndices.length) {
+    const nextFrontIndices: number[] = [];
+    for (const pIndex of currentFrontIndices) {
+      // Annotate genome with its multi-objective rank for downstream use.
+      (pop[pIndex] as any)._moRank = currentFrontRank;
+      // For every genome q dominated by p, reduce its domination count.
+      for (const qIndex of dominatedIndicesByIndex[pIndex]) {
+        dominationCounts[qIndex]--;
+        if (dominationCounts[qIndex] === 0) nextFrontIndices.push(qIndex);
+      }
+    }
+    // Add the actual genomes (not indices) as a front.
+    paretoFronts.push(currentFrontIndices.map((i) => pop[i]));
+    currentFrontIndices = nextFrontIndices;
+    currentFrontRank++;
+    // Safety: prevent pathological runs in degenerate cases.
+    if (currentFrontRank > 50) break;
+  }
+
+  // Crowding distance calculation: measures density around solutions in each front.
+  for (const front of paretoFronts) {
+    if (front.length === 0) continue;
+    // Initialize crowding distance for each genome in the front.
+    for (const genomeItem of front) (genomeItem as any)._moCrowd = 0;
+
+    // For each objective, sort the front and accumulate normalized distances.
+    for (
+      let objectiveIndex = 0;
+      objectiveIndex < objectiveDescriptors.length;
+      objectiveIndex++
+    ) {
+      // Sort ascending by the objective value so that boundary solutions
+      // (min and max) fall at the ends of the sorted array — this is needed
+      // to mark boundary genomes with infinite crowding distance.
+      const sortedByCurrentObjective = front
+        .slice()
+        .sort((genomeA, genomeB) => {
+          const valA = objectiveDescriptors[objectiveIndex].accessor(genomeA);
+          const valB = objectiveDescriptors[objectiveIndex].accessor(genomeB);
+          return valA - valB;
+        });
+
+      // Boundary solutions get infinite crowding so they are always preferred.
+      (sortedByCurrentObjective[0] as any)._moCrowd = Infinity;
+      (sortedByCurrentObjective[
+        sortedByCurrentObjective.length - 1
+      ] as any)._moCrowd = Infinity;
+
+      const minVal = objectiveDescriptors[objectiveIndex].accessor(
+        sortedByCurrentObjective[0]
+      );
+      const maxVal = objectiveDescriptors[objectiveIndex].accessor(
+        sortedByCurrentObjective[sortedByCurrentObjective.length - 1]
+      );
+      // Avoid division by zero when all values are equal.
+      const valueRange = maxVal - minVal || 1;
+
+      // For non-boundary genomes, add normalized distance between neighbors.
+      for (
+        let sortedIndex = 1;
+        sortedIndex < sortedByCurrentObjective.length - 1;
+        sortedIndex++
+      ) {
+        const prevVal = objectiveDescriptors[objectiveIndex].accessor(
+          sortedByCurrentObjective[sortedIndex - 1]
+        );
+        const nextVal = objectiveDescriptors[objectiveIndex].accessor(
+          sortedByCurrentObjective[sortedIndex + 1]
+        );
+        (sortedByCurrentObjective[sortedIndex] as any)._moCrowd +=
+          (nextVal - prevVal) / valueRange;
+      }
+    }
+  }
+
+  // Optionally archive a compact Pareto history for visualization/debugging.
+  // The archive stores the current generation and the IDs of genomes in the
+  // top N fronts (here we keep up to 3 fronts). This is deliberately compact
+  // (IDs only) to keep the archive small for long runs.
+  if (this.options.multiObjective?.enabled) {
+    this._paretoArchive.push({
+      generation: this.generation,
+      fronts: paretoFronts.slice(0, 3).map((front) =>
+        // map each front (array of Network) to an array of genome IDs
+        front.map((genome) => (genome as any)._id)
+      ),
+    });
+    if (this._paretoArchive.length > 100) this._paretoArchive.shift();
+  }
+
+  return paretoFronts;
+}