@reicek/neataptic-ts 0.1.0

package/src/neat/neat.export.ts

@@ -0,0 +1,249 @@
+import { NeatLike } from './neat.types';
+
+// ----------------------------------------------------------------------------------
+// Export / Import helpers for NEAT evolutionary state.
+// These utilities deliberately avoid importing the concrete Neat class directly so
+// they can be mixed into lighter-weight facades or used in static contexts.
+// ----------------------------------------------------------------------------------
+
+/**
+ * JSON representation of an individual genome (network). The concrete shape is
+ * produced by `Network#toJSON()` and re‑hydrated via `Network.fromJSON()`. We use
+ * an open record signature here because the network architecture may evolve with
+ * plugins / future features (e.g. CPPNs, substrate metadata, ONNX export tags).
+ */
+export interface GenomeJSON {
+  [key: string]: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+}
+
+/**
+ * Serialized meta information describing a NEAT run, excluding the concrete
+ * population genomes. This allows you to persist & resume experiment context
+ * (innovation history, current generation, IO sizes, hyper‑parameters) without
+ * committing to a particular population snapshot.
+ */
+export interface NeatMetaJSON {
+  /** Number of input nodes expected by evolved networks. */
+  input: number;
+  /** Number of output nodes produced by evolved networks. */
+  output: number;
+  /** Current evolutionary generation index (0-based). */
+  generation: number;
+  /** Full options object (hyper‑parameters) used to configure NEAT. */
+  options: any; // retained as any until options interface is extracted
+  /** Innovation records for node split mutations: [compositeKey, innovationId]. */
+  nodeSplitInnovations: [any, any][]; // key/value pairs serialised from Map
+  /** Innovation records for connection mutations: [compositeKey, innovationId]. */
+  connInnovations: [any, any][];
+  /** Next global innovation number that will be assigned. */
+  nextGlobalInnovation: number;
+}
+
+/**
+ * Top‑level bundle containing both NEAT meta information and the full array of
+ * serialized genomes (population). This is what you get from `exportState()` and
+ * feed into `importStateImpl()` to resume exactly where you left off.
+ */
+export interface NeatStateJSON {
+  /** Serialized NEAT meta (innovation history, generation, options, etc.). */
+  neat: NeatMetaJSON;
+  /** Array of serialized genomes representing the current population. */
+  population: GenomeJSON[];
+}
+
+/**
+ * Export the current population (array of genomes) into plain JSON objects.
+ * Each genome is converted via its `toJSON()` method. You can persist this
+ * result (e.g. to disk, a database, or localStorage) and later rehydrate it
+ * with {@link importPopulation}.
+ *
+ * Why export population only? Sometimes you want to snapshot *just* the set of
+ * candidate solutions (e.g. for ensemble evaluation) without freezing the
+ * innovation counters or hyper‑parameters.
+ *
+ * Example:
+ * ```ts
+ * // Assuming `neat` is an instance exposing this helper
+ * const popSnapshot = neat.exportPopulation();
+ * fs.writeFileSync('population.json', JSON.stringify(popSnapshot, null, 2));
+ * ```
+ * @category Serialization
+ * @returns Array of genome JSON objects.
+ */
+export function exportPopulation(this: NeatLike): GenomeJSON[] {
+  // 1. Map each genome in the current population to its serializable form
+  return (this as any).population.map((genome: any) => genome.toJSON());
+}
+
+/**
+ * Import (replace) the current population from an array of serialized genomes.
+ * This does not touch NEAT meta state (generation, innovations, etc.)—only the
+ * population array and implied `popsize` are updated.
+ *
+ * Example:
+ * ```ts
+ * const populationData: GenomeJSON[] = JSON.parse(fs.readFileSync('population.json','utf8'));
+ * neat.importPopulation(populationData); // population replaced
+ * neat.evolve(); // continue evolving with new starting genomes
+ * ```
+ *
+ * Edge cases handled:
+ * - Empty array => becomes an empty population (popsize=0).
+ * - Malformed entries will throw if `Network.fromJSON` rejects them.
+ *
+ * @param populationJSON Array of serialized genome objects.
+ */
+export function importPopulation(
+  this: NeatLike,
+  populationJSON: GenomeJSON[]
+): void {
+  /** const Network class used for genome (network) rehydration */
+  const Network = require('../architecture/network').default;
+  // 1. Recreate each genome via Network.fromJSON
+  (this as any).population = populationJSON.map((serializedGenome: any) =>
+    Network.fromJSON(serializedGenome)
+  );
+  // 2. Keep popsize option in sync with actual population length
+  (this as any).options.popsize = (this as any).population.length;
+}
+
+/**
+ * Convenience helper that returns a full evolutionary snapshot: both NEAT meta
+ * information and the serialized population array. Use this when you want a
+ * truly *pause‑and‑resume* capability including innovation bookkeeping.
+ *
+ * Example:
+ * ```ts
+ * const state = neat.exportState();
+ * fs.writeFileSync('state.json', JSON.stringify(state));
+ * // ...later / elsewhere...
+ * const raw = JSON.parse(fs.readFileSync('state.json','utf8')) as NeatStateJSON;
+ * const neat2 = Neat.importState(raw, fitnessFn); // identical evolutionary context
+ * ```
+ * @returns A {@link NeatStateJSON} bundle containing meta + population.
+ */
+export function exportState(this: NeatLike): NeatStateJSON {
+  /** const lazily loaded export helpers (avoids circular deps) */
+  const { toJSONImpl, exportPopulation } = require('./neat.export');
+  // 1. Serialize meta
+  // 2. Serialize population
+  // 3. Package into a bundle for persistence
+  return {
+    neat: toJSONImpl.call(this as any),
+    population: exportPopulation.call(this as any),
+  };
+}
+
+/**
+ * Static-style helper that rehydrates a full evolutionary state previously
+ * produced by {@link exportState}. Invoke this with the NEAT *class* (not an
+ * instance) bound as `this`, e.g. `Neat.importStateImpl(bundle, fitnessFn)`.
+ * It constructs a new NEAT instance using the meta data, then imports the
+ * population (if present).
+ *
+ * Safety & validation:
+ * - Throws if the bundle is not an object.
+ * - Silently skips population import if `population` is missing or not an array.
+ *
+ * Example:
+ * ```ts
+ * const bundle: NeatStateJSON = JSON.parse(fs.readFileSync('state.json','utf8'));
+ * const neat = Neat.importStateImpl(bundle, fitnessFn);
+ * neat.evolve();
+ * ```
+ * @param stateBundle Full state bundle from {@link exportState}.
+ * @param fitnessFunction Fitness evaluation callback used for new instance.
+ * @returns Rehydrated NEAT instance ready to continue evolving.
+ */
+export function importStateImpl(
+  this: any,
+  stateBundle: NeatStateJSON,
+  fitnessFunction: (network: any) => number
+): any {
+  // 1. Basic validation of bundle shape
+  if (!stateBundle || typeof stateBundle !== 'object')
+    throw new Error('Invalid state bundle');
+  // 2. Reconstruct Neat meta & instance
+  const neatInstance = this.fromJSON(stateBundle.neat, fitnessFunction);
+  // 3. Import population if provided
+  if (Array.isArray(stateBundle.population))
+    neatInstance.import(stateBundle.population);
+  // 4. Return fully restored instance
+  return neatInstance;
+}
+
+/**
+ * Serialize NEAT meta (excluding the mutable population) for persistence of
+ * innovation history and experiment configuration. This is sufficient to
+ * recreate a *blank* NEAT run at the same evolutionary generation with the
+ * same innovation counters, enabling deterministic continuation when combined
+ * later with a saved population.
+ *
+ * Example:
+ * ```ts
+ * const meta = neat.toJSONImpl();
+ * fs.writeFileSync('neat-meta.json', JSON.stringify(meta));
+ * // ... later ...
+ * const metaLoaded = JSON.parse(fs.readFileSync('neat-meta.json','utf8')) as NeatMetaJSON;
+ * const neat2 = Neat.fromJSONImpl(metaLoaded, fitnessFn); // empty population
+ * ```
+ * @returns {@link NeatMetaJSON} object describing current NEAT meta state.
+ */
+export function toJSONImpl(this: NeatLike): NeatMetaJSON {
+  // 1. Return a plain object with primitive / array serializable fields only
+  return {
+    input: (this as any).input,
+    output: (this as any).output,
+    generation: (this as any).generation,
+    options: (this as any).options,
+    nodeSplitInnovations: Array.from(
+      (this as any)._nodeSplitInnovations.entries()
+    ),
+    connInnovations: Array.from((this as any)._connInnovations.entries()),
+    nextGlobalInnovation: (this as any)._nextGlobalInnovation,
+  };
+}
+
+/**
+ * Static-style implementation that rehydrates a NEAT instance from previously
+ * exported meta JSON produced by {@link toJSONImpl}. This does *not* restore a
+ * population; callers typically follow up with `importPopulation` or use
+ * {@link importStateImpl} for a complete restore.
+ *
+ * Example:
+ * ```ts
+ * const meta: NeatMetaJSON = JSON.parse(fs.readFileSync('neat-meta.json','utf8'));
+ * const neat = Neat.fromJSONImpl(meta, fitnessFn); // empty population, same innovations
+ * neat.importPopulation(popSnapshot); // optional
+ * ```
+ * @param neatJSON Serialized meta (no population).
+ * @param fitnessFunction Fitness callback used to construct the new instance.
+ * @returns Fresh NEAT instance with restored innovation history.
+ */
+export function fromJSONImpl(
+  this: any,
+  neatJSON: NeatMetaJSON,
+  fitnessFunction: (network: any) => number
+): any {
+  /** const alias for the constructor (class) this function is bound to */
+  const NeatClass = this as any;
+  // 1. Instantiate with stored IO sizes & options
+  const neatInstance = new NeatClass(
+    neatJSON.input,
+    neatJSON.output,
+    fitnessFunction,
+    neatJSON.options || {}
+  );
+  // 2. Restore generation index
+  neatInstance.generation = neatJSON.generation || 0;
+  // 3. Restore innovation maps when present
+  if (Array.isArray(neatJSON.nodeSplitInnovations))
+    neatInstance._nodeSplitInnovations = new Map(neatJSON.nodeSplitInnovations);
+  if (Array.isArray(neatJSON.connInnovations))
+    neatInstance._connInnovations = new Map(neatJSON.connInnovations);
+  // 4. Restore next innovation counter
+  if (typeof neatJSON.nextGlobalInnovation === 'number')
+    neatInstance._nextGlobalInnovation = neatJSON.nextGlobalInnovation;
+  // 5. Return reconstructed instance (empty population)
+  return neatInstance;
+}

