@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/multiobjective/dominance/README.md

@@ -43,49 +43,35 @@ from or why descriptor order must stay fixed.
 
 ## neat/multiobjective/dominance/multiobjective.dominance.ts
 
-### vectorDominates
+### applyPairwiseDominance
 
 ```ts
-vectorDominates(
-  valuesA: number[],
-  valuesB: number[],
+applyPairwiseDominance(
+  dominanceState: DominanceState,
+  valuesMatrixInput: number[][],
   descriptors: ObjectiveDescriptor[],
-): boolean
+  candidateIndex: number,
+  opponentIndex: number,
+): void
 ```
 
-Determines whether vector A Pareto-dominates vector B.
-
-A dominates B iff:
-- A is **no worse** than B in every objective (respecting each objective’s
-  direction: maximize/minimize), and
-- A is **strictly better** in at least one objective.
+Applies a single pairwise dominance update between candidate and opponent.
 
-This helper is deliberately pair-local. It does not mutate bookkeeping or
-know anything about fronts; it only answers the comparison question that the
-wider bookkeeping pass repeats across every pair of matrix rows.
+If the candidate dominates the opponent, the opponent index is appended to
+`dominatedIndicesByIndex[candidateIndex]`. If the candidate is dominated by
+the opponent, `dominationCounts[candidateIndex]` is incremented.
 
-Assumptions:
-- `valuesA` and `valuesB` are aligned and have the same length.
-- `descriptors` provides a descriptor for each objective index.
-- If a descriptor has no `direction`, it defaults to `'max'`.
+That asymmetry is the key bookkeeping contract for the later frontier peel:
+- the count answers whether the candidate can join the current front yet,
+- the dominated-neighbor list tells later passes which counts to relax once
+  the candidate is removed as a blocker.
 
 Parameters:
-- `valuesA` - - Objective values for candidate A.
-- `valuesB` - - Objective values for candidate B.
-- `descriptors` - - Objective descriptors defining direction semantics.
-
-Returns: `true` if A dominates B; otherwise `false`.
-
-Example:
-
-```ts
-// Maximize accuracy, minimize latency:
-vectorDominates([0.9, 120], [0.9, 150], [
-  { accessor: () => 0, direction: 'max' },
-  { accessor: () => 0, direction: 'min' },
-]);
-// => true (equal accuracy, lower latency)
-```
+- `dominanceState` - - Dominance bookkeeping.
+- `valuesMatrixInput` - - Matrix of objective values.
+- `descriptors` - - Objective descriptors.
+- `candidateIndex` - - Candidate genome index.
+- `opponentIndex` - - Opponent genome index.
 
 ### buildDominanceState
 
@@ -128,41 +114,25 @@ Parameters:
 
 Returns: Dominance bookkeeping structures for ranking.
 
-### DominanceState
-
-Dominance bookkeeping structures for fast non-dominated sorting.
-
-These structures are typically produced once per generation (from the values
-matrix) and then consumed to build Pareto fronts.
-
-They form the compact handoff between pairwise comparison mechanics and the
-later frontier-construction pass:
-- `dominationCounts` records how many opponents currently sit above each row
-- `dominatedIndicesByIndex` records which rows should be relaxed when a
-  front is peeled away
-- `firstFrontIndices` captures the initial non-dominated frontier without
-  re-running the full comparison loop
-
-### resolveObjectiveDirection
+### buildIndexRange
 
 ```ts
-resolveObjectiveDirection(
-  descriptors: ObjectiveDescriptor[],
-  objectiveIndex: number,
-): "max" | "min"
+buildIndexRange(
+  populationSize: number,
+): number[]
 ```
 
-Resolves the objective direction for a given objective index.
+Builds a stable index range for iterating the population.
 
-If a descriptor omits `direction`, it is treated as maximization.
-Keeping that default here ensures every comparison helper downstream reads
-one normalized direction rule instead of repeating fallback logic.
+The returned range becomes the shared iteration order for candidate and
+opponent loops. Using explicit indices instead of genome references keeps the
+dominance state compact and guarantees later frontier code can look up rows
+and genomes with the same integer keys.
 
 Parameters:
-- `descriptors` - - Objective descriptors.
-- `objectiveIndex` - - Objective index.
+- `populationSize` - - Number of genomes.
 
-Returns: Normalized objective direction.
+Returns: Array of indices `0..populationSize-1`.
 
 ### compareObjectiveValues
 
@@ -190,6 +160,40 @@ Parameters:
 
 Returns: Comparison flags for this objective.
 
