Update documentation

README.md

@@ -1,22 +1,25 @@
 IA: jeu de Reversi
 ------------------
 
-Le but de ce projet est d'implémenter plusieurs mécanisme de jeu (humain et 
+Le but de ce projet est d'implémenter plusieurs mécanismes de jeu (humain et 
-intelligence artificielle) pour le jeu de Reversi
+intelligence artificielle) pour le Reversi. 
 
 ## Installation
 
-Le programme utilise des outils standard de Python installé de base : `random`,
+Le programme utilise des outils standard de Python installés de base : `random`,
-`math`, `argpase` et `logging`. Le project est fourni avec un shell *Nix* dans
+`math`, `argpase` et `logging`. Le projet est fourni avec un shell *Nix* dans
-le répertoire `src`
+le répertoire `src`.
 
 ## Utilisation
 
-le programme propose un emsemble d'options en ligne de commande afin de définir
+J'ai choisi de créer un programme en *Python* utilisable depuis un terminal
-les options du jeu comme le choix des implementations de jeu (aléatoine, MinMax
+(testé uniquement sous Linux).
-etc.) ou encore les paramètres (profondeur de recherche). Une aide est intégrée
+
-au programme via la commande `./game.py -h`. Voici quelques exemple de
+Le programme propose un ensemble d'options afin de définir les paramètres des
-lancement:
+différentes implémentations présentes dans le jeu comme le choix des moteurs de
+jeu (aléatoire, MinMax etc.), les paramètres (profondeur de recherche,
+temps imparti) etc. Une aide est intégrée au programme via la commande `./game.py
+-h`. Voici quelques exemple de lancement:
 
 ```shell
 # Lancement de base: les deux joueurs jouent avec le moteur aléatoire et les
@@ -24,38 +27,50 @@ options de base:
 ./game.py
 
 # joueur noir humain et joueur blanc MinMax avec une profondeur de 5
-./game.py -be human -we minmax --white-depth-exploration 5
+./game.py -be human -we minmax -wd 5
 ```
-Voici la liste des options :
+
+Voyons maintenant quelques paramètres.
 
 ### Moteur de jeu
 
-Il est possible de définir le moteur de jeu indépedamment pour chaque joueur et
+Il est possible de définir le moteur de jeu indépendamment pour chaque joueur et
-ainsi faire des match:
+ainsi faire des matches:
 
  * `-be` | `--black-player-engine`: moteur utilisé par le joueur avec les pions
    noirs
  * `-we` | `--white-player-engine`: moteur utilisé par le joueur avec les pions
    blancs
 
-Le moteur de jeux par défaut est random.
+Le moteur de jeux par défaut est `random`.
 
 ### Profondeur d'exploration
 
- Il est aussi possible de définir la profindeur d'exploration de l'arbre de jeu
+ Il est aussi possible de définir la profondeur d'exploration de l'arbre de jeu
  pour chacun des joueurs:
 
- * `-bd` | `--black-depth-exploration`: niveau d'eploration de l'arbre de jeu
+ * `-bd` | `--black-depth-exploration`: niveau d'exploration de l'arbre de jeu
    pour le joueur au pions noirs, valable pour les moteurs `minmax` et
    `alphabeta`. Utilisé aussi pour définit la profondeur de départ pour
    l'*iterative deepening*
- * `-wd` | `--white-depth-exploration`: niveau d'eploration de l'arbre de jeu
+ * `-wd` | `--white-depth-exploration`: niveau d'exploration de l'arbre de jeu
-   pour le joueur au pions noirs, valable pour les moteurs `minmax` et
+   pour le joueur au pions blancs, valable pour les moteurs `minmax` et
    `alphabeta`Utilisé aussi pour définit la profondeur de départ pour
    l'*iterative deepening*
  
 La profondeur par défaut est 3.
 
+### Temps d'exploration pour l'*Iterative Deepening*
+
+Lorsque le choix est fait d'utiliser les algorithmes utilisant l'*iterative
+deepening. Il est possible de régler les temps d'exploration indépendamment pour 
+les deux joueurs:
+
+ * `-bt` | `--black-player-deepening-time`: temps maximum en seconde
+   d'exploration de l'arbre pour le joueur noir
+ * `-wt` | `--white-player-deepening-time`: temps maximum en seconde
+   d'exploration de l'arbre pour le joueur blanc
+
 ### Heuristique
  
 Il est possible de choisir entre les 3 moteur de calcul d'heuristique inclus à
@@ -75,14 +90,19 @@ Pour l'utilisation des poids, il est possible de les paramétrer :
  * `--weight`: scores utilisés pour le calcul des heuristiques pour les moteurs
    `weight` et `full`.
 
-L'affichage verbeux est activé avec `-V` et les informations de débogage sont 
+### Debug et mode verbeux
+
+L'affichage verbeux est activé avec `-V` et les informations de débogages sont 
 affichée avec l'option `-d`.
 
 ## Choix d'implémentation
 
-J'ai avant tout privilégié la personnalisation des différentes paramètres des
+J'ai avant tout privilégié la personnalisation des  paramètres des
-différents moteurs composant le jeu. Il,e st ainsi plus aisé de tester le
+différents moteurs composant le jeu. Il est ainsi plus aisé de tester le
-fonctionnement des différents moteurs.
+fonctionnement suivants différents scénarios.
+
+Tout est implémenté suivant une logique objet facilitant le développement des
+composants et leurs tests.
 
 ### Classes PlayerEngine
 
@@ -107,30 +127,31 @@ class AlphabetaPlayerEngine(PlayerEngine):
 
 Quatre moteur "joueurs" sont implémentés :
 
- * `Human` pour gérer des joueurs humain, une saisir utilisateur est demandée
+ * `Human` pour gérer des joueurs humain, une saisie utilisateur est demandée
    sous la forme `<pos_x><pos_y>`. Il est aussi possible d'afficher le plateau
    avec la commande `print` ou les coups possibles avec `help`;
- * `Ramdom` va choisir aléatoirement le coup à jouer en fonction des coups;
+ * `Ramdom` va choisir aléatoirement le coup à jouer en fonction de ceux
    possibles;
  * `Minmax` utilise *MinMax* pour déterminer le coup à jouer avec une profondeur
    maximale définie;
  * `AphaBeta` utilise *AlphaBeta* pour déterminer le coup à jouer avec une
    profondeur maximale définie;
- * `MinmaxDeepeningMinmax` utilise Minmax avec un temps maximum autorisé;
+ * `MinmaxDeepeningMinmax` utilise Minmax avec un temps maximum autorisé en
- * `AlphaBetaDeepening` utilise AlphaBeta avec un temps maximum autorisé
+   itérant sur la profondeur;
+ * `AlphaBetaDeepening` utilise AlphaBeta avec un temps maximum autorisé.
 
 Le choix de ces moteur se fait en ligne de commande avec les options évoquées
 plus haut. 
 
 ### Classes HeuristicsEngine
 
-Plusieurs classes impémentent plusieurs méthodes pour le calcul de
+Plusieurs classes implémentent plusieurs méthodes pour le calcul de
 l'heuristique. Toutes les implémentations se trouvent dans le fichier
 `./src/classes/Heuristic.py` Comme nous l'avons vu, les moteurs peuvent être
 choisis en ligne de commande et de façon indépendante pour les joueurs blanc et
 noir.
 
-Trois implementation sond disponibles:
+Trois implementations sont disponibles:
 
  1. `ScoreHeuristicEngine`: l'heuristique se sert du score (comptage des pièces
     sur le tableau) via la méthode `Board.heuristique`;
@@ -155,17 +176,19 @@ Cependant certaines parties du plateau de jeu sont à éviter :
    adverse de placer un de ses pions dans le coin. La case en diagonale du coin
    est particulièrement sensible.
  * Les lignes juste avant les bords, placer un pion à cet endroit permettrai à
-   l'adversaire de placer un pion sur le bord. Ce ion sera alors p[lus
+   l'adversaire de placer un pion sur le bord. Ce pion sera alors plus
    difficilement *"capturable"*
 
 Les poids affectés sont personnalisable via l'options `--weight`, par défaut
-nous avons -5, 2, 10 et 25.
+nous avons `[-5, 2, 10, 25]`. Ces quatre chiffres servent de base pour le
+calcul de l'ensemble des poids
 
 Une étude autour de l'heuristique de l'Othello menée par Vaishnavi Sannidhanam 
-et Muthukaruppan Annamalai de l'université de Washingtown propose d'autre piste
+et Muthukaruppan Annamalai de l'université de Washingtown propose d'autre pistes
-pour maéliorer l'heuristique. [télécharger le pdf][etude]
+pour améliorer son calcul. [télécharger le pdf][etude]. Mon calcul des poinds
+s'en inspire grandement.
 
-Voici le tableau des poinds par défaut, il peut être affiché avec l'option
+Voici le tableau des poids par défaut, il peut être affiché avec l'option
 `--show-weights-table`:
 
 ```text
@@ -186,11 +209,39 @@ Starting PyReverso...
  9 |25 |-5 |10 | 8 | 8 | 8 | 8 |10 |-5 |25 |
 ```
 
-
-
 ### À savoir:
 
-Les pois utilisé pour les heuristiques sont important.
+Les poids utilisé pour les heuristiques sont importants, ils ont été trouvés en
+effectuant plusieurs tests mais peuvent être améliorés de mon point.
+
+## mode récursions
+
+Le programme principal inclus un mode *recursion* permettant l'exécutions de
+plusieurs parties les unes à la suite des autres afin de tester les paramètres. Le
+paramètre pour la ligne de commande est `-r` | `--recursions` suivi d'un nombre
+entier positif.
+
+À la fin de la passe, un récapitulatif est affiché montrant statistiques,
+moteurs utilisés et leurs options:
+
+```text
+Stats
+---
+Parties: 10
+Black:  8 | ratio:   80.0 | engine: MinmaxDeepeningPlayerEngine
+White:  2 | ratio:   20.0 | engine: AlphaBetaDeepeningPlayerEngine
+Null:   0 | ratio:    0.0
+```
+## Pour conclure
+
+Pour mon implémentation, le moteur **MinMax** avec l'**Iterative Deepening** se
+montre plus performant. La logique voudrait que se soit le moteur *AlphaBeta*
+avec *Iterative Deepening* le plus performant car il explore l'arbre de jeu
+plus en profondeur. C'est d'ailleurs ce qui apparait dans les données affichées
+en mode debug (option `-d`).
+
+Il est donc fort à parier que mon heuristique ne soit pas encore au point. Mais
+le temps a manqué pour améliorer ce point. 
 
 [reversi]:https://www.coolmathgames.com/blog/how-to-play-reversi-basics-and-best-strategies
 [etude]:https://courses.cs.washington.edu/courses/cse573/04au/Project/mini1/RUSSIA/Final_Paper.pdf