@reicek/neataptic-ts 0.1.24 → 0.1.26

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

@@ -44,170 +44,113 @@ missing context is how the fronts themselves were constructed.
 
 ## neat/multiobjective/crowding/multiobjective.crowding.ts
 
-### buildGenomeIndexByReference
-
-```ts
-buildGenomeIndexByReference(
-  population: default[],
-): Map<default, number>
-```
-
-Builds a stable mapping from genome object references to their population
-index.
-
-This relies on object identity (reference equality), not structural
-equality. It is used to resolve objective values from a values matrix when
-working with reordered views such as per-objective sorted fronts.
-The map preserves the controller's original population order even while this
-chapter temporarily reorders front-local views for spacing calculations.
-
-Parameters:
-- `population` - - Genomes in population order.
-
-Returns: Map from genome references to their index.
-
-### resolveGenomeIndex
-
-```ts
-resolveGenomeIndex(
-  genomeIndexByReference: Map<default, number>,
-  genomeItem: default,
-): number
-```
-
-Resolves a genome’s index using a reference-based map.
-
-Crowding works with reordered arrays of genome references, but the value
-matrix still lives in population order. This lookup reconnects those two
-views without copying the matrix.
-
-Parameters:
-- `genomeIndexByReference` - - Lookup map created by
- *  {@link buildGenomeIndexByReference} .
-- `genomeItem` - - Genome to resolve.
-
-Returns: The population index of the genome.
-
-### resolveObjectiveValue
+### accumulateCrowdingForObjective
 
 ```ts
-resolveObjectiveValue(
+accumulateCrowdingForObjective(
+  sortedFront: default[],
   valuesMatrixInput: number[][],
   genomeIndexByReference: Map<default, number>,
-  genomeItem: default,
   objectiveIndex: number,
-): number
-```
-
-Resolves an objective value for a genome from a values matrix.
-
-This is a convenience helper for working with sorted/reordered views of the
-population while keeping objective values in a dense matrix.
-It lets the crowding pass ask "what is this genome's value on the current
-objective?" without assuming the front is still in population order.
-
-Parameters:
-- `valuesMatrixInput` - - Values matrix indexed by population index.
-- `genomeIndexByReference` - - Lookup map from genome reference to index.
-- `genomeItem` - - Genome to resolve.
-- `objectiveIndex` - - Objective column index.
-
-Returns: The objective value for the genome.
-
-### initializeCrowding
-
-```ts
-initializeCrowding(
-  front: default[],
 ): void
 ```
 
-Initializes crowding-distance annotations for a front.
+Accumulates crowding distance contributions for a single objective.
 
-This sets each genome’s `_moCrowd` to `0`. Later steps accumulate per-
-objective spacing deltas.
+Pre-conditions / expectations:
+- `sortedFront` must be sorted ascending by the selected objective.
+- {@link initializeCrowding} has already set `_moCrowd = 0` for the front.
+- {@link markBoundaryCrowding} is typically called before this to set the
+  boundary genomes to `Infinity`.
 
-Resetting the field once per front keeps the later per-objective helpers
-additive and makes the final score easy to interpret as one accumulated
-spacing signal across all objectives.
+Edge cases:
+- If the front has fewer than 2 genomes, this is a no-op.
+- If the objective range is `0`, a range of `1` is used (see
+  {@link resolveObjectiveRange}).
+
+This helper deliberately ignores objective direction. Crowding measures raw
+spacing between neighboring values, so the same frontier width matters
+whether the controller is minimizing or maximizing that objective.
 
 Parameters:
-- `front` - - Pareto front.
+- `sortedFront` - - Front sorted by objective.
+- `valuesMatrixInput` - - Values matrix.
+- `genomeIndexByReference` - - Lookup map.
+- `objectiveIndex` - - Objective column index.
 
-### markBoundaryCrowding
+### accumulateInteriorCrowding
 
 ```ts
-markBoundaryCrowding(
+accumulateInteriorCrowding(
   sortedFront: default[],
+  valuesMatrixInput: number[][],
+  genomeIndexByReference: Map<default, number>,
+  objectiveIndex: number,
+  valueRange: number,
 ): void
 ```
 
