@reicek/neataptic-ts 0.1.24 → 0.1.26

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

@@ -20,6 +20,13 @@ flowchart LR
 
 ## trainer/evaluation/trainer.evaluation.service.types.ts
 
+### PopulationAggregateScoringContext
+
+Aggregate scoring context shared while computing frame-primary scores.
+
+The context precomputes population-wide reference values so per-genome scoring
+can stay simple and deterministic.
+
 ### PopulationStageEvaluationRequest
 
 Candidate-stage request used by the staged population evaluator.
@@ -32,52 +39,29 @@ This shape is intentionally stage-agnostic: quick, full, and reevaluation can
 all use the same execution helper by changing only candidate count, seed set,
 and rollout budget.
 
-### PopulationAggregateScoringContext
-
-Aggregate scoring context shared while computing frame-primary scores.
-
-The context precomputes population-wide reference values so per-genome scoring
-can stay simple and deterministic.
-
 ## trainer/evaluation/trainer.evaluation.service.ts
 
-### evaluatePopulationQuickStage
+### commitPopulationScores
 
 ```ts
-evaluatePopulationQuickStage(
+commitPopulationScores(
   population: readonly FlappyTrainerNetwork[],
-  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
-  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
-  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
 ): void
 ```
 
-Executes the quick evaluation stage over the full population.
+Commits provisional scores to genome score fields.
 
-Educational note:
-The quick stage is a cheap screening pass. Every genome is tested on the same
-small shared seed batch so the trainer can discard obviously weak candidates
-before spending more rollout budget on them.
+Provisional scores are kept in a map during staging so each phase can refresh
+them without mutating the genomes too early. This helper performs the final
+write-back once staged evaluation is complete.
 
 Parameters:
 - `population` - - Current population.
-- `generationEvaluationPlan` - - Per-generation staged evaluation plan.
-- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
-- `provisionalScoresByGenome` - - Mutable provisional score map.
+- `provisionalScoresByGenome` - - Final provisional score map.
 
 Returns: Nothing.
 
-Example:
-
-```ts
-evaluatePopulationQuickStage(
-  population,
-  generationEvaluationPlan,
-  aggregateByGenome,
-  provisionalScoresByGenome,
-);
-```
-
 ### evaluatePopulationFullStage
 
 ```ts
@@ -105,52 +89,68 @@ Parameters:
 
 Returns: Nothing.
 
-### evaluatePopulationReevaluationStage
+### evaluatePopulationQuickStage
 
 ```ts
-evaluatePopulationReevaluationStage(
+evaluatePopulationQuickStage(
   population: readonly FlappyTrainerNetwork[],
   generationEvaluationPlan: FlappyGenerationEvaluationPlan,
   aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
   provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
-  elitismCount: number,
 ): void
 ```
 
-Executes the large-seed reevaluation stage over top candidates.
+Executes the quick evaluation stage over the full population.
 
 Educational note:
-Reevaluation is the trainer's anti-luck pass. The best provisional genomes
-are tested again on a larger shared seed batch so leaderboard positions are
-less sensitive to a fortunate early sample.
+The quick stage is a cheap screening pass. Every genome is tested on the same
+small shared seed batch so the trainer can discard obviously weak candidates
+before spending more rollout budget on them.
 
 Parameters:
 - `population` - - Current population.
 - `generationEvaluationPlan` - - Per-generation staged evaluation plan.
 - `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
 - `provisionalScoresByGenome` - - Mutable provisional score map.
-- `elitismCount` - - Configured elitism count.
 
 Returns: Nothing.
 
-### commitPopulationScores
+Example:
 
 ```ts
-commitPopulationScores(
+evaluatePopulationQuickStage(
+  population,
+  generationEvaluationPlan,
+  aggregateByGenome,
+  provisionalScoresByGenome,
+);
+```
+
+### evaluatePopulationReevaluationStage
+
+```ts
+evaluatePopulationReevaluationStage(
   population: readonly FlappyTrainerNetwork[],
-  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+  elitismCount: number,
 ): void
 ```
 
-Commits provisional scores to genome score fields.
+Executes the large-seed reevaluation stage over top candidates.
 
-Provisional scores are kept in a map during staging so each phase can refresh
-them without mutating the genomes too early. This helper performs the final
-write-back once staged evaluation is complete.
+Educational note:
+Reevaluation is the trainer's anti-luck pass. The best provisional genomes
+are tested again on a larger shared seed batch so leaderboard positions are
+less sensitive to a fortunate early sample.
 
 Parameters:
 - `population` - - Current population.
-- `provisionalScoresByGenome` - - Final provisional score map.
+- `generationEvaluationPlan` - - Per-generation staged evaluation plan.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+- `elitismCount` - - Configured elitism count.
 
 Returns: Nothing.
 
@@ -239,13 +239,6 @@ Fallback score assigned to genomes that have not yet been evaluated.
 Using negative infinity guarantees unevaluated genomes lose any ranking tie
 against genomes that already have real aggregate results.
 
-### FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE
-
-Fallback score assigned to genomes that have not yet been evaluated.
-
-Using negative infinity guarantees unevaluated genomes lose any ranking tie
-against genomes that already have real aggregate results.
-
 ### FLAPPY_TRAINER_MIN_PIPE_PROGRESS
 
 Minimum pipe-progress baseline used when no aggregates are available.
@@ -253,6 +246,13 @@ Minimum pipe-progress baseline used when no aggregates are available.
 This keeps early-stage aggregate scoring well-defined even before any genome
 has established meaningful pipe progress.
 
+### FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE
+
+Fallback score assigned to genomes that have not yet been evaluated.
+
+Using negative infinity guarantees unevaluated genomes lose any ranking tie
+against genomes that already have real aggregate results.
+
 ## trainer/evaluation/trainer.evaluation.service.utils.ts
 
 ### assignFramePrimaryScores
@@ -319,6 +319,26 @@ Parameters:
 
 Returns: Highest mean pipe-progress value.
 
+### resolvePopulationAggregateScoringContext
+
+```ts
+resolvePopulationAggregateScoringContext(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+): PopulationAggregateScoringContext
+```
+
+Resolves the aggregate scoring context used by frame-primary scoring.
+
+This precomputation step keeps the per-genome scoring loop lean and avoids
+recomputing population-wide maxima for every genome.
+
+Parameters:
+- `population` - - Current population.
+- `aggregateByGenome` - - Aggregate cache keyed by genome.
+
+Returns: Aggregate scoring context.
+
 ### scoreAggregateFramePrimary
 
 ```ts
@@ -340,23 +360,3 @@ Parameters:
 - `maximumMeanPipesPassed` - - Best mean pipe progress in the population.
 
 Returns: Provisional score.
-
-### resolvePopulationAggregateScoringContext
-
-```ts
-resolvePopulationAggregateScoringContext(
-  population: readonly FlappyTrainerNetwork[],
-  aggregateByGenome: ReadonlyMap<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
-): PopulationAggregateScoringContext
-```
-
-Resolves the aggregate scoring context used by frame-primary scoring.
-
-This precomputation step keeps the per-genome scoring loop lean and avoids
-recomputing population-wide maxima for every genome.
-
-Parameters:
-- `population` - - Current population.
-- `aggregateByGenome` - - Aggregate cache keyed by genome.
-
-Returns: Aggregate scoring context.