Update README.md

README.md

@@ -8,117 +8,111 @@ tags:
 - ResNet
 ---
 
-# **GChess**
 
-## **Model Description:** 
-GChess model is a powerful deep neural network designed specifically for the game of chess. Its architecture is heavily inspired by the principles of AlphaZero, utilizing a single neural network to simultaneously predict the optimal move and evaluate the position.
+# **GChess: A Deep Residual Network for Chess**
 
-## **Architecture Details:** 
-The core of the network is a Deep Residual Network (ResNet), a structure well-suited for processing the spatial data of an 8x8 chessboard.
+## Model Description
+The **GChess** model is a deep neural network designed for the game of chess, inspired by the **AlphaZero** architecture. It uses a single network to perform both move prediction (Policy) and position evaluation (Value).
 
-## **Torso:** 
-The network employs a robust torso composed of 20 Residual Blocks. Each block contains convolutional layers with skip connections, allowing for the effective learning of deep, hierarchical features and maintaining stable training.
+This release is a **proof-of-concept** version. The model's current estimated playing strength is **~1300 Elo**, placing it at a beginner to intermediate level. It demonstrates a robust foundation for an AlphaZero-style chess AI.
 
-## **Feature Processing:**  
-The entire network processes data using a high number of channels, specifically 512 filters in its main convolutional layers.
-
- * **Input Representation:** The current board state and history are encoded into a multi-plane tensor with 128 input channels, which typically includes information about piece locations, the player to move, castling rights, and repetition history, a common input format for state-of-the-art chess AI.
-
-## **Dual Output Heads:** 
-The shared ResNet torso branches into two specialized heads:
-
- * **Policy Head (p_logits):** Predicts a probability distribution over the 4672 possible moves (actions) that can be taken. This output is crucial for guiding the Monte Carlo Tree Search (MCTS).
-
- * **Value Head (v):** Outputs a single scalar value, typically between -1.0 (Black is winning) and +1.0 (White is winning). This score represents the network's prediction of the final game outcome from the current position.
-
-## **Training:** 
-The model is trained on small dataset from high-quality PGN of games. The model is trained on 50.000 games during 50 hours on RTX4060. This model acctually is evaluate around 1250 Elo. Training uses the PyTorch framework with advanced optimization techniques, including a OneCycleLR learning rate scheduler for accelerated convergence and a large batch size of 1024.
-
-## **Metrics & Training Loss Analysis**
-
-* **Training Loss Curve:**
-![Training Loss](training_loss.png)
-The graph shows a very sharp initial drop followed by a smooth, gradual decline before stabilizing at a low point.
-
-## **Interpretation:** 
-The rapid initial drop signifies highly efficient learning of fundamental chess concepts. The smooth convergence indicates stable training with no major signs of oscillation or instability.
-
-* **Key Metrics:** The deep residual network (20 blocks) optimizes a combined total loss from two primary components:
-
-* **Policy Loss:** Measures the accuracy of the model's move predictions (the most crucial metric for move quality).
-
-* **Value Loss:** Measures how accurately the model evaluates the position (the score, ranging from -1 to 1).
-
-## **Training Efficiency:**
-
-The efficient convergence is largely due to the use of the OneCycleLR learning rate scheduler, which accelerates training by strategically cycling the learning rate up to a high maximum value before annealing it (cooling it down).
-
-
-## **Detailed Loss Convergence:**
-![Detailed Loss convergences](detailed_training_loss.png)
-
-## **Key Observations**
-Rapid Initial Drop: The loss shows an immediate, steep decline, indicating the model quickly learned fundamental concepts and patterns. This is a great sign of an effective learning setup.
+---
 
-* **Wider Fluctuations:** Compared to a smoother curve, this detailed view reveals more short-term oscillations (ups and downs) in the loss, particularly around the 50,000 to 100,000 steps mark.
+## Architecture Details
 
-* **Interpretation:** These fluctuations are common, especially when using an aggressive learning rate schedule like OneCycleLR, as seen in our Training.py. The high learning rate peaks allow the model to escape shallow minimums but also cause the loss to momentarily rise.
+GChess is built on a **Deep Residual Network (ResNet)**, which is highly effective for processing the spatial features of an 8x8 board.
 
-* **Consistent Convergence:** Despite the fluctuations, the overall long-term trend is clearly downward. The loss is consistently driven lower, stabilizing at a much lower point towards the end of the shown steps.
+### **Core Network (Torso)**
+* **Architecture Type:** Deep Residual Network (ResNet).
+* **Residual Blocks:** **20** blocks, ensuring deep, hierarchical feature learning.
+* **Filter Count:** **512** convolutional filters (channels) in its main layers for high feature complexity.
 
-* **Stable Final Phase:** In the later steps, the magnitude of the fluctuations seems to decrease, and the loss settles into a low, stable range, suggesting the model has largely converged.
+### **Input Representation**
+The network accepts a multi-plane tensor encoding the board state and history:
+* **Input Channels:** **128** input channels.
+* **Data Included:** Piece locations, player to move, castling rights, and **8-ply history** to handle repetition and context.
 
-![Accuracy Evaluations](accuracy_evals.png)
+### **Dual Output Heads**
+The shared ResNet torso branches into two specialized output heads:
 
-## **Accuracy Evaluations**
+| Head | Function | Output Format |
+| :--- | :--- | :--- |
+| **Policy Head (p\_logits)** | **Move Prediction** | Logits over **4672** possible moves/actions. |
+| **Value Head (v)** | **Position Evaluation** | Single scalar value in [-1.0, +1.0]. |
 