package/src/neat/neat.helpers.ts

@@ -0,0 +1,235 @@
+import { NeatLike } from './neat.types';
+import Network from '../architecture/network';
+
+/**
+ * Helper utilities that augment the core NEAT (NeuroEvolution of Augmenting Topologies)
+ * implementation. These functions are kept separate from the main class so they can
+ * be tree‑shaken when unused and independently documented for educational purposes.
+ *
+ * The helpers focus on three core lifecycle operations:
+ * 1. Spawning children from an existing parent genome with mutation ("sexual" reproduction not handled here).
+ * 2. Registering externally created genomes so lineage & invariants remain consistent.
+ * 3. Creating the initial population pool (bootstrapping evolution) either from a seed
+ *    network or by synthesizing fresh minimal networks.
+ *
+ * All helpers expect to be invoked with a `this` context that matches `NeatLike`.
+ * They intentionally use defensive try/catch blocks to avoid aborting broader
+ * evolutionary runs when an individual genome operation fails; this mirrors the
+ * tolerant/robust nature of many historical NEAT library implementations.
+ */
+
+/**
+ * Spawn (clone & mutate) a child genome from an existing parent genome.
+ *
+ * The returned child is intentionally NOT auto‑inserted into the population;
+ * call {@link addGenome} (or the class method wrapper) once you decide to
+ * keep it. This separation allows callers to perform custom validation or
+ * scoring heuristics before committing the child genome.
+ *
+ * Evolutionary rationale:
+ * - Cloning preserves the full topology & weights of the parent.
+ * - A configurable number of mutation passes are applied sequentially; each
+ *   pass may alter structure (add/remove nodes / connections) or weights.
+ * - Lineage annotations (`_parents`, `_depth`) enable later analytics (e.g.,
+ *   diversity statistics, genealogy visualization, pruning heuristics).
+ *
+ * Robustness philosophy: individual mutation failures are silently ignored so
+ * a single stochastic edge case (e.g., no valid structural mutation) does not
+ * derail evolutionary progress.
+ *
+ * @param this Bound NEAT instance (inferred when used as a method).
+ * @param parentGenome Parent genome/network to clone. Must implement either
+ * `clone()` OR a pair of `toJSON()` / static `fromJSON()` for deep copying.
+ * @param mutateCount Number of sequential mutation operations to attempt; each
+ *        iteration chooses a mutation method using the instance's selection logic.
+ *        Defaults to 1 for conservative structural drift.
+ * @returns A new genome (unregistered) whose score is reset and whose lineage
+ *          metadata references the parent.
+ * @example
+ * ```ts
+ * // Assume `neat` is an instance implementing NeatLike and `parent` is a genome in neat.population
+ * const child = neat.spawnFromParent(parent, 3); // apply 3 mutation passes
+ * // Optionally inspect / filter the child before adding
+ * neat.addGenome(child, [parent._id]);
+ * ```
+ */
+export function spawnFromParent(
+  this: NeatLike,
+  parentGenome: any,
+  mutateCount: number = 1
+) {
+  // Step 1: Deep clone the parent (prefer direct clone() for performance).
+  const clone = parentGenome.clone
+    ? parentGenome.clone()
+    : require('../architecture/network').default.fromJSON(
+        parentGenome.toJSON()
+      );
+
+  // Step 2: Reset evaluation state for the fresh offspring.
+  clone.score = undefined;
+  (clone as any)._reenableProb = (this as any).options.reenableProb;
+  (clone as any)._id = (this as any)._nextGenomeId++;
+
+  // Step 3: Record minimal lineage (single direct parent) and generation depth.
+  (clone as any)._parents = [(parentGenome as any)._id];
+  (clone as any)._depth = ((parentGenome as any)._depth ?? 0) + 1;
+
+  // Step 4: Enforce structural invariants (minimum hidden nodes, no dead ends).
+  (this as any).ensureMinHiddenNodes(clone);
+  (this as any).ensureNoDeadEnds(clone);
+
+  // Step 5: Apply the requested number of mutation passes.
+  for (let mutationIndex = 0; mutationIndex < mutateCount; mutationIndex++) {
+    try {
+      // Select a mutation operator; may return a single method or an array of candidates.
+      let selectedMutationMethod = (this as any).selectMutationMethod(
+        clone,
+        false
+      );
+      if (Array.isArray(selectedMutationMethod)) {
+        const candidateMutations = selectedMutationMethod as any[];
+        selectedMutationMethod =
+          candidateMutations[
+            Math.floor((this as any)._getRNG()() * candidateMutations.length)
+          ];
+      }
+      // Execute mutation if a valid operator with a name (convention) is present.
+      if (selectedMutationMethod && selectedMutationMethod.name) {
+        clone.mutate(selectedMutationMethod);
+      }
+    } catch {
+      // Intentionally ignore individual mutation failures to keep evolution moving.
+    }
+  }
+
+  // Step 6: Invalidate any cached compatibility / distance metrics tied to the genome.
+  (this as any)._invalidateGenomeCaches(clone);
+  return clone;
+}
+
+/**
+ * Register an externally constructed genome (e.g., deserialized, custom‑built,
+ * or imported from another run) into the active population. Ensures lineage
+ * metadata and structural invariants are consistent with internally spawned
+ * genomes.
+ *
+ * Defensive design: If invariant enforcement fails, the genome is still added
+ * (best effort) so experiments remain reproducible and do not abort mid‑run.
+ * Caller can optionally inspect or prune later during evaluation.
+ *
+ * @param this Bound NEAT instance.
+ * @param genome Genome / network object to insert. Mutated in place to add
+ *        internal metadata fields (`_id`, `_parents`, `_depth`, `_reenableProb`).
+ * @param parents Optional explicit list of parent genome IDs (e.g., 2 parents
+ *        for crossover). If omitted, lineage metadata is left empty.
+ * @example
+ * ```ts
+ * const imported = Network.fromJSON(saved);
+ * neat.addGenome(imported, [parentA._id, parentB._id]);
+ * ```
+ */
+export function addGenome(this: NeatLike, genome: any, parents?: number[]) {
+  try {
+    // Step 1: Reset score so future evaluations are not biased by stale values.
+    genome.score = undefined;
+    (genome as any)._reenableProb = (this as any).options.reenableProb;
+    (genome as any)._id = (this as any)._nextGenomeId++;
+
+    // Step 2: Copy lineage from provided parent IDs (if any).
+    (genome as any)._parents = Array.isArray(parents) ? parents.slice() : [];
+    (genome as any)._depth = 0;
+    if ((genome as any)._parents.length) {
+      // Compute depth = (max parent depth) + 1 for genealogical layering.
+      const parentDepths = (genome as any)._parents
+        .map((pid: number) =>
+          (this as any).population.find((g: any) => g._id === pid)
+        )
+        .filter(Boolean)
+        .map((g: any) => g._depth ?? 0);
+      (genome as any)._depth = parentDepths.length
+        ? Math.max(...parentDepths) + 1
+        : 1;
+    }
+
+    // Step 3: Ensure structural invariants.
+    (this as any).ensureMinHiddenNodes(genome);
+    (this as any).ensureNoDeadEnds(genome);
+
+    // Step 4: Invalidate caches & persist.
+    (this as any)._invalidateGenomeCaches(genome);
+    (this as any).population.push(genome);
+  } catch (error) {
+    // Fallback: still add genome so the evolutionary run can continue.
+    (this as any).population.push(genome);
+  }
+}
+
+/**
+ * Create (or reset) the initial population pool for a NEAT run.
+ *
+ * If a `seedNetwork` is supplied, every genome is a structural + weight clone
+ * of that seed. This is useful for transfer learning or continuing evolution
+ * from a known good architecture. When omitted, brand‑new minimal networks are
+ * synthesized using the configured input/output sizes (and optional minimum
+ * hidden layer size).
+ *
+ * Design notes:
+ * - Population size is derived from `options.popsize` (default 50).
+ * - Each genome gets a unique sequential `_id` for reproducible lineage.
+ * - When lineage tracking is enabled (`_lineageEnabled`), parent & depth fields
+ *   are initialized for later analytics.
+ * - Structural invariant checks are best effort. A single failure should not
+ *   prevent other genomes from being created, hence broad try/catch blocks.
+ *
+ * @param this Bound NEAT instance.
+ * @param seedNetwork Optional prototype network to clone for every initial genome.
+ * @example
+ * ```ts
+ * // Basic: create 50 fresh minimal networks
+ * neat.createPool(null);
+ *
+ * // Seeded: start with a known topology
+ * const seed = new Network(neat.input, neat.output, { minHidden: 4 });
+ * neat.createPool(seed);
+ * ```
+ */
+export function createPool(this: NeatLike, seedNetwork: any | null) {
+  try {
+    // Step 1: Reset population container.
+    (this as any).population = [];
+    const poolSize = ((this as any).options?.popsize as number) || 50;
+
+    // Step 2: Generate each initial genome.
+    for (let genomeIndex = 0; genomeIndex < poolSize; genomeIndex++) {
+      // Clone from seed OR build a fresh network.
+      const genomeCopy = seedNetwork
+        ? Network.fromJSON(seedNetwork.toJSON())
+        : new Network((this as any).input, (this as any).output, {
+            minHidden: (this as any).options?.minHidden,
+          });
+
+      // Step 2a: Ensure no stale scoring information.
+      genomeCopy.score = undefined;
+
+      // Step 2b: Attempt structural invariant enforcement (best effort).
+      try {
+        (this as any).ensureNoDeadEnds(genomeCopy);
+      } catch {
+        // Ignored; genome may still be viable or corrected by later mutations.
+      }
+
+      // Step 2c: Annotate runtime metadata.
+      (genomeCopy as any)._reenableProb = (this as any).options.reenableProb;
+      (genomeCopy as any)._id = (this as any)._nextGenomeId++;
+      if ((this as any)._lineageEnabled) {
+        (genomeCopy as any)._parents = [];
+        (genomeCopy as any)._depth = 0;
+      }
+
+      // Step 2d: Insert into population.
+      (this as any).population.push(genomeCopy);
+    }
+  } catch {
+    // Swallow: partial population is acceptable; caller may decide to refill or continue.
+  }
+}