@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/asciiMaze/mazeMovement/runtime/README.md

@@ -19,46 +19,25 @@ define the world state that policy, shaping, and finalization build on top of.
 
 ## mazeMovement/runtime/mazeMovement.runtime.ts
 
-### isMazeMovementCellOpen
-
-```ts
-isMazeMovementCellOpen(
-  encodedMaze: readonly (readonly number[])[],
-  x: number,
-  y: number,
-  coordinateScratch: Int32Array<ArrayBufferLike>,
-): boolean
-```
-
-Determine whether a maze cell is inside bounds and not a wall.
-
-Parameters:
-- `encodedMaze` - - Maze grid to inspect.
-- `x` - - Zero-based maze column.
-- `y` - - Zero-based maze row.
-- `coordinateScratch` - - Reused integer scratch buffer for coordinate coercion.
-
-Returns: True when the target cell is within bounds and open.
-
-### getMazeMovementDistance
+### buildMazeMovementVisionAndDistance
 
 ```ts
-getMazeMovementDistance(
-  encodedMaze: readonly (readonly number[])[],
-  __1: readonly [number, number],
+buildMazeMovementVisionAndDistance(
+  state: SimulationState,
+  encodedMaze: number[][],
+  exitPos: readonly [number, number],
   distanceMap: number[][] | undefined,
-): number
+): void
 ```
 
-Resolve the current distance value for a maze coordinate.
+Build the current perception vector and update distance-tracking state.
 
 Parameters:
-- `encodedMaze` - - Maze grid aligned with the optional distance map.
-- `coordinates` - - Zero-based `[x, y]` coordinate tuple.
+- `state` - - Mutable simulation state for the active run.
+- `encodedMaze` - - Maze grid used for perception and distance lookup.
+- `exitPos` - - Goal coordinate for the current run.
 - `distanceMap` - - Optional precomputed distance map.
 
-Returns: Finite distance when present, otherwise `Infinity`.
-
 ### createMazeMovementRunState
 
 ```ts
@@ -80,20 +59,24 @@ Parameters:
 
 Returns: Fresh simulation state backed by the shared buffer pools.
 
-### pushMazeMovementHistory
+### getMazeMovementDistance
 
 ```ts
-pushMazeMovementHistory(
-  state: SimulationState,
-  cellIndex: number,
-): void
+getMazeMovementDistance(
+  encodedMaze: readonly (readonly number[])[],
+  __1: readonly [number, number],
+  distanceMap: number[][] | undefined,
+): number
 ```
 
-Push a cell index into the circular visit-history ring.
+Resolve the current distance value for a maze coordinate.
 
 Parameters:
-- `state` - - Mutable simulation state containing the ring buffer.
-- `cellIndex` - - Linearized cell index to append.
+- `encodedMaze` - - Maze grid aligned with the optional distance map.
+- `coordinates` - - Zero-based `[x, y]` coordinate tuple.
+- `distanceMap` - - Optional precomputed distance map.
+
+Returns: Finite distance when present, otherwise `Infinity`.
 
 ### getMazeMovementHistoryFromEnd
 
@@ -112,34 +95,51 @@ Parameters:
 
 Returns: The requested cell index or `undefined` when out of range.
 
-### recordMazeMovementVisitAndPenalties
+### isMazeMovementCellOpen
 
 ```ts
