@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/environment/environment.constants.ts

@@ -3,13 +3,26 @@ import {
   FLAPPY_MAX_FRAMES_PER_EPISODE,
 } from '../constants/constants';
 
-/** Default curriculum difficulty scale used by environment stepping. */
+/**
+ * Default curriculum difficulty scale used by environment stepping.
+ *
+ * A value of `1` means the environment uses the full adaptive difficulty ramp.
+ */
 export const FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE = 1;
 
-/** Default number of control/physics substeps executed per simulation frame. */
+/**
+ * Default number of control/physics substeps executed per simulation frame.
+ *
+ * Reusing the shared control-substep count keeps the environment and browser
+ * playback aligned on the same stepping granularity.
+ */
 export const FLAPPY_ENVIRONMENT_DEFAULT_CONTROL_SUBSTEPS_PER_FRAME =
   FLAPPY_CONTROL_SUBSTEPS_PER_FRAME;
 
-/** Maximum frame budget before the environment forces timeout termination. */
+/**
+ * Maximum frame budget before the environment forces timeout termination.
+ *
+ * Timeouts stop extremely long survival loops from dominating evaluation cost.
+ */
 export const FLAPPY_ENVIRONMENT_MAX_FRAMES_PER_EPISODE =
   FLAPPY_MAX_FRAMES_PER_EPISODE;

package/test/examples/flappy_bird/environment/environment.observation.utils.ts