+### createEmptyDominanceState
+
+```ts
+createEmptyDominanceState(
+  populationSize: number,
+): DominanceState
+```
+
+Creates an empty dominance state container sized to the population.
+
+Every array slot maps directly to one matrix row and therefore one genome in
+the ranking pass. Initializing the structure once keeps later comparison
+helpers focused on bookkeeping updates rather than allocation details.
+
+Parameters:
+- `populationSize` - - Number of genomes.
+
+Returns: An initialized dominance state with zeroed counts.
+
+### DominanceState
+
+Dominance bookkeeping structures for fast non-dominated sorting.
+
+These structures are typically produced once per generation (from the values
+matrix) and then consumed to build Pareto fronts.
+
+They form the compact handoff between pairwise comparison mechanics and the
+later frontier-construction pass:
+- `dominationCounts` records how many opponents currently sit above each row
+- `dominatedIndicesByIndex` records which rows should be relaxed when a
+  front is peeled away
+- `firstFrontIndices` captures the initial non-dominated frontier without
+  re-running the full comparison loop
+
 ### isCandidateDominatedByObjective
 
 ```ts
@@ -235,192 +239,188 @@ Parameters:
 
 Returns: `true` if the candidate is strictly better for this objective.
 
-### updateStrictImprovement
+### isNonDominatedCandidate
 
 ```ts