-recordMazeMovementVisitAndPenalties(
+isMazeMovementCellOpen(
+  encodedMaze: readonly (readonly number[])[],
+  x: number,
+  y: number,
+  coordinateScratch: Int32Array<ArrayBufferLike>,
+): boolean
+```
+
+Determine whether a maze cell is inside bounds and not a wall.
+
+Parameters:
+- `encodedMaze` - - Maze grid to inspect.
+- `x` - - Zero-based maze column.
+- `y` - - Zero-based maze row.
+- `coordinateScratch` - - Reused integer scratch buffer for coordinate coercion.
+
+Returns: True when the target cell is within bounds and open.
+
+### pushMazeMovementHistory
+
+```ts
+pushMazeMovementHistory(
   state: SimulationState,
+  cellIndex: number,
 ): void
 ```
 
-Record the current cell visit and update visit-driven penalties.
+Push a cell index into the circular visit-history ring.
 
 Parameters:
-- `state` - - Mutable simulation state for the active run.
+- `state` - - Mutable simulation state containing the ring buffer.
+- `cellIndex` - - Linearized cell index to append.
 
-### buildMazeMovementVisionAndDistance
+### recordMazeMovementVisitAndPenalties
 
 ```ts
-buildMazeMovementVisionAndDistance(
+recordMazeMovementVisitAndPenalties(
   state: SimulationState,
-  encodedMaze: number[][],
-  exitPos: readonly [number, number],
-  distanceMap: number[][] | undefined,
 ): void
 ```
 
-Build the current perception vector and update distance-tracking state.
+Record the current cell visit and update visit-driven penalties.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `encodedMaze` - - Maze grid used for perception and distance lookup.
-- `exitPos` - - Goal coordinate for the current run.
-- `distanceMap` - - Optional precomputed distance map.

package/test/examples/asciiMaze/mazeMovement/shaping/README.md

@@ -18,113 +18,111 @@ this boundary turns the aftermath into training signal.
 
 ## mazeMovement/shaping/mazeMovement.shaping.ts
 
-### executeMazeMovementAndRewards
+### applyMazeMovementEntropyGuidanceShaping
 
 ```ts
-executeMazeMovementAndRewards(
+applyMazeMovementEntropyGuidanceShaping(
   state: SimulationState,
-  encodedMaze: number[][],
-  distanceMap: number[][] | undefined,
+  rewardScale: number,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Execute the chosen move and apply the shaping terms tied to that move.
+Apply entropy-guided shaping based on confidence and perceptual guidance.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `encodedMaze` - - Maze grid used for move validity and distance lookup.
-- `distanceMap` - - Optional precomputed distance map.
+- `rewardScale` - - Global reward scale used by the penalties and bonuses.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementPostActionPenalties
+### applyMazeMovementExplorationVisitAdjustment
 
 ```ts
-applyMazeMovementPostActionPenalties(
+applyMazeMovementExplorationVisitAdjustment(
   state: SimulationState,
+  rewardScale: number,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply the post-action shaping and penalty aggregation phase.
+Apply the per-cell exploration bonus or revisit penalty.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
+- `rewardScale` - - Global reward scale used by the adjustment.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementLocalAreaPenalty
+### applyMazeMovementGlobalDistanceImprovementBonus
 
 ```ts
-applyMazeMovementLocalAreaPenalty(
+applyMazeMovementGlobalDistanceImprovementBonus(
   state: SimulationState,
+  encodedMaze: number[][],
   rewardScale: number,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply a local-area stagnation penalty when the run oscillates in a tight window.
+Apply the long-horizon global-distance improvement bonus.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `rewardScale` - - Global reward scale used for the penalty magnitude.
+- `encodedMaze` - - Maze grid used for distance lookup.
+- `rewardScale` - - Global reward scale used by the bonus magnitude.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementProgressShaping
+### applyMazeMovementLocalAreaPenalty
 
 ```ts
-applyMazeMovementProgressShaping(
+applyMazeMovementLocalAreaPenalty(
   state: SimulationState,
-  distanceDelta: number,
-  improved: boolean,
-  worsened: boolean,
   rewardScale: number,
+  coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply progress and away-from-goal shaping after a move.
+Apply a local-area stagnation penalty when the run oscillates in a tight window.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `distanceDelta` - - Positive when the agent moved closer to the goal.
-- `improved` - - True when the move improved distance to the goal.
-- `worsened` - - True when the move increased distance to the goal.
-- `rewardScale` - - Global reward scale used by the shaping terms.
+- `rewardScale` - - Global reward scale used for the penalty magnitude.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementExplorationVisitAdjustment
+### applyMazeMovementPostActionPenalties
 
 ```ts
-applyMazeMovementExplorationVisitAdjustment(
+applyMazeMovementPostActionPenalties(
   state: SimulationState,
-  rewardScale: number,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply the per-cell exploration bonus or revisit penalty.
+Apply the post-action shaping and penalty aggregation phase.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `rewardScale` - - Global reward scale used by the adjustment.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementGlobalDistanceImprovementBonus
+### applyMazeMovementProgressShaping
 
 ```ts
-applyMazeMovementGlobalDistanceImprovementBonus(
+applyMazeMovementProgressShaping(
   state: SimulationState,
-  encodedMaze: number[][],
+  distanceDelta: number,
+  improved: boolean,
+  worsened: boolean,
   rewardScale: number,
-  coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply the long-horizon global-distance improvement bonus.
+Apply progress and away-from-goal shaping after a move.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `encodedMaze` - - Maze grid used for distance lookup.
-- `rewardScale` - - Global reward scale used by the bonus magnitude.
-- `coordinateScratch` - - Reused coordinate scratch buffer.
+- `distanceDelta` - - Positive when the agent moved closer to the goal.
+- `improved` - - True when the move improved distance to the goal.
+- `worsened` - - True when the move increased distance to the goal.
+- `rewardScale` - - Global reward scale used by the shaping terms.
 
 ### applyMazeMovementRepetitionAndBacktrackPenalties
 
@@ -143,38 +141,40 @@ Parameters:
 - `rewardScale` - - Global reward scale used by the penalties.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementEntropyGuidanceShaping
+### applyMazeMovementSaturationPenaltyCycle
 
 ```ts
-applyMazeMovementEntropyGuidanceShaping(
+applyMazeMovementSaturationPenaltyCycle(
   state: SimulationState,
   rewardScale: number,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply entropy-guided shaping based on confidence and perceptual guidance.
+Apply the periodic saturation penalty cycle.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `rewardScale` - - Global reward scale used by the penalties and bonuses.
+- `rewardScale` - - Global reward scale used by the penalties.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementSaturationPenaltyCycle
+### executeMazeMovementAndRewards
 
 ```ts
-applyMazeMovementSaturationPenaltyCycle(
+executeMazeMovementAndRewards(
   state: SimulationState,
-  rewardScale: number,
+  encodedMaze: number[][],
+  distanceMap: number[][] | undefined,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply the periodic saturation penalty cycle.
+Execute the chosen move and apply the shaping terms tied to that move.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `rewardScale` - - Global reward scale used by the penalties.
+- `encodedMaze` - - Maze grid used for move validity and distance lookup.
+- `distanceMap` - - Optional precomputed distance map.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
 ### maybeTerminateMazeMovementDeepStagnation