-Marks the boundary genomes of a sorted front as infinitely crowded.
+Accumulates crowding deltas for the interior genomes of a sorted front.
 
-In NSGA-II style crowding distance, boundary solutions (extremes for the
-objective) are assigned an infinite crowding distance to ensure they are
-always preferred when ranks tie.
+Interior genomes receive a normalized spacing delta:
+`delta = (nextValue - previousValue) / valueRange`.
 
-This preserves the ends of the tradeoff surface. Even when interior genomes
-become densely packed, the extreme solutions remain available to later
-selection because they carry unique objective-space coverage.
+Looking at both neighbors matters because crowding is trying to estimate how
+much empty objective-space surrounds the current genome, not merely whether
+it differs from one adjacent point.
 
 Parameters:
-- `sortedFront` - - Front sorted by the current objective.
+- `sortedFront` - - Front sorted by objective.
+- `valuesMatrixInput` - - Values matrix.
+- `genomeIndexByReference` - - Lookup map.
+- `objectiveIndex` - - Objective column index.
+- `valueRange` - - Normalized objective range.
 
-### resolveObjectiveRange
+### applyCrowdingDelta
 
 ```ts
-resolveObjectiveRange(
-  minValue: number,
-  maxValue: number,
-): number
+applyCrowdingDelta(
+  currentGenome: NetworkWithMOAnnotations,
+  previousValue: number,
+  nextValue: number,
+  valueRange: number,
+): void
 ```
 
-Resolves a non-zero objective range used to normalize crowding deltas.
+Applies a normalized crowding-distance delta to a genome.
 
-If all genomes have the same objective value, the raw range is `0`. This
-returns `1` in that case to avoid division by zero while still producing a
-well-defined crowding delta of `0`.
-The fallback means a flat objective contributes no spacing signal instead of
-exploding numerically or distorting the remaining objectives.
+If the genome’s crowding distance is `Infinity`, it will remain `Infinity`.
+This helper only updates when `_moCrowd` is initialized.
+That preserves the boundary-solutions rule while still allowing interior
+genomes to accumulate spacing contributions across many objectives.
 
 Parameters:
-- `minValue` - - Minimum objective value.
-- `maxValue` - - Maximum objective value.
-
-Returns: Normalized range with a non-zero floor.
+- `currentGenome` - - Genome to update.
+- `previousValue` - - Objective value of previous genome.
+- `nextValue` - - Objective value of next genome.
+- `valueRange` - - Normalized objective range.
 
-### accumulateCrowdingForObjective
+### applyCrowdingForObjective
 
 ```ts
-accumulateCrowdingForObjective(
-  sortedFront: default[],
+applyCrowdingForObjective(
+  front: default[],
   valuesMatrixInput: number[][],
   genomeIndexByReference: Map<default, number>,
   objectiveIndex: number,
 ): void
 ```
 
-Accumulates crowding distance contributions for a single objective.
-
-Pre-conditions / expectations:
-- `sortedFront` must be sorted ascending by the selected objective.
-- {@link initializeCrowding} has already set `_moCrowd = 0` for the front.
-- {@link markBoundaryCrowding} is typically called before this to set the
-  boundary genomes to `Infinity`.
-
-Edge cases:
-- If the front has fewer than 2 genomes, this is a no-op.
-- If the objective range is `0`, a range of `1` is used (see
-  {@link resolveObjectiveRange}).
+Applies crowding-distance accumulation for a single objective within a
+single front.
 
-This helper deliberately ignores objective direction. Crowding measures raw
-spacing between neighboring values, so the same frontier width matters
-whether the controller is minimizing or maximizing that objective.
+The work happens in two phases: create the sorted frontier view for the
+chosen objective, then protect its boundaries and accumulate interior
+spacing. Keeping those phases together makes the per-objective flow easy to
+audit in the generated chapter.
 
 Parameters:
-- `sortedFront` - - Front sorted by objective.
+- `front` - - Pareto front.
 - `valuesMatrixInput` - - Values matrix.
 - `genomeIndexByReference` - - Lookup map.
 - `objectiveIndex` - - Objective column index.
@@ -250,267 +193,324 @@ Parameters:
 - `descriptors` - - Objective descriptors (provides objective count).
 - `population` - - Population to resolve indices.
 
-### resolveBoundaryGenomes
+### assignCrowdingForFront
 
 ```ts
-resolveBoundaryGenomes(
-  sortedFront: default[],
-): { firstGenome: default; lastGenome: default; } | null
+assignCrowdingForFront(
+  front: default[],
+  valuesMatrixInput: number[][],
+  genomeIndexByReference: Map<default, number>,
+  objectiveIndices: number[],
+): void
 ```
 
-Resolves the boundary (first/last) genomes for a sorted front.
+Assigns crowding distances for a single front across all objectives.
 
-Parameters:
-- `sortedFront` - - Front sorted by objective.
+This helper keeps the front-local story clear: once the front exists and its
+crowding fields are initialized, simply walk the objective columns and let
+each one contribute its own spacing signal.
 
-Returns: Boundary genomes, or `null` if the front is empty.
+Parameters:
+- `front` - - Pareto front.
+- `valuesMatrixInput` - - Values matrix.
+- `genomeIndexByReference` - - Lookup map.
+- `objectiveIndices` - - Objective indices to process.
 
-### resolveObjectiveRangeFromBoundaries
+### buildGenomeIndexByReference
 
 ```ts
-resolveObjectiveRangeFromBoundaries(
-  valuesMatrixInput: number[][],
-  genomeIndexByReference: Map<default, number>,
-  boundaryGenomes: { firstGenome: default; lastGenome: default; },
-  objectiveIndex: number,
-): number
+buildGenomeIndexByReference(
+  population: default[],
+): Map<default, number>
 ```
 
-Resolves the normalized objective range for a front from its boundary
-genomes.
+Builds a stable mapping from genome object references to their population
+index.
 
-Because `sortedFront` is sorted by objective, the first and last genomes are
-the extrema used for range normalization.
+This relies on object identity (reference equality), not structural
+equality. It is used to resolve objective values from a values matrix when
+working with reordered views such as per-objective sorted fronts.
+The map preserves the controller's original population order even while this
+chapter temporarily reorders front-local views for spacing calculations.
 
 Parameters:
-- `valuesMatrixInput` - - Values matrix.
-- `genomeIndexByReference` - - Lookup map.
-- `boundaryGenomes` - - Boundary genomes for the front.
-- `objectiveIndex` - - Objective column index.
+- `population` - - Genomes in population order.
 
-Returns: Normalized value range for the objective.
+Returns: Map from genome references to their index.
 
-### accumulateInteriorCrowding
+### buildInteriorIndexRange
 
 ```ts
-accumulateInteriorCrowding(
-  sortedFront: default[],
-  valuesMatrixInput: number[][],
-  genomeIndexByReference: Map<default, number>,
-  objectiveIndex: number,
-  valueRange: number,
-): void
+buildInteriorIndexRange(
+  frontLength: number,
+): number[]
 ```
 
-Accumulates crowding deltas for the interior genomes of a sorted front.
+Builds the index range for interior genomes of a front.
 
-Interior genomes receive a normalized spacing delta:
-`delta = (nextValue - previousValue) / valueRange`.
+Boundary genomes are excluded because their crowding distance is treated as
+infinite.
 
-Looking at both neighbors matters because crowding is trying to estimate how
-much empty objective-space surrounds the current genome, not merely whether
-it differs from one adjacent point.
+Parameters:
+- `frontLength` - - Length of the sorted front.
+
+Returns: Interior indices excluding boundary genomes.
+
+### buildObjectiveIndexRange
+
+```ts
+buildObjectiveIndexRange(
+  objectiveCount: number,
+): number[]
+```
+
+Builds a stable objective index range.
+
+Keeping objective iteration explicit makes the front-level accumulation order
+easy to inspect and keeps the per-objective helper signatures small.
 
 Parameters:
-- `sortedFront` - - Front sorted by objective.
+- `objectiveCount` - - Number of objectives.
+
+Returns: Objective indices `0..objectiveCount-1`.
+
+### buildSortedFrontByObjective
+
+```ts
+buildSortedFrontByObjective(
+  front: default[],
+  valuesMatrixInput: number[][],
+  genomeIndexByReference: Map<default, number>,
+  objectiveIndex: number,
+): default[]
+```
+
+Builds a copy of the front sorted by the specified objective.
+
+Sorting is ascending by the raw objective value. This ordering is used for
+computing neighbor spacing in objective space.
+The original front array remains untouched so Pareto-rank grouping stays
+stable while each objective gets its own temporary geometric view.
+
+Parameters:
+- `front` - - Pareto front.
 - `valuesMatrixInput` - - Values matrix.
 - `genomeIndexByReference` - - Lookup map.
 - `objectiveIndex` - - Objective column index.
-- `valueRange` - - Normalized objective range.
 
-### buildInteriorIndexRange
+Returns: Front sorted by objective value.
+
+### compareObjectiveValuesForCrowding
 
 ```ts
-buildInteriorIndexRange(
-  frontLength: number,
-): number[]
+compareObjectiveValuesForCrowding(
+  valuesMatrixInput: number[][],
+  genomeIndexByReference: Map<default, number>,
+  objectiveIndex: number,
+  leftGenome: default,
+  rightGenome: default,
+): number
 ```
 
-Builds the index range for interior genomes of a front.
+Comparator used to sort genomes by a specific objective value.
 
-Boundary genomes are excluded because their crowding distance is treated as
-infinite.
+The comparator resolves values through the shared matrix so the sorted view
+stays consistent with the same objective data used during dominance and
+frontier construction.
 
 Parameters:
-- `frontLength` - - Length of the sorted front.
+- `valuesMatrixInput` - - Values matrix.
+- `genomeIndexByReference` - - Lookup map.
+- `objectiveIndex` - - Objective column index.
+- `leftGenome` - - Left genome.
+- `rightGenome` - - Right genome.
 
-Returns: Interior indices excluding boundary genomes.
+Returns: Numeric sort comparison value (ascending).
 
-### resolveNeighborPair
+### initializeCrowding
 
 ```ts
-resolveNeighborPair(
-  sortedFront: default[],
-  sortedIndex: number,
-): { previousGenome: default; nextGenome: default; }
+initializeCrowding(
+  front: default[],
+): void
 ```
 
-Resolves the neighbor genomes for an interior element of a sorted front.
+Initializes crowding-distance annotations for a front.
 
-Parameters:
-- `sortedFront` - - Front sorted by objective.
-- `sortedIndex` - - Current index in sorted front.
+This sets each genome’s `_moCrowd` to `0`. Later steps accumulate per-
+objective spacing deltas.
 
-Returns: Previous and next neighbor genomes.
+Resetting the field once per front keeps the later per-objective helpers
+additive and makes the final score easy to interpret as one accumulated
+spacing signal across all objectives.
 
-### applyCrowdingDelta
+Parameters:
+- `front` - - Pareto front.
+
+### markBoundaryCrowding
 
 ```ts
-applyCrowdingDelta(
-  currentGenome: NetworkWithMOAnnotations,
-  previousValue: number,
-  nextValue: number,
-  valueRange: number,
+markBoundaryCrowding(
+  sortedFront: default[],
 ): void
 ```
 
-Applies a normalized crowding-distance delta to a genome.
+Marks the boundary genomes of a sorted front as infinitely crowded.
 