-updateStrictImprovement(
-  hasStrictImprovement: boolean,
-  isStrictlyBetter: boolean,
+isNonDominatedCandidate(
+  dominanceState: DominanceState,
+  candidateIndex: number,
 ): boolean
 ```
 
-Accumulates whether the candidate has a strict improvement across
-objectives.
+Determines whether a candidate has zero domination count.
+
+A zero count means the current row survived every pairwise comparison without
+finding a dominating opponent, which is exactly the criterion for first-front
+membership before frontier peeling begins.
 
 Parameters:
-- `hasStrictImprovement` - - Current strict-improvement flag.
-- `isStrictlyBetter` - - Whether the candidate strictly improves on the
-current objective.
+- `dominanceState` - - Dominance bookkeeping.
+- `candidateIndex` - - Candidate genome index.
 
-Returns: Updated strict-improvement flag.
+Returns: `true` if the candidate is currently non-dominated.
 
-### createEmptyDominanceState
+### resolveDominanceOutcome
 
 ```ts
-createEmptyDominanceState(
-  populationSize: number,
-): DominanceState
+resolveDominanceOutcome(
+  candidateVector: number[],
+  opponentVector: number[],
+  descriptors: ObjectiveDescriptor[],
+): "dominates" | "dominated" | "indifferent"
 ```
 
-Creates an empty dominance state container sized to the population.
+Resolves dominance outcome between two objective vectors.
 
-Every array slot maps directly to one matrix row and therefore one genome in
-the ranking pass. Initializing the structure once keeps later comparison
-helpers focused on bookkeeping updates rather than allocation details.
+Outcome meanings:
+- `'dominates'`: candidate dominates opponent.
+- `'dominated'`: candidate is dominated by opponent.
+- `'indifferent'`: neither dominates the other.
+
+Pareto dominance is directional, so this helper checks both directions in a
+fixed order. That keeps ties and tradeoffs explicit: many pairs in a
+multi-objective population are intentionally incomparable rather than simply
+"better" or "worse."
 
 Parameters:
-- `populationSize` - - Number of genomes.
+- `candidateVector` - - Candidate objective values.
+- `opponentVector` - - Opponent objective values.
+- `descriptors` - - Objective descriptors.
 
-Returns: An initialized dominance state with zeroed counts.
+Returns: Dominance outcome between candidate and opponent.
 
-### buildIndexRange
+### resolveObjectiveDirection
 
 ```ts
-buildIndexRange(
-  populationSize: number,
-): number[]
+resolveObjectiveDirection(
+  descriptors: ObjectiveDescriptor[],
+  objectiveIndex: number,
+): "max" | "min"
 ```
 
-Builds a stable index range for iterating the population.
+Resolves the objective direction for a given objective index.
 
-The returned range becomes the shared iteration order for candidate and
-opponent loops. Using explicit indices instead of genome references keeps the
-dominance state compact and guarantees later frontier code can look up rows
-and genomes with the same integer keys.
+If a descriptor omits `direction`, it is treated as maximization.
+Keeping that default here ensures every comparison helper downstream reads
+one normalized direction rule instead of repeating fallback logic.
 
 Parameters:
-- `populationSize` - - Number of genomes.
+- `descriptors` - - Objective descriptors.
+- `objectiveIndex` - - Objective index.
 
-Returns: Array of indices `0..populationSize-1`.
+Returns: Normalized objective direction.
 
-### updateDominanceForCandidate
+### shouldSkipSelfComparison
 
 ```ts
-updateDominanceForCandidate(
-  dominanceState: DominanceState,
-  valuesMatrixInput: number[][],
-  descriptors: ObjectiveDescriptor[],
+shouldSkipSelfComparison(
   candidateIndex: number,
-  candidateIndices: number[],
-): void
+  opponentIndex: number,
+): boolean
 ```
 
-Updates dominance bookkeeping for a candidate against all opponents.
+Determines whether a pairwise comparison should be skipped.
 
-This iterates every opponent index and applies a pairwise dominance update.
-Self-comparisons are ignored.
+Currently this skips only self-comparisons.
 
-The helper stays candidate-centric on purpose. Each pass answers "what does
-the rest of the matrix imply about this row?" and leaves first-front
-discovery to the outer orchestration once all opponent evidence has been
-accumulated.
+Keeping the skip rule isolated makes it easier to audit the pairwise loop and
+preserves the invariant that every stored relationship refers to two distinct
+matrix rows.
 
 Parameters:
-- `dominanceState` - - Dominance bookkeeping.
-- `valuesMatrixInput` - - Matrix of objective values.
-- `descriptors` - - Objective descriptors.
 - `candidateIndex` - - Candidate genome index.
-- `candidateIndices` - - Indices to compare against.
+- `opponentIndex` - - Opponent genome index.
 
-### applyPairwiseDominance
+Returns: `true` if the pair should be skipped.
+
+### updateDominanceForCandidate
 
 ```ts
-applyPairwiseDominance(
+updateDominanceForCandidate(
   dominanceState: DominanceState,
   valuesMatrixInput: number[][],
   descriptors: ObjectiveDescriptor[],
   candidateIndex: number,
-  opponentIndex: number,
+  candidateIndices: number[],
 ): void
 ```
 
-Applies a single pairwise dominance update between candidate and opponent.
+Updates dominance bookkeeping for a candidate against all opponents.
 
-If the candidate dominates the opponent, the opponent index is appended to
-`dominatedIndicesByIndex[candidateIndex]`. If the candidate is dominated by
-the opponent, `dominationCounts[candidateIndex]` is incremented.
+This iterates every opponent index and applies a pairwise dominance update.
+Self-comparisons are ignored.
 
-That asymmetry is the key bookkeeping contract for the later frontier peel:
-- the count answers whether the candidate can join the current front yet,
-- the dominated-neighbor list tells later passes which counts to relax once
-  the candidate is removed as a blocker.
+The helper stays candidate-centric on purpose. Each pass answers "what does
+the rest of the matrix imply about this row?" and leaves first-front
+discovery to the outer orchestration once all opponent evidence has been
+accumulated.
 
 Parameters:
 - `dominanceState` - - Dominance bookkeeping.
 - `valuesMatrixInput` - - Matrix of objective values.
 - `descriptors` - - Objective descriptors.
 - `candidateIndex` - - Candidate genome index.
-- `opponentIndex` - - Opponent genome index.
+- `candidateIndices` - - Indices to compare against.
 
-### shouldSkipSelfComparison
+### updateStrictImprovement
 
 ```ts
-shouldSkipSelfComparison(
-  candidateIndex: number,
-  opponentIndex: number,
+updateStrictImprovement(
+  hasStrictImprovement: boolean,
+  isStrictlyBetter: boolean,
 ): boolean
 ```
 
-Determines whether a pairwise comparison should be skipped.
-
-Currently this skips only self-comparisons.
-
-Keeping the skip rule isolated makes it easier to audit the pairwise loop and
-preserves the invariant that every stored relationship refers to two distinct
-matrix rows.
+Accumulates whether the candidate has a strict improvement across
+objectives.
 
 Parameters:
-- `candidateIndex` - - Candidate genome index.
-- `opponentIndex` - - Opponent genome index.
+- `hasStrictImprovement` - - Current strict-improvement flag.
+- `isStrictlyBetter` - - Whether the candidate strictly improves on the
+current objective.
 
-Returns: `true` if the pair should be skipped.
+Returns: Updated strict-improvement flag.
 
-### resolveDominanceOutcome
+### vectorDominates
 
 ```ts
-resolveDominanceOutcome(
-  candidateVector: number[],
-  opponentVector: number[],
+vectorDominates(
+  valuesA: number[],
+  valuesB: number[],
   descriptors: ObjectiveDescriptor[],
-): "dominates" | "dominated" | "indifferent"
+): boolean
 ```
 
-Resolves dominance outcome between two objective vectors.
+Determines whether vector A Pareto-dominates vector B.
 
-Outcome meanings:
-- `'dominates'`: candidate dominates opponent.
-- `'dominated'`: candidate is dominated by opponent.
-- `'indifferent'`: neither dominates the other.
+A dominates B iff:
+- A is **no worse** than B in every objective (respecting each objective’s
+  direction: maximize/minimize), and
+- A is **strictly better** in at least one objective.
 
-Pareto dominance is directional, so this helper checks both directions in a
-fixed order. That keeps ties and tradeoffs explicit: many pairs in a
-multi-objective population are intentionally incomparable rather than simply
-"better" or "worse."
+This helper is deliberately pair-local. It does not mutate bookkeeping or
+know anything about fronts; it only answers the comparison question that the
+wider bookkeeping pass repeats across every pair of matrix rows.
+
+Assumptions:
+- `valuesA` and `valuesB` are aligned and have the same length.
+- `descriptors` provides a descriptor for each objective index.
+- If a descriptor has no `direction`, it defaults to `'max'`.
 
 Parameters:
-- `candidateVector` - - Candidate objective values.
-- `opponentVector` - - Opponent objective values.
-- `descriptors` - - Objective descriptors.
+- `valuesA` - - Objective values for candidate A.
+- `valuesB` - - Objective values for candidate B.
+- `descriptors` - - Objective descriptors defining direction semantics.
 
-Returns: Dominance outcome between candidate and opponent.
+Returns: `true` if A dominates B; otherwise `false`.
 
-### isNonDominatedCandidate
+Example:
 
 ```ts
-isNonDominatedCandidate(
-  dominanceState: DominanceState,
-  candidateIndex: number,
-): boolean
+// Maximize accuracy, minimize latency:
+vectorDominates([0.9, 120], [0.9, 150], [
+  { accessor: () => 0, direction: 'max' },
+  { accessor: () => 0, direction: 'min' },
+]);
+// => true (equal accuracy, lower latency)
 ```
-
-Determines whether a candidate has zero domination count.
-
-A zero count means the current row survived every pairwise comparison without
-finding a dominating opponent, which is exactly the criterion for first-front
-membership before frontier peeling begins.
-
-Parameters:
-- `dominanceState` - - Dominance bookkeeping.
-- `candidateIndex` - - Candidate genome index.
-
-Returns: `true` if the candidate is currently non-dominated.

package/src/neat/multiobjective/fronts/README.md

@@ -44,51 +44,49 @@ computed in the first place.
 
 ## neat/multiobjective/fronts/multiobjective.fronts.ts
 
-### buildParetoFronts
+### annotateGenomeRank
 
 ```ts
-buildParetoFronts(
+annotateGenomeRank(
   population: default[],
-  dominanceState: DominanceState,
-  maxFrontRankGuard: number,
-): default[][]
+  genomeIndex: number,
+  frontRank: number,
+): void
 ```
 
-Builds Pareto fronts from a precomputed dominance state.
-
-This performs the “peeling” phase of fast non-dominated sorting:
-- Start with the first front (all non-dominated genomes).
-- For each front, reduce domination counts of the genomes it dominates.
-- Each genome whose domination count becomes zero moves to the next front.
-
-The implementation is intentionally breadth-first. It never revisits pairwise
-comparisons; instead it trusts the dominance-state handoff and repeatedly
-relaxes domination counts until the next layer becomes visible.
-
-Side effects:
-- Annotates each genome in `population` with `_moRank` (0 = best front).
+Annotates a genome with its Pareto front rank.
 
-Guard:
-- Stops when `currentFrontRank > maxFrontRankGuard` to avoid pathological
-  infinite/degenerate runs. If the guard triggers, the returned fronts may
-  be incomplete.
+Ranking is stored directly on the genome so later selection, telemetry, and
+archive helpers can read one stable annotation instead of carrying a parallel
+rank table beside the population.
 
 Parameters:
-- `population` - - Genome population (same ordering used by dominance
-bookkeeping).
-- `dominanceState` - - Dominance bookkeeping.
-- `maxFrontRankGuard` - - Safety guard for ranking iterations.
+- `population` - - Genome population.
+- `genomeIndex` - - Index of the genome to annotate.
+- `frontRank` - - Pareto front rank (0 = best front).
 
-Returns: Ordered Pareto fronts (rank order).
+### appendFront
 
-### MAX_PARETO_FRONT_RANK_GUARD
+```ts
+appendFront(
+  paretoFronts: default[][],
+  population: default[],
+  currentFrontIndices: number[],
+): void
+```
 
-Maximum number of Pareto fronts to allow during ranking before aborting.
+Appends the current front (index list) as genome references to the
+`paretoFronts` accumulator.
 
-This is a defensive guard against pathological conditions (e.g., corrupted
-dominance bookkeeping) that could otherwise cause long/infinite loops.
-A healthy ranking pass should terminate well before this threshold, so the
-constant exists as a safety rail rather than a normal control knob.
+The accumulator stores genomes, not indices, because the returned fronts are
+meant to be consumed by later crowding and archive code. The conversion from
+stable indices to genome references happens only after the current layer has
+been fully identified.
+
+Parameters:
+- `paretoFronts` - - Accumulator for Pareto fronts.
+- `population` - - Genome population.
+- `currentFrontIndices` - - Indices for the current front.
 
 ### buildNextFrontIndices
 
@@ -115,26 +113,42 @@ Parameters:
 
 Returns: Indices for the next front.
 
-### annotateGenomeRank
+### buildParetoFronts
 
 ```ts
-annotateGenomeRank(
+buildParetoFronts(
   population: default[],
-  genomeIndex: number,
-  frontRank: number,
-): void
+  dominanceState: DominanceState,
+  maxFrontRankGuard: number,
+): default[][]
 ```
 
-Annotates a genome with its Pareto front rank.
+Builds Pareto fronts from a precomputed dominance state.
 
-Ranking is stored directly on the genome so later selection, telemetry, and
-archive helpers can read one stable annotation instead of carrying a parallel
-rank table beside the population.
+This performs the “peeling” phase of fast non-dominated sorting:
+- Start with the first front (all non-dominated genomes).
+- For each front, reduce domination counts of the genomes it dominates.
+- Each genome whose domination count becomes zero moves to the next front.
+
+The implementation is intentionally breadth-first. It never revisits pairwise
+comparisons; instead it trusts the dominance-state handoff and repeatedly
+relaxes domination counts until the next layer becomes visible.
+
+Side effects:
+- Annotates each genome in `population` with `_moRank` (0 = best front).
+
+Guard:
+- Stops when `currentFrontRank > maxFrontRankGuard` to avoid pathological
+  infinite/degenerate runs. If the guard triggers, the returned fronts may
+  be incomplete.
 
 Parameters:
-- `population` - - Genome population.
-- `genomeIndex` - - Index of the genome to annotate.
-- `frontRank` - - Pareto front rank (0 = best front).
+- `population` - - Genome population (same ordering used by dominance
+bookkeeping).
+- `dominanceState` - - Dominance bookkeeping.
+- `maxFrontRankGuard` - - Safety guard for ranking iterations.
+
+Returns: Ordered Pareto fronts (rank order).
 
 ### collectNextFrontIndices
 
@@ -159,29 +173,6 @@ Parameters:
 - `genomeIndex` - - Index of the current genome.
 - `nextFrontIndices` - - Accumulator for the next front.
 
-### appendFront
-
-```ts
-appendFront(
-  paretoFronts: default[][],
-  population: default[],
-  currentFrontIndices: number[],
-): void
-```
-
-Appends the current front (index list) as genome references to the
-`paretoFronts` accumulator.
-
-The accumulator stores genomes, not indices, because the returned fronts are
-meant to be consumed by later crowding and archive code. The conversion from
-stable indices to genome references happens only after the current layer has
-been fully identified.
-
-Parameters:
-- `paretoFronts` - - Accumulator for Pareto fronts.
-- `population` - - Genome population.
-- `currentFrontIndices` - - Indices for the current front.
-
 ### incrementFrontRank
 
 ```ts
@@ -200,6 +191,15 @@ Parameters:
 
 Returns: Incremented front rank.
 
+### MAX_PARETO_FRONT_RANK_GUARD
+
+Maximum number of Pareto fronts to allow during ranking before aborting.
+
+This is a defensive guard against pathological conditions (e.g., corrupted
+dominance bookkeeping) that could otherwise cause long/infinite loops.
+A healthy ranking pass should terminate well before this threshold, so the
+constant exists as a safety rail rather than a normal control knob.
+
 ### shouldStopFrontRanking
 
 ```ts