@@ -23,6 +23,12 @@ import type {
 /**
  * Generate the network observation vector for the current state.
  *
+ * Educational note:
+ * This helper is the environment-facing bridge into the shared observation
+ * system. It keeps the environment API simple while ensuring evaluation,
+ * training, and browser playback all derive their policy inputs from the same
+ * feature definitions.
+ *
  * Observation (12 numbers):
  *  1) bird y position normalized to [0, 1]
  *  2) bird vertical velocity normalized to [-1, 1]
@@ -53,6 +59,11 @@ export function getFlappyObservation(
 /**
  * Resolve structured observation features for policy input and reward shaping.
  *
+ * @example
+ * ```ts
+ * const features = getFlappyObservationFeatures(state, 1);
+ * ```
+ *
  * @param state - Current state.
  * @param difficultyScale - Curriculum difficulty scale in [0, 1].
  * @returns Named feature object.
@@ -61,7 +72,7 @@ export function getFlappyObservationFeatures(
   state: FlappyGameState,
   difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
 ): FlappyObservationFeatures {
-  const difficultyProfile = resolveDifficultyProfile(
+  const difficultyProfile = resolveAdaptiveDifficultyProfile(
     state.pipesPassed,
     difficultyScale,
   );
@@ -84,21 +95,3 @@ export function getFlappyObservationFeatures(
     normalizationEpsilon: FLAPPY_NORMALIZATION_EPSILON,
   });
 }
-
-/**
- * Resolves adaptive difficulty parameters from current progress.
- *
- * @param pipesPassed - Number of pipes passed by the active bird.
- * @param difficultyScale - Curriculum difficulty scale in [0, 1].
- * @returns Runtime difficulty profile.
- */
-function resolveDifficultyProfile(
-  pipesPassed: number,
-  difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
-): {
-  pipeGapPx: number;
-  pipeSpeedPxPerFrame: number;
-  pipeSpawnIntervalFrames: number;
-} {
-  return resolveAdaptiveDifficultyProfile(pipesPassed, difficultyScale);
-}

package/test/examples/flappy_bird/environment/environment.state.service.ts

@@ -16,6 +16,16 @@ import type { FlappyGameState } from './environment.types';
 /**
  * Create a fresh Flappy Bird episode state.
  *
+ * Educational note:
+ * A new episode starts with one initial pipe already materialized so the first
+ * observation is meaningful immediately. That avoids a cold-start phase where a
+ * policy would receive mostly empty-space inputs.
+ *
+ * @example
+ * ```ts
+ * const state = createInitialFlappyState(rng);
+ * ```
+ *
  * @param rng - Random source used to generate initial pipe configuration.
  * @returns Initial state for one deterministic rollout.
  */

package/test/examples/flappy_bird/environment/environment.step.service.ts

@@ -28,10 +28,14 @@ import type {
 /**
  * Advance the simulation by one frame.
  *
+ * This is the simplest stepping surface: one logical frame and one flap choice.
+ * More advanced callers can use the control-substep variant below.
+ *
  * @param state - Mutable state object to update in-place.
  * @param rng - Random source used to spawn pipes.
  * @param flap - If true, applies an upward velocity impulse.
  * @param difficultyScale - Curriculum difficulty scale in [0, 1].
+ * @returns Nothing.
  */
 export function stepFlappyState(
   state: FlappyGameState,
@@ -54,6 +58,14 @@ export function stepFlappyState(
  * This allows policies to react multiple times before `frameIndex` advances,
  * improving responsiveness in high-difficulty scenarios.
  *
+ * Educational note:
+ * Splitting a logical frame into smaller control steps is a simple numerical
+ * stability trick. It reduces the chance that fast pipes or large velocity
+ * updates make the environment feel artificially coarse.
+ *
+ * For background reading, the Wikipedia article on "numerical integration"
+ * provides the general idea behind updating continuous motion in small steps.
+ *
  * @param state - Mutable state object to update in-place.
  * @param rng - Random source used to spawn pipes.
  * @param shouldFlapForSubstep - Callback deciding flap action per substep.
@@ -70,7 +82,7 @@ export function stepFlappyStateWithControlSubsteps(
 ): void {
   if (state.done) return;
 
-  const difficultyProfile = resolveDifficultyProfile(
+  const difficultyProfile = resolveAdaptiveDifficultyProfile(
     state.pipesPassed,
     difficultyScale,
   );
@@ -105,12 +117,12 @@ export function stepFlappyStateWithControlSubsteps(
 
     state.framesUntilNextPipeSpawn -= substepDelta;
     if (state.framesUntilNextPipeSpawn <= 0) {
-      const nextGapSizePx = resolveLocalNextSpawnGapSize(
+      const nextGapSizePx = resolveNextSpawnGapSize(
         state.lastSpawnedPipeGapPx,
         difficultyProfile,
         rng,
       );
-      const nextSpawnIntervalFrames = resolveLocalNextSpawnIntervalFrames(
+      const nextSpawnIntervalFrames = resolveNextSpawnIntervalFrames(
         state.lastSpawnedPipeSpawnIntervalFrames,
         difficultyProfile,
       );
@@ -145,66 +157,3 @@ export function stepFlappyStateWithControlSubsteps(
     state.doneReason = 'timeout';
   }
 }
-
-/**
- * Resolves adaptive difficulty parameters from current progress.
- *
- * @param pipesPassed - Number of pipes passed by the active bird.
- * @param difficultyScale - Curriculum difficulty scale in [0, 1].
- * @returns Runtime difficulty profile.
- */
-function resolveDifficultyProfile(
-  pipesPassed: number,
-  difficultyScale: FlappyDifficultyScale = FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE,
-): {
-  pipeGapPx: number;
-  pipeSpeedPxPerFrame: number;
-  pipeSpawnIntervalFrames: number;
-} {
-  return resolveAdaptiveDifficultyProfile(pipesPassed, difficultyScale);
-}
-
-/**
- * Resolve the next spawned pipe gap with progressive wide-to-hard shrink and jitter.
- *
- * @param previousSpawnGapPx - Most recently spawned gap size.
- * @param difficultyProfile - Current adaptive profile.
- * @param rng - Random source.
- * @returns Gap size for the next pipe.
- */
-function resolveLocalNextSpawnGapSize(
-  previousSpawnGapPx: number | undefined,
-  difficultyProfile: {
-    pipeGapPx: number;
-    pipeSpeedPxPerFrame: number;
-    pipeSpawnIntervalFrames: number;
-  },
-  rng: FlappyRng,
-): number {
-  return resolveNextSpawnGapSize(
-    previousSpawnGapPx,
-    difficultyProfile as SharedDifficultyProfile,
-    rng,
-  );
-}
-
-/**
- * Resolve the next spawned pipe interval with progressive wide-to-hard shrink.
- *
- * @param previousSpawnIntervalFrames - Most recently spawned interval.
- * @param difficultyProfile - Current adaptive profile.
- * @returns Spawn interval for the next pipe.
- */
-function resolveLocalNextSpawnIntervalFrames(
-  previousSpawnIntervalFrames: number | undefined,
-  difficultyProfile: {
-    pipeGapPx: number;
-    pipeSpeedPxPerFrame: number;
-    pipeSpawnIntervalFrames: number;
-  },
-): number {
-  return resolveNextSpawnIntervalFrames(
-    previousSpawnIntervalFrames,
-    difficultyProfile as SharedDifficultyProfile,
-  );
-}

package/test/examples/flappy_bird/environment/environment.types.ts

@@ -5,6 +5,9 @@ import type { SharedObservationFeatures } from '../flappy.simulation.shared.util
  *
  * Pipes move from right to left. The bird scores once per pipe when the pipe
  * completely crosses the bird x-position.
+ *
+ * This is the environment-owned pipe state, distinct from the packed snapshot
+ * transport shapes used by the browser worker.
  */
 export interface FlappyPipe {
   /** Horizontal position of the left edge (pixels). */
@@ -22,6 +25,9 @@ export interface FlappyPipe {
 
 /**
  * Bird kinematic state for one simulation frame.
+ *
+ * The environment keeps only the minimum physics state needed to advance the
+ * episode: vertical position and vertical velocity.
  */
 export interface FlappyBird {
   /** Vertical position (pixels). */
@@ -33,6 +39,11 @@ export interface FlappyBird {
 
 /**
  * Full simulation state for one Flappy episode.
+ *
+ * Educational note:
+ * This is the canonical single-episode world state used by evaluation and some
+ * trainer-facing helpers. It is intentionally compact so stepping the world is
+ * deterministic and easy to inspect.
  */
 export interface FlappyGameState {
   /** Current frame counter (0-based). */
@@ -84,5 +95,8 @@ export type FlappyObservationFeatures = SharedObservationFeatures;
  *
  * - `0` means easiest profile (wide gaps, slower pipes).
  * - `1` means fully adaptive profile based on passed pipes.
+ *
+ * Values between `0` and `1` interpolate between those extremes, which lets the
+ * trainer or environment caller dial curriculum strength continuously.
  */
 export type FlappyDifficultyScale = number;

package/test/examples/flappy_bird/evaluation/README.md

@@ -0,0 +1,155 @@
+# evaluation
+
+## evaluation/evaluation.types.ts
+
+### FlappyEpisodeResult
+
+Summary metrics for a single Flappy episode rollout.
+
+The result intentionally keeps both a single scalar `fitness` and the channel
+breakdown that produced it, which makes reward debugging much easier.
+
+### FlappyNetworkLike
+
+Minimal network contract required by Flappy evaluation.
+
+The evaluation layer depends only on activation plus an optional stable id
+used for deterministic seed mixing.
+
+### FlappyRolloutOptions
+
+Runtime controls for one rollout evaluation.
+
+This is the public control surface for evaluation callers. The rollout layer
+later normalizes these options into execution-safe context values.
+
+### FlappySeedBatchEvaluation
+
+Aggregate statistics from evaluating one network across shared seeds.
+
+These statistics are the trainer-facing view of evaluation quality: mean,
+median, $p90$, stability, and average gameplay progress.
+
+## evaluation/evaluation.constants.ts
+
+### evaluation.constants
+
+Default difficulty scale for rollouts when caller does not provide one.
+
+A value of `1` means full adaptive difficulty is enabled during evaluation.
+
+### FLAPPY_EVALUATION_DEFAULT_DIFFICULTY_SCALE
+
+### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
+
+### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES
+
+### FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET
+
+### FLAPPY_EVALUATION_DENSE_SHAPING_FRAMES_NORMALIZER
+
+### FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_PROGRESS_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT
+
+### FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT
+
+### FLAPPY_EVALUATION_ROBUST_STDDEV_PENALTY
+
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_A
+
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_B
+
+### FLAPPY_EVALUATION_SEED_MIX_XOR_SALT
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY
+
+### FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY
+
+## evaluation/evaluation.rollout.service.ts
+
+### evaluation.rollout.service
+
+Public rollout compatibility facade.
+
+Keeping this file at the evaluation layer preserves the established import
+path while the actual rollout orchestration lives behind the dedicated
+rollout-owned module boundary.
+
+This is the public evaluation-layer shelf for callers that should not need to
+know about the rollout subfolder layout.
+
+### rolloutEpisode
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyEpisodeResult`
+
+Roll out an episode and return details.
+
+Parameters:
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Episode result details.
+
+## evaluation/evaluation.seed.utils.ts
+
+### mixGenomeEvaluationSeed
+
+`(genomeId: number) => number`
+
+Mixes a genome identifier into a stable uint32 rollout seed.
+
+This keeps evaluation deterministic per genome while still spreading nearby
+genome ids across the RNG state space to reduce correlated rollouts.
+
+If you want background reading, the Wikipedia article on "hash function"
+gives a reasonable intuition for why a few avalanche-style mixing steps help
+nearby ids map to less-correlated seed values.
+
+Parameters:
+- `genomeId` - - Genome id from NEAT bookkeeping.
+
+Returns: Mixed uint32 seed.
+
+## evaluation/evaluation.fitness.utils.ts
+
+### evaluateFlappyFitness
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => number`
+
+Evaluate a network on a single deterministic Flappy Bird episode.
+
+This is the simplest evaluation entrypoint: one policy, one rollout, one
+scalar fitness.
+
+Parameters:
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Fitness score (higher is better).
+
+### evaluateFlappyFitnessAcrossSeeds
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, sharedSeeds: readonly number[], rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation`
+
+Evaluate a network on a shared batch of deterministic seeds.
+
+Educational note:
+Shared-seed evaluation reduces luck. Every genome in the same comparison set
+sees the same rollout seeds, which makes the aggregate statistics much more
+useful for selection than a single lucky episode.
+
+Parameters:
+- `network` - - Genome/network to evaluate.
+- `sharedSeeds` - - Shared deterministic seeds used for all genomes.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Robust aggregate metrics for selection/ranking.

package/test/examples/flappy_bird/evaluation/evaluation.constants.ts

@@ -1,4 +1,8 @@
-/** Default difficulty scale for rollouts when caller does not provide one. */
+/**
+ * Default difficulty scale for rollouts when caller does not provide one.
+ *
+ * A value of `1` means full adaptive difficulty is enabled during evaluation.
+ */
 export const FLAPPY_EVALUATION_DEFAULT_DIFFICULTY_SCALE = 1;
 
 /** Default grace period (frames) before early termination checks begin. */
@@ -7,7 +11,12 @@ export const FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES = 160;
 /** Default consecutive unrecoverable frames required for early termination. */
 export const FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES = 24;
 
-/** Default pipe-progress target used when normalizing rollout fitness. */
+/**
+ * Default pipe-progress target used when normalizing rollout fitness.
+ *
+ * This target anchors the progress channel so normalization remains meaningful
+ * even when individual episodes vary widely in difficulty and duration.
+ */
 export const FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET = 20;
 
 /** Dense shaping normalization factor per survived frame. */
@@ -25,7 +34,12 @@ export const FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT = 1_200;
 /** Terminal-shaping channel weight in normalized fitness composition. */
 export const FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT = 600;
 
-/** Robust fitness penalty multiplier applied to standard deviation. */
+/**
+ * Robust fitness penalty multiplier applied to standard deviation.
+ *
+ * A higher value penalizes instability more strongly when computing robust
+ * fitness from a shared-seed batch.
+ */
 export const FLAPPY_EVALUATION_ROBUST_STDDEV_PENALTY = 0.35;
 
 /** Unrecoverable clearance threshold used by early termination heuristic. */
@@ -43,7 +57,12 @@ export const FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA = -0.45;
 /** Rising-speed threshold used by early termination heuristic. */
 export const FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY = -0.5;
 
-/** Seed-mix additive constant used to decorrelate nearby genome ids. */
+/**
+ * Seed-mix additive constant used to decorrelate nearby genome ids.
+ *
+ * Together with the multiplicative constants below, this creates a small
+ * avalanche-style mixing pipeline for deterministic seed derivation.
+ */
 export const FLAPPY_EVALUATION_SEED_MIX_XOR_SALT = 0x9e3779b9;
 
 /** Seed-mix first multiplicative avalanche constant. */

package/test/examples/flappy_bird/evaluation/evaluation.fitness.utils.ts

@@ -9,11 +9,14 @@ import {
   computeMean,
   computePercentile,
   computePopulationStandardDeviation,
-} from './evaluation.statistics.utils';
+} from '../flappy.simulation.shared.utils';
 
 /**
  * Evaluate a network on a single deterministic Flappy Bird episode.
  *
+ * This is the simplest evaluation entrypoint: one policy, one rollout, one
+ * scalar fitness.
+ *
  * @param network - Genome/network to evaluate.
  * @param rolloutOptions - Optional rollout controls.
  * @returns Fitness score (higher is better).
@@ -28,6 +31,18 @@ export function evaluateFlappyFitness(
 /**
  * Evaluate a network on a shared batch of deterministic seeds.
  *
+ * Educational note:
+ * Shared-seed evaluation reduces luck. Every genome in the same comparison set
+ * sees the same rollout seeds, which makes the aggregate statistics much more
+ * useful for selection than a single lucky episode.
+ *
+ * @example
+ * ```ts
+ * const aggregate = evaluateFlappyFitnessAcrossSeeds(network, [11, 22, 33], {
+ *   normalizeFitness: true,
+ * });
+ * ```
+ *
  * @param network - Genome/network to evaluate.
  * @param sharedSeeds - Shared deterministic seeds used for all genomes.
  * @param rolloutOptions - Optional rollout controls.