@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/adaptive/README.md

@@ -49,6 +49,71 @@ flowchart TD
 
 ## neat/adaptive/adaptive.ts
 
+### applyAdaptiveMutation
+
+```ts
+applyAdaptiveMutation(): void
+```
+
+Self-adaptive per-genome mutation tuning.
+
+This function implements several strategies to adjust each genome's
+internal mutation rate (`g._mutRate`) and optionally its mutation
+amount (`g._mutAmount`) over time. Strategies include:
+- `twoTier`: push top and bottom halves in opposite directions to
+  create exploration/exploitation balance.
+- `exploreLow`: preferentially increase mutation for lower-scoring
+  genomes to promote exploration.
+- `anneal`: gradually reduce mutation deltas over time.
+
+The method reads `this.options.adaptiveMutation` for configuration
+and mutates genomes in-place.
+
+This is the adaptive controller that feeds most directly into the root
+mutation chapter. Rather than choosing one operator itself, it adjusts each
+genome's readiness for later mutation so the next structural-edit pass can be
+more exploratory or more conservative depending on recent success.
+
+Returns: Updates per-genome mutation-rate state in place when the current generation satisfies the adaptation cadence.
+
+Example:
+
+// configuration example:
+// options.adaptiveMutation = { enabled: true, initialRate: 0.5, adaptEvery: 1, strategy: 'twoTier', minRate: 0.01, maxRate: 1 }
+engine.applyAdaptiveMutation();
+
+### applyAncestorUniqAdaptive
+
+```ts
+applyAncestorUniqAdaptive(): void
+```
+
+Adaptive adjustments based on ancestor uniqueness telemetry.
+
+This helper inspects the most recent telemetry lineage block (if
+available) for an `ancestorUniq` metric indicating how unique
+ancestry is across the population. If ancestry uniqueness drifts
+outside configured thresholds, the method will adjust either the
+multi-objective dominance epsilon (if `mode === 'epsilon'`) or the
+lineage pressure strength (if `mode === 'lineagePressure'`).
+
+This makes the lineage controller the feedback bridge between telemetry and
+future search policy. It does not rewrite the current population directly;
+instead it nudges the options that govern how later multi-objective or
+lineage-pressure decisions behave.
+
+Typical usage: keep population lineage diversity within a healthy
+band. Low ancestor uniqueness means too many genomes share ancestors
+(risking premature convergence); high uniqueness might indicate
+excessive divergence.
+
+Returns: May update lineage-related controller options and record the most recent adjustment generation.
+
+Example:
+
+// Adjusts `options.multiObjective.dominanceEpsilon` when configured
+engine.applyAncestorUniqAdaptive();
+
 ### applyComplexityBudget
 
 ```ts
@@ -91,33 +156,6 @@ Example:
 engine.applyComplexityBudget();
 // engine.options.maxNodes now holds the adjusted complexity cap
 
-### applyPhasedComplexity
-
-```ts
-applyPhasedComplexity(): void
-```
-
-Toggle phased complexity mode between 'complexify' and 'simplify'.
-
-Phased complexity supports alternating periods where the algorithm
-is encouraged to grow (complexify) or shrink (simplify) network
-structures. This can help escape local minima or reduce bloat.
-
-Use this controller when one static mutation policy is not enough. Instead of
-adjusting caps continuously like `applyComplexityBudget()`, this helper flips
-the controller into a new structural mood and records when that phase began.
-
-The current phase and its start generation are stored on `this` as
-`_phase` and `_phaseStartGeneration` so the state persists across
-generations.
-
-Returns: Mutates `this._phase` and `this._phaseStartGeneration` so later mutation-selection code knows whether to favor growth or simplification.
-
-Example:
-
-// Called once per generation to update the phase state
-engine.applyPhasedComplexity();
-
 ### applyMinimalCriterionAdaptive
 
 ```ts
@@ -152,6 +190,61 @@ Example:
 // options.minimalCriterionAdaptive = { enabled: true, initialThreshold: 0.1, targetAcceptance: 0.5, adjustRate: 0.1 }
 engine.applyMinimalCriterionAdaptive();
 