-The detailed curve confirms a stable and aggressive training process. The fluctuations are expected with our dynamic learning rate strategy but are offset by the continuous decrease in overall loss, indicating successful learning and convergence of our chess network.
+| Value Interpretation | Score |
+| :--- | :--- |
+| **White Winning** | Close to +1.0 |
+| **Black Winning** | Close to -1.0 |
+| **Equal Position** | Close to 0.0 |
 
-## **Key Observations**
+---
 
-* **Positive Progress:** Both Top 1 Accuracy and Top 5 Accuracy show a clear and consistent upward trend across the training steps. This is the most crucial takeaway: the network is successfully learning to predict moves and is not overfitting to the limited data.
+## Training Summary
 
-* **Top 5 Strength:** The Top 5 Accuracy is considerably higher, indicating that the correct expert move is frequently included in the model's top five choices. This is highly promising.
+The model was trained on a small dataset of **50,000 high-quality PGN games** across **25 epochs**.
 
+### **Convergence Analysis**
+The training process was stable and highly efficient, utilizing an aggressive learning rate strategy.
 
-## **Conclusions**
+* **Training Loss Curve:**
+    ![Training Loss](training_loss.png)
+    The loss shows a rapid initial drop, signifying quick learning of fundamental concepts, followed by a smooth convergence.
 
+* **Detailed Loss Convergence:**
+    ![Detailed Loss convergences](detailed_training_loss.png)
+    A detailed view reveals short-term oscillations, which are expected with dynamic learning rate scheduling but confirm a consistently downward trend towards a low, stable loss.
 
-* **Current Performance:** The model has achieved an estimated 1300 Elo rating. While this is not yet grandmaster level, it represents a respectable baseline performance, particularly for a policy network without Monte Carlo Tree Search (MCTS) enhancement.
+* **Accuracy Evaluations:**
+    ![Accuracy Evaluations](accuracy_evals.png)
+    Both Top 1 and Top 5 Accuracy showed clear, consistent upward trends, confirming that the network successfully learned to predict expert moves without overfitting to the limited data. The high Top 5 Accuracy indicates the model reliably generates a strong list of candidate moves.
 
-* **Resource Constraints:** This 1300 Elo was reached using a small dataset of only 50,000 PGN games across 25 training epochs. This resource limitation means the model's knowledge depth is restricted, preventing it from tackling the highest-level strategies.
+---
 
-* **Stable and Efficient Learning:** The loss curves demonstrate stable and aggressive convergence, thanks to the OneCycleLR scheduler. The network effectively maximized the learning potential of the limited data.
+## Conclusion and Future Outlook
 
-* **Strong Predictive Foundation:** The Accuracy Evaluations show consistent improvement. Crucially, the Top 5 Accuracy is high, confirming that the model reliably generates a small list of strong candidate moves.
+* **Current Performance:** The model achieved an estimated **1300 Elo**. While this is an entry-level performance, it's a strong result considering the resource constraints.
+* **Strong Foundation:** The architecture is structurally sound, and the training process demonstrated effective learning.
+* **Future Potential:** The established architecture is well-suited for scaling. With a significantly larger, more diverse dataset (e.g., millions of games) and extended training, this model has the foundation to reach expert and master Elo levels.
 
-* **Future Potential:** The established architecture is highly potent. The current performance is a strong proof of concept. With future iterations involving a larger, more diverse dataset (e.g., millions of games) and a deeper training run, this model has the necessary structural foundation to climb significantly higher into the expert and master Elo ranges.
+---
 
+## Usage
 
-## **Usage:**
+To use the GChess model for inference, you must convert a `chess.Board` object and its history into the required **128-channel input tensor**.
 
 ```python
-
 import chess
 import torch
+import torch.nn.functional as F
+
+# NOTE: The 'model' object must be loaded from a checkpoint, and 
+# 'board_to_tensor' function must be implemented separately 
+# to generate the 128-channel input.
+# DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
 
 # Define Input State (FEN)
-# Example: The initial position of a game
+# Example: Initial position
 fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
 board = chess.Board(fen)
 
-# Preprocess Input
-# This function converts the board object into the 128-channel input tensor expected by the model
-# (Implementation of board_to_tensor is required separately)
-input_tensor = board_to_tensor(board, history_depth=8).unsqueeze(0).to(DEVICE)
+# --- Preprocess Input (Requires custom function) ---
+# input_tensor = board_to_tensor(board, history_depth=8).unsqueeze(0).to(DEVICE)
+# Placeholder tensor for execution:
+input_tensor = torch.randn(1, 128, 8, 8) 
+model = torch.nn.Module() # Placeholder model for execution
+model.eval() # Set model to evaluation mode
 
 # Run Inference
 with torch.no_grad():
     # policy_logits is a tensor of size 4672, value_output is a scalar tensor
-    policy_logits, value_output = model(input_tensor)
+    # policy_logits, value_output = model(input_tensor)
+    
+    # Placeholder outputs for demonstration:
+    policy_logits = torch.randn(1, 4672) 
+    value_output = torch.tensor([[0.25]])
 
 # Post-process Output
-# Convert logits to a probability distribution over all possible moves (actions)
 policy_probabilities = F.softmax(policy_logits, dim=1).squeeze(0)
 
 # Find the move with the highest predicted probability
@@ -131,10 +125,9 @@ expected_value = value_output.item()
 # Print Results
 print(f"FEN: {fen}")
 print(f"--- Model Prediction ---")
-print(f"Move Probability: {best_probability:.4f}")
+print(f"Predicted Probability of Top Move: {best_probability:.4f}")
 print(f"Position Evaluation (Value): {expected_value:.4f}")
-print("\nInterpretation: Value close to +1.0 means White is winning, -1.0 means Black is winning.")
-
+print("Interpretation: Value close to +1.0 means White is winning, -1.0 means Black is winning.")
 ```
 
-Developer: Vanhans, PENEAUX Benjamin
+Devlopper: PENEAUX Benjamin