@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/asciiMaze/evolutionEngine/curriculumPhase.ts

@@ -0,0 +1,90 @@
+import type Network from '../../../../src/architecture/network';
+import type { INetwork } from '../interfaces';
+import { NetworkRefinement } from '../networkRefinement';
+import type {
+  MazeEvolutionCurriculumPhaseOutcome,
+  MazeEvolutionRunResult,
+} from './evolutionEngine.types';
+
+/**
+ * Resolve the stable curriculum-facing outcome of one maze evolution phase.
+ *
+ * @remarks
+ * Browser-entry and curriculum-style tests should consume this helper instead
+ * of re-implementing solve-threshold checks or winner carry-over refinement in
+ * host-specific files. That keeps curriculum progression separate from the
+ * engine-owned interpretation of a completed phase result.
+ *
+ * @param evolutionResult - Stable engine result returned by `EvolutionEngine.runMazeEvolution()`.
+ * @param previousBestNetwork - Previously carried winner used when the latest phase has no replacement.
+ * @param minProgressToPass - Progress threshold required before curriculum should advance.
+ * @returns Shared curriculum outcome describing progress, solve state, and next carry-over seed.
+ *
+ * @example
+ * ```ts
+ * const phaseOutcome = resolveMazeEvolutionPhaseOutcome(result, previousBest, 95);
+ * if (phaseOutcome.solved) {
+ *   previousBest = phaseOutcome.nextBestNetwork;
+ * }
+ * ```
+ */
+export const resolveMazeEvolutionPhaseOutcome = (
+  evolutionResult: MazeEvolutionRunResult,
+  previousBestNetwork: INetwork | undefined,
+  minProgressToPass: number,
+): MazeEvolutionCurriculumPhaseOutcome => {
+  const progress = evolutionResult.bestResult?.progress;
+
+  return {
+    result: evolutionResult,
+    progress,
+    solved: hasMazeEvolutionReachedCurriculumThreshold(
+      progress,
+      minProgressToPass,
+    ),
+    nextBestNetwork: refineMazeEvolutionCarryOverNetwork(
+      (evolutionResult.bestNetwork as unknown as INetwork | undefined) ??
+        undefined,
+      previousBestNetwork,
+    ),
+  };
+};
+
+/**
+ * Determine whether a completed phase should advance the surrounding curriculum.
+ *
+ * @param progress - Progress reported by the best run result.
+ * @param minProgressToPass - Minimum progress percentage required to advance.
+ * @returns Whether the phase counts as curriculum-complete.
+ */
+export const hasMazeEvolutionReachedCurriculumThreshold = (
+  progress: unknown,
+  minProgressToPass: number,
+): boolean => {
+  return typeof progress === 'number' && progress >= minProgressToPass;
+};
+
+/**
+ * Refine the winning network before seeding the next curriculum phase.
+ *
+ * @param bestNetwork - Network returned by the latest evolution phase.
+ * @param previousBestNetwork - Previously carried curriculum seed.
+ * @returns Refined winner or the best available carry-over network.
+ */
+export const refineMazeEvolutionCarryOverNetwork = (
+  bestNetwork: INetwork | undefined,
+  previousBestNetwork: INetwork | undefined,
+): INetwork | undefined => {
+  if (!bestNetwork) {
+    return previousBestNetwork;
+  }
+
+  try {
+    const refinedNetwork = NetworkRefinement.refineWinnerWithBackprop(
+      bestNetwork as unknown as Network,
+    );
+    return (refinedNetwork as unknown as INetwork | undefined) ?? bestNetwork;
+  } catch {
+    return bestNetwork;
+  }
+};

package/test/examples/asciiMaze/evolutionEngine/engineState.constants.ts

@@ -0,0 +1,36 @@
+/**
+ * Constant values shared by the ASCII maze engine-state facade and its helper utilities.
+ */
+
+/** Default logits ring length used when allocating pooled softmax buffers. */
+export const DEFAULT_LOGITS_RING_CAPACITY = 512;
+/** Number of action outputs (N, E, S, W) represented in each logits row. */
+export const ACTION_OUTPUT_DIMENSION = 4;
+/** Default load factor target for the visited coordinate hash table. */
+export const DEFAULT_VISITED_HASH_LOAD_FACTOR = 0.7;
+/** Minimum safe load factor applied when normalising visited-hash configuration. */
+export const MIN_VISITED_HASH_LOAD_FACTOR = 0.1;
+/** Maximum safe load factor applied when normalising visited-hash configuration. */
+export const MAX_VISITED_HASH_LOAD_FACTOR = 0.95;
+/** Default RNG cache batch size mirroring the façade constant. */
+export const DEFAULT_RNG_CACHE_BATCH_SIZE = 4;
+/** Default capacity reserved for species identifier scratch arrays. */
+export const DEFAULT_SPECIES_SCRATCH_CAPACITY = 64;
+/** Default capacity reserved for connection flag buffers. */
+export const DEFAULT_CONNECTION_FLAG_CAPACITY = 128;
+/** Default capacity reused by history and sampling scratch arrays. */
+export const DEFAULT_HISTORY_BUFFER_CAPACITY = 64;
+/** Default capacity reserved for sorted index scratch arrays. */
+export const DEFAULT_SORTED_INDEX_CAPACITY = 512;
+/** Default stack depth reserved for quicksort range storage. */
+export const DEFAULT_QUICKSORT_STACK_CAPACITY = 128;
+/** Default pool size for telemetry sampling helpers. */
+export const DEFAULT_SAMPLE_POOL_SIZE = 40;
+/** Default capacity for telemetry string assembly buffers. */
+export const DEFAULT_STRING_BUFFER_CAPACITY = 64;
+/** Default capacity for the small exploration table scratch. */
+export const DEFAULT_SMALL_EXPLORE_TABLE_CAPACITY = 64;
+/** Default capacity for the node index buffer used during inspection. */
+export const DEFAULT_NODE_INDEX_BUFFER_CAPACITY = 64;
+/** Knuth-derived 32-bit constant used when seeding the RNG state. */
+export const RNG_GOLDEN_RATIO_SEED = 0x9e3779b9;