+### applyOperatorAdaptation
+
+```ts
+applyOperatorAdaptation(): void
+```
+
+Decay operator adaptation statistics (success/attempt counters).
+
+Many adaptive operator-selection schemes keep running tallies of how
+successful each operator has been. This helper applies an exponential
+moving-average style decay to those counters so older outcomes
+progressively matter less.
+
+Use this controller when operator adaptation is enabled and you want the
+mutation selector to favor recent evidence over stale wins from much earlier
+generations. It is a policy-maintenance helper, not an operator chooser by
+itself.
+
+The `_operatorStats` map on `this` is expected to contain values of
+the shape `{ success: number, attempts: number }` keyed by operator
+id/name.
+
+Returns: Decays `_operatorStats` in place so later mutation-method selection reflects more recent operator performance.
+
+Example:
+
+engine.applyOperatorAdaptation();
+
+### applyPhasedComplexity
+
+```ts
+applyPhasedComplexity(): void
+```
+
+Toggle phased complexity mode between 'complexify' and 'simplify'.
+
+Phased complexity supports alternating periods where the algorithm
+is encouraged to grow (complexify) or shrink (simplify) network
+structures. This can help escape local minima or reduce bloat.
+
+Use this controller when one static mutation policy is not enough. Instead of
+adjusting caps continuously like `applyComplexityBudget()`, this helper flips
+the controller into a new structural mood and records when that phase began.
+
+The current phase and its start generation are stored on `this` as
+`_phase` and `_phaseStartGeneration` so the state persists across
+generations.
+
+Returns: Mutates `this._phase` and `this._phaseStartGeneration` so later mutation-selection code knows whether to favor growth or simplification.
+
+Example:
+
+// Called once per generation to update the phase state
+engine.applyPhasedComplexity();
+
 ### NeatLikeWithAdaptive
 
 Contract map for the adaptive helper boundary.
@@ -186,96 +279,3 @@ flowchart TD
   Options --> Mutation[Mutation and operator adaptation]
   Options --> Lineage[Ancestor uniqueness and lineage pressure]
 ```
-
-### applyAncestorUniqAdaptive
-
-```ts
-applyAncestorUniqAdaptive(): void
-```
-
-Adaptive adjustments based on ancestor uniqueness telemetry.
-
-This helper inspects the most recent telemetry lineage block (if
-available) for an `ancestorUniq` metric indicating how unique
-ancestry is across the population. If ancestry uniqueness drifts
-outside configured thresholds, the method will adjust either the
-multi-objective dominance epsilon (if `mode === 'epsilon'`) or the
-lineage pressure strength (if `mode === 'lineagePressure'`).
-
-This makes the lineage controller the feedback bridge between telemetry and
-future search policy. It does not rewrite the current population directly;
-instead it nudges the options that govern how later multi-objective or
-lineage-pressure decisions behave.
-
-Typical usage: keep population lineage diversity within a healthy
-band. Low ancestor uniqueness means too many genomes share ancestors
-(risking premature convergence); high uniqueness might indicate
-excessive divergence.
-
-Returns: May update lineage-related controller options and record the most recent adjustment generation.
-
-Example:
-
-// Adjusts `options.multiObjective.dominanceEpsilon` when configured
-engine.applyAncestorUniqAdaptive();
-
-### applyAdaptiveMutation
-
-```ts
-applyAdaptiveMutation(): void
-```
-
-Self-adaptive per-genome mutation tuning.
-
-This function implements several strategies to adjust each genome's
-internal mutation rate (`g._mutRate`) and optionally its mutation
-amount (`g._mutAmount`) over time. Strategies include:
-- `twoTier`: push top and bottom halves in opposite directions to
-  create exploration/exploitation balance.
-- `exploreLow`: preferentially increase mutation for lower-scoring
-  genomes to promote exploration.
-- `anneal`: gradually reduce mutation deltas over time.
-
-The method reads `this.options.adaptiveMutation` for configuration
-and mutates genomes in-place.
-
-This is the adaptive controller that feeds most directly into the root
-mutation chapter. Rather than choosing one operator itself, it adjusts each
-genome's readiness for later mutation so the next structural-edit pass can be
-more exploratory or more conservative depending on recent success.
-
-Returns: Updates per-genome mutation-rate state in place when the current generation satisfies the adaptation cadence.
-
-Example:
-
-// configuration example:
-// options.adaptiveMutation = { enabled: true, initialRate: 0.5, adaptEvery: 1, strategy: 'twoTier', minRate: 0.01, maxRate: 1 }
-engine.applyAdaptiveMutation();
-
-### applyOperatorAdaptation
-
-```ts
-applyOperatorAdaptation(): void
-```
-
-Decay operator adaptation statistics (success/attempt counters).
-
-Many adaptive operator-selection schemes keep running tallies of how
-successful each operator has been. This helper applies an exponential
-moving-average style decay to those counters so older outcomes
-progressively matter less.
-
-Use this controller when operator adaptation is enabled and you want the
-mutation selector to favor recent evidence over stale wins from much earlier
-generations. It is a policy-maintenance helper, not an operator chooser by
-itself.
-
-The `_operatorStats` map on `this` is expected to contain values of
-the shape `{ success: number, attempts: number }` keyed by operator
-id/name.
-
-Returns: Decays `_operatorStats` in place so later mutation-method selection reflects more recent operator performance.
-
-Example:
-
-engine.applyOperatorAdaptation();

package/src/neat/adaptive/acceptance/README.md

@@ -224,25 +224,34 @@ The helper flow is intentionally compact:
 3. measure how much of the population clears the bar,
 4. retune the threshold and reject genomes that still miss it.
 
-### initializeThreshold
+### applyRejection
 
 ```ts
