Statistics.md

Statistics

This page explains how MicroChess tracks performance metrics and game statistics using the stats_t class, defined in stats.h and stats.cpp. These statistics provide insights into the chess engine’s efficiency and behavior, crucial for debugging and optimization on Arduino’s constrained resources (less than 2K RAM).

Overview

The stats_t class collects and manages data about the engine’s performance, such as the number of nodes searched, time taken per move, and game outcomes. This information helps developers tune the engine and monitor its operation, especially under Arduino’s memory and processing limitations.

The stats_t Class

The stats_t class, defined in stats.h and implemented in stats.cpp, stores key metrics and provides methods to update and retrieve them. Key attributes include:

• Nodes Searched: The total number of board positions evaluated during the minimax search.
• Search Time: The time (in milliseconds) spent on each move or search iteration.
• Nodes per Second: The rate of node evaluations (nodes searched ÷ search time).
• Move Count: The number of moves played in the current game.
• Game Outcomes: Counts of wins, losses, draws, checkmates, and stalemates.
• Evaluation Scores: Tracks the range of scores returned by the evaluation function.

Key Methods

• Constructor: Initializes counters (e.g., nodes=0, time=0).
• incrementNodes(count): Adds to the nodes searched counter.
• addSearchTime(ms): Records time spent on a search.
• getNodesPerSecond(): Calculates and returns the nodes-per-second rate.
• recordMove(): Increments the move counter.
• recordOutcome(type): Logs game outcomes (e.g., checkmate, draw).
• reset(): Clears statistics for a new game or session.

Tracked Metrics

The following metrics are collected by stats_t:

• Nodes Searched:
  • Purpose: Measures the search algorithm’s workload.
  • Example: A 4-ply search might evaluate 10,000 nodes per move.
• Search Time:
  • Purpose: Tracks computational effort per move.
  • Example: A move might take 800ms within a 1000ms limit.
• Nodes per Second:
  • Purpose: Indicates search efficiency.
  • Example: 12,500 nodes/second on an Arduino Uno.
• Move Count:
  • Purpose: Tracks game progress.
  • Example: 40 moves in a game.
• Game Outcomes:
  • Purpose: Summarizes results for analysis.
  • Example: 1 checkmate, 2 draws in a session.
• Evaluation Scores:
  • Purpose: Monitors position quality.
  • Example: Scores range from -300 to +200 in a game.

Output

Statistics are output to the Serial Monitor, depending on the verbosity level set in options_t (see Options):

• Minimal Verbosity: No statistics displayed.
• Normal Verbosity: Basic stats (e.g., nodes searched, time taken) after each move.
• Debug Verbosity: Detailed stats (e.g., nodes per second, outcome counts) for debugging.

Example Serial Monitor output (debug mode):