-If the genome’s crowding distance is `Infinity`, it will remain `Infinity`.
-This helper only updates when `_moCrowd` is initialized.
-That preserves the boundary-solutions rule while still allowing interior
-genomes to accumulate spacing contributions across many objectives.
+In NSGA-II style crowding distance, boundary solutions (extremes for the
+objective) are assigned an infinite crowding distance to ensure they are
+always preferred when ranks tie.
+
+This preserves the ends of the tradeoff surface. Even when interior genomes
+become densely packed, the extreme solutions remain available to later
+selection because they carry unique objective-space coverage.
 
 Parameters:
-- `currentGenome` - - Genome to update.
-- `previousValue` - - Objective value of previous genome.
-- `nextValue` - - Objective value of next genome.
-- `valueRange` - - Normalized objective range.
+- `sortedFront` - - Front sorted by the current objective.
 
-### buildObjectiveIndexRange
+### resolveBoundaryGenomes
 
 ```ts
-buildObjectiveIndexRange(
-  objectiveCount: number,
-): number[]
+resolveBoundaryGenomes(
+  sortedFront: default[],
+): { firstGenome: default; lastGenome: default; } | null
 ```
 
-Builds a stable objective index range.
-
-Keeping objective iteration explicit makes the front-level accumulation order
-easy to inspect and keeps the per-objective helper signatures small.
+Resolves the boundary (first/last) genomes for a sorted front.
 
 Parameters:
-- `objectiveCount` - - Number of objectives.
+- `sortedFront` - - Front sorted by objective.
 
-Returns: Objective indices `0..objectiveCount-1`.
+Returns: Boundary genomes, or `null` if the front is empty.
 
-### shouldSkipCrowdingFront
+### resolveGenomeIndex
 
 ```ts
-shouldSkipCrowdingFront(
-  front: default[],
-): boolean
+resolveGenomeIndex(
+  genomeIndexByReference: Map<default, number>,
+  genomeItem: default,
+): number
 ```
 
-Determines whether crowding-distance processing should be skipped for a
-front.
+Resolves a genome’s index using a reference-based map.
 
-Empty fronts are ignored because they carry no genomes to annotate and would
-otherwise force needless setup work.
+Crowding works with reordered arrays of genome references, but the value
+matrix still lives in population order. This lookup reconnects those two
+views without copying the matrix.
 
 Parameters:
-- `front` - - Pareto front.
+- `genomeIndexByReference` - - Lookup map created by
+ *  {@link buildGenomeIndexByReference} .
+- `genomeItem` - - Genome to resolve.
 
-Returns: `true` if the front should be skipped.
+Returns: The population index of the genome.
 
-### assignCrowdingForFront
+### resolveNeighborPair
 
 ```ts
-assignCrowdingForFront(
-  front: default[],
-  valuesMatrixInput: number[][],
-  genomeIndexByReference: Map<default, number>,
-  objectiveIndices: number[],
-): void
+resolveNeighborPair(
+  sortedFront: default[],
+  sortedIndex: number,
+): { previousGenome: default; nextGenome: default; }
 ```
 
-Assigns crowding distances for a single front across all objectives.
-
-This helper keeps the front-local story clear: once the front exists and its
-crowding fields are initialized, simply walk the objective columns and let
-each one contribute its own spacing signal.
+Resolves the neighbor genomes for an interior element of a sorted front.
 
 Parameters:
-- `front` - - Pareto front.
-- `valuesMatrixInput` - - Values matrix.
-- `genomeIndexByReference` - - Lookup map.
-- `objectiveIndices` - - Objective indices to process.
+- `sortedFront` - - Front sorted by objective.
+- `sortedIndex` - - Current index in sorted front.
 
-### applyCrowdingForObjective
+Returns: Previous and next neighbor genomes.
+
+### resolveObjectiveRange
 
 ```ts
-applyCrowdingForObjective(
-  front: default[],
-  valuesMatrixInput: number[][],
-  genomeIndexByReference: Map<default, number>,
-  objectiveIndex: number,
-): void
+resolveObjectiveRange(
+  minValue: number,
+  maxValue: number,
+): number
 ```
 
-Applies crowding-distance accumulation for a single objective within a
-single front.
+Resolves a non-zero objective range used to normalize crowding deltas.
 
-The work happens in two phases: create the sorted frontier view for the
-chosen objective, then protect its boundaries and accumulate interior
-spacing. Keeping those phases together makes the per-objective flow easy to
-audit in the generated chapter.
+If all genomes have the same objective value, the raw range is `0`. This
+returns `1` in that case to avoid division by zero while still producing a
+well-defined crowding delta of `0`.
+The fallback means a flat objective contributes no spacing signal instead of
+exploding numerically or distorting the remaining objectives.
 
 Parameters:
-- `front` - - Pareto front.
-- `valuesMatrixInput` - - Values matrix.
-- `genomeIndexByReference` - - Lookup map.
-- `objectiveIndex` - - Objective column index.
+- `minValue` - - Minimum objective value.
+- `maxValue` - - Maximum objective value.
 
-### buildSortedFrontByObjective
+Returns: Normalized range with a non-zero floor.
+
+### resolveObjectiveRangeFromBoundaries
 
 ```ts
-buildSortedFrontByObjective(
-  front: default[],
+resolveObjectiveRangeFromBoundaries(
   valuesMatrixInput: number[][],
   genomeIndexByReference: Map<default, number>,
+  boundaryGenomes: { firstGenome: default; lastGenome: default; },
   objectiveIndex: number,
-): default[]
+): number
 ```
 
-Builds a copy of the front sorted by the specified objective.
+Resolves the normalized objective range for a front from its boundary
+genomes.
 
-Sorting is ascending by the raw objective value. This ordering is used for
-computing neighbor spacing in objective space.
-The original front array remains untouched so Pareto-rank grouping stays
-stable while each objective gets its own temporary geometric view.
+Because `sortedFront` is sorted by objective, the first and last genomes are
+the extrema used for range normalization.
 
 Parameters:
-- `front` - - Pareto front.
 - `valuesMatrixInput` - - Values matrix.
 - `genomeIndexByReference` - - Lookup map.
+- `boundaryGenomes` - - Boundary genomes for the front.
 - `objectiveIndex` - - Objective column index.
 
-Returns: Front sorted by objective value.
+Returns: Normalized value range for the objective.
 
-### compareObjectiveValuesForCrowding
+### resolveObjectiveValue
 
 ```ts
-compareObjectiveValuesForCrowding(
+resolveObjectiveValue(
   valuesMatrixInput: number[][],
   genomeIndexByReference: Map<default, number>,
+  genomeItem: default,
   objectiveIndex: number,
-  leftGenome: default,
-  rightGenome: default,
 ): number
 ```
 
-Comparator used to sort genomes by a specific objective value.
+Resolves an objective value for a genome from a values matrix.
 
-The comparator resolves values through the shared matrix so the sorted view
-stays consistent with the same objective data used during dominance and
-frontier construction.
+This is a convenience helper for working with sorted/reordered views of the
+population while keeping objective values in a dense matrix.
+It lets the crowding pass ask "what is this genome's value on the current
+objective?" without assuming the front is still in population order.
 
 Parameters:
-- `valuesMatrixInput` - - Values matrix.
-- `genomeIndexByReference` - - Lookup map.
+- `valuesMatrixInput` - - Values matrix indexed by population index.
+- `genomeIndexByReference` - - Lookup map from genome reference to index.
+- `genomeItem` - - Genome to resolve.
 - `objectiveIndex` - - Objective column index.
-- `leftGenome` - - Left genome.
-- `rightGenome` - - Right genome.
 
-Returns: Numeric sort comparison value (ascending).
+Returns: The objective value for the genome.
+
+### shouldSkipCrowdingFront
+
+```ts
+shouldSkipCrowdingFront(
+  front: default[],
+): boolean
+```
+
+Determines whether crowding-distance processing should be skipped for a
+front.
+
+Empty fronts are ignored because they carry no genomes to annotate and would
+otherwise force needless setup work.
+
+Parameters:
+- `front` - - Pareto front.
+
+Returns: `true` if the front should be skipped.