-initializeThreshold(
+applyRejection(
   engine: NeatLikeWithAdaptive,
-  config: { enabled?: boolean | undefined; initialThreshold?: number | undefined; targetAcceptance?: number | undefined; adjustRate?: number | undefined; },
+  threshold: number,
 ): void
 ```
 
-Initialize MC threshold if missing.
+Zero scores below the final threshold.
 
-Threshold initialization is lazy because many runs never enable adaptive
-acceptance at all. The first invocation seeds the long-lived threshold, and
-later generations reuse the updated value rather than restarting from the
-original configuration each time.
+Rejection is the acceptance chapter's most direct intervention. Instead of
+queuing a future policy change, it rewrites the current generation's scores so
+the same selection pass immediately treats low-performing genomes as filtered
+out.
+
+Example:
+
+```ts
+const scores = collectScores(engine);
+const acceptance = computeAcceptance(scores, engine._mcThreshold ?? 0);
+updateThreshold(engine, acceptance, resolveTargetSettings(config));
+applyRejection(engine, engine._mcThreshold ?? 0);
+```
 
 Parameters:
 - `engine` - - NEAT engine instance.
-- `config` - - Minimal-criterion adaptive configuration.
+- `threshold` - - Final MC threshold.
 
 Returns: Nothing.
 
@@ -288,6 +297,28 @@ Parameters:
 
 Returns: Acceptance proportion.
 
+### initializeThreshold
+
+```ts
+initializeThreshold(
+  engine: NeatLikeWithAdaptive,
+  config: { enabled?: boolean | undefined; initialThreshold?: number | undefined; targetAcceptance?: number | undefined; adjustRate?: number | undefined; },
+): void
+```
+
+Initialize MC threshold if missing.
+
+Threshold initialization is lazy because many runs never enable adaptive
+acceptance at all. The first invocation seeds the long-lived threshold, and
+later generations reuse the updated value rather than restarting from the
+original configuration each time.
+
+Parameters:
+- `engine` - - NEAT engine instance.
+- `config` - - Minimal-criterion adaptive configuration.
+
+Returns: Nothing.
+
 ### resolveTargetSettings
 
 ```ts
@@ -328,34 +359,3 @@ Parameters:
 - `tuning` - - Target acceptance and adjustment settings.
 
 Returns: Nothing.
-
-### applyRejection
-
-```ts
-applyRejection(
-  engine: NeatLikeWithAdaptive,
-  threshold: number,
-): void
-```
-
-Zero scores below the final threshold.
-
-Rejection is the acceptance chapter's most direct intervention. Instead of
-queuing a future policy change, it rewrites the current generation's scores so
-the same selection pass immediately treats low-performing genomes as filtered
-out.
-
-Example:
-
-```ts
-const scores = collectScores(engine);
-const acceptance = computeAcceptance(scores, engine._mcThreshold ?? 0);
-updateThreshold(engine, acceptance, resolveTargetSettings(config));
-applyRejection(engine, engine._mcThreshold ?? 0);
-```
-
-Parameters:
-- `engine` - - NEAT engine instance.
-- `threshold` - - Final MC threshold.
-
-Returns: Nothing.