Skip to content

Commit

Permalink
Deployed 7548c34 with MkDocs version: 1.5.3
Browse files Browse the repository at this point in the history
  • Loading branch information
@programarivm
programarivm committed May 7, 2024
1 parent c4a07f1 commit 3aed8e3
Show file tree
Hide file tree
Showing 9 changed files with 152 additions and 135 deletions.
40 changes: 31 additions & 9 deletions chess-tutor/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,11 @@
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal current" href="./">Chess Tutor</a>
<ul class="current">
<li class="toctree-l2"><a class="reference internal" href="#explain-fen">Explain FEN</a>
<li class="toctree-l2"><a class="reference internal" href="#explain-a-fen-position">Explain a FEN Position</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#explain-pgn">Explain PGN</a>
<li class="toctree-l2"><a class="reference internal" href="#explain-a-pgn-move">Explain a PGN Move</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#explain-a-good-pgn-move">Explain a Good PGN Move</a>
</li>
</ul>
</li>
Expand Down Expand Up @@ -101,9 +103,9 @@
<div class="section" itemprop="articleBody">

<h1 id="chess-tutor">Chess Tutor</h1>
<h2 id="explain-fen">Explain FEN</h2>
<h2 id="explain-a-fen-position">Explain a FEN Position</h2>
<p>✨ Chess beginners often think they can checkmate the opponent's king quickly. However, there are so many different things to consider in order to understand a position.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Tutor/FenEvaluationTest.php">Chess\Tutor\FenEvaluation</a> helps you improve your chess thinking process by evaluating a FEN position in terms of <a href="https://php-chess.docs.chesslablab.org/heuristics/">chess concepts</a>.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Tutor/FenEvaluationTest.php">Chess\Tutor\FenEvaluation</a> helps you improve your chess thinking process by evaluating a FEN position in terms of <a href="https://php-chess.docs.chesslablab.org/heuristics/">chess concepts</a> like in the example below.</p>
<pre><code class="language-php">use Chess\FenToBoardFactory;
use Chess\Tutor\FenEvaluation;

Expand All @@ -115,13 +117,13 @@ <h2 id="explain-fen">Explain FEN</h2>

echo $text;
</code></pre>
<pre><code class="language-text">White has a significant material advantage. White has a significant control of the center. The white pieces are somewhat better connected. The white player is pressuring a little bit more squares than its opponent. White has some absolute pin advantage. White has the bishop pair. The knight on e6 is pinned shielding the king so it cannot move out of the line of attack because the king would be put in check. Overall, 6 heuristic evaluation features are favoring White while 0 are favoring Black.
<pre><code class="language-text">White has a decisive material advantage. White has a slightly better control of the center. The white pieces are significantly better connected. The white player is pressuring a little bit more squares than its opponent. White has a slight absolute pin advantage. White has the bishop pair. The knight on e6 is pinned shielding the king so it cannot move out of the line of attack because the king would be put in check. Overall, 6 heuristic evaluation features are favoring White while 0 are favoring Black.
</code></pre>
<p>A heuristic evaluation is a quick numerical estimate of a chess position that suggests who may be better without considering checkmate. Please note that a heuristic evaluation is not the same thing as a chess calculation. Heuristic evaluations are often correct but may fail as long as they are based on probabilities more than anything else.</p>
<p>🎉 This is a form of abductive reasoning.</p>
<h2 id="explain-pgn">Explain PGN</h2>
<p>✨ Typically, chess engines won't provide an explanation in easy-to-understand language about why a move is good.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Tutor/PgnEvaluationTest.php">Chess\Tutor\PgnEvaluation</a> can explain the implications of making a particular move in terms of <a href="https://php-chess.docs.chesslablab.org/heuristics/">chess concepts</a> and combined with an UCI engine it will explain the why of a good move. Stockfish has been set up with a skill level of <code>20</code> and a depth of <code>15</code> to suggest a good move. In order to use this functionality, make sure to install Stockfish &gt;= 15.1 as it is described in <a href="https://php-chess.docs.chesslablab.org/play-computer/">Play Computer</a>.</p>
<h2 id="explain-a-pgn-move">Explain a PGN Move</h2>
<p>✨ Typically, chess engines won't provide an explanation in easy-to-understand language about how a move changes the position on the board.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Tutor/PgnEvaluationTest.php">Chess\Tutor\PgnEvaluation</a> explains how a particular move changes the position.</p>
<pre><code class="language-php">use Chess\Play\SanPlay;
use Chess\Tutor\PgnEvaluation;

Expand All @@ -135,9 +137,29 @@ <h2 id="explain-pgn">Explain PGN</h2>

echo $text;
</code></pre>
<pre><code class="language-text">Black has some space advantage. White has a small protection advantage. The pawn on c5 is unprotected. Overall, 2 heuristic evaluation features are favoring White while 2 are favoring Black.
<pre><code class="language-text">Black has a slight space advantage. White has a slight protection advantage. The pawn on c5 is unprotected. Overall, 2 heuristic evaluation features are favoring White while 2 are favoring Black.
</code></pre>
<p>The resulting text may sound a little robotic but it can be easily rephrased by the AI of your choice to make it sound more human-like.</p>
<h2 id="explain-a-good-pgn-move">Explain a Good PGN Move</h2>
<p>✨ It's often difficult for beginners to understand why a move is good.</p>
<p>With the help of an UCI engine <a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Tutor/GoodPgnEvaluationTest.php">Chess\Tutor\GoodPgnEvaluation</a> can explain the why of a good move.</p>
<pre><code class="language-php">$movetext = '1.d4 d5 2.c4 Nc6 3.cxd5 Qxd5 4.e3 e5 5.Nc3 Bb4 6.Bd2 Bxc3 7.Bxc3 exd4 8.Ne2';

$limit = (new Limit())-&gt;setDepth(12);
$stockfish = new UciEngine('/usr/games/stockfish');
$board = (new SanPlay($movetext))-&gt;validate()-&gt;getBoard();

$goodPgnEvaluation = new GoodPgnEvaluation($limit, $stockfish, $board);

$pgn = $goodPgnEvaluation-&gt;getPgn();
$paragraph = implode(' ', $goodPgnEvaluation-&gt;getParagraph());

echo $pgn . PHP_EOL;
echo $paragraph . PHP_EOL;
</code></pre>
<pre><code class="language-text">Bg4
The black player is pressuring a little bit more squares than its opponent. The black pieces are timidly approaching the other side's king. Black has a moderate relative pin advantage. The knight on e2 is pinned shielding a piece that is more valuable than the attacking piece. Overall, 4 heuristic evaluation features are favoring White while 9 are favoring Black.
</code></pre>
<p>🎉 Let's do this!</p>

</div>
Expand Down
7 changes: 3 additions & 4 deletions getting-started/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,16 +103,15 @@ <h1 id="getting-started">Getting Started</h1>

$board = new Board();
</code></pre>
<p>Then, you're set up to play classical chess either in PGN or LAN format.</p>
<p>If you have ever attended a chess tournament, you've probably noticed that each player writes down their move in PGN format on a piece of paper. PGN stands for Portable Game Notation and is a human-readable format that allows chess players to read and write chess games. When it comes to computer chess, though, a more appropriate machine-readable format called Long Algebraic Notation (LAN) is often used instead.</p>
<p>Be that as it may, you're already set up to play classical chess either in PGN or LAN format.</p>
<p>In PGN format:</p>
<pre><code class="language-php">$board-&gt;play('w', 'e4');
</code></pre>
<p>In LAN format:</p>
<pre><code class="language-php">$board-&gt;playLan('w', 'e2e4');
</code></pre>
<p>Have you ever attended a chess tournament or watched one streamed on a website? If so, you've probably noticed that each player writes down their move on a piece of paper. PGN stands for Portable Game Notation and is a human-readable format that allows chess players to read and write chess games. Computers and graphical user interfaces (GUI) often prefer an easy-to-use, machine-readable format called Long Algebraic Notation (LAN) instead.</p>
<p>So, for example, if you're integrating a JavaScript chessboard with a backend, you may want to make the chess moves in LAN format. On the other hand, PGN is more suitable for loading games annotated by humans.</p>
<p>Be that as it may, every time a move is made, the state of the board changes.</p>
<p>Every time a move is made, the state of the board changes.</p>
<pre><code class="language-php">var_dump($board-&gt;toFen());
</code></pre>
<pre><code class="language-text">string(55) &quot;rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3&quot;
Expand Down
40 changes: 21 additions & 19 deletions heuristics/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -258,25 +258,26 @@ <h1 id="heuristics">Heuristics</h1>
[6] =&gt; Protection
[7] =&gt; Threat
[8] =&gt; Attack
[9] =&gt; Doubled pawn
[10] =&gt; Passed pawn
[11] =&gt; Advanced pawn
[12] =&gt; Far-advanced pawn
[13] =&gt; Isolated pawn
[14] =&gt; Backward pawn
[15] =&gt; Defense
[16] =&gt; Absolute skewer
[17] =&gt; Absolute pin
[18] =&gt; Relative pin
[19] =&gt; Absolute fork
[20] =&gt; Relative fork
[21] =&gt; Outpost square
[22] =&gt; Knight outpost
[23] =&gt; Bishop outpost
[24] =&gt; Bishop pair
[25] =&gt; Bad bishop
[26] =&gt; Diagonal opposition
[27] =&gt; Direct opposition
[9] =&gt; Discovered check
[10] =&gt; Doubled pawn
[11] =&gt; Passed pawn
[12] =&gt; Advanced pawn
[13] =&gt; Far-advanced pawn
[14] =&gt; Isolated pawn
[15] =&gt; Backward pawn
[16] =&gt; Defense
[17] =&gt; Absolute skewer
[18] =&gt; Absolute pin
[19] =&gt; Relative pin
[20] =&gt; Absolute fork
[21] =&gt; Relative fork
[22] =&gt; Outpost square
[23] =&gt; Knight outpost
[24] =&gt; Bishop outpost
[25] =&gt; Bishop pair
[26] =&gt; Bad bishop
[27] =&gt; Diagonal opposition
[28] =&gt; Direct opposition
)

[balance] =&gt; Array
Expand Down Expand Up @@ -309,6 +310,7 @@ <h1 id="heuristics">Heuristics</h1>
[25] =&gt; 0
[26] =&gt; 0
[27] =&gt; 0
[28] =&gt; 0
)

)
Expand Down
2 changes: 1 addition & 1 deletion index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -257,5 +257,5 @@ <h2 id="lightweight">Lightweight</h2>

<!--
MkDocs version : 1.5.3
Build Date UTC : 2024-05-06 17:53:16.933493+00:00
Build Date UTC : 2024-05-07 17:25:06.568290+00:00
-->
67 changes: 43 additions & 24 deletions play-chess/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,9 @@
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal current" href="./">Play Chess</a>
<ul class="current">
<li class="toctree-l2"><a class="reference internal" href="#play-like-a-pro">Play Like a Pro</a>
<li class="toctree-l2"><a class="reference internal" href="#play-randomly">Play Randomly</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#play-like-a-grandmaster">Play Like a Grandmaster</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#play-computer">Play Computer</a>
</li>
Expand Down Expand Up @@ -101,44 +103,62 @@
<div class="section" itemprop="articleBody">

<h1 id="play-chess">Play Chess</h1>
<h2 id="play-like-a-pro">Play Like a Pro</h2>
<p>✨ The <a href="https://github.com/chesslablab/chess-server/blob/main/data/players.json">players.json</a> file in the <a href="https://github.com/chesslablab/chess-server">Chess Server</a> contains thousands of games by titled FIDE players. This file can be generated and customized with the command line tools available in the <a href="https://github.com/chesslablab/chess-data">Chess Data</a> repo.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/GrandmasterTest.php">Chess\Grandmaster</a> figures out the next move to be made based on the JSON file that is passed to its constructor. Please make sure to first create one for it or feel free to use the players.json linked above.</p>
<pre><code class="language-php">use Chess\Grandmaster;
<h2 id="play-randomly">Play Randomly</h2>
<p>✨ Sometimes you want to play a random game of chess.</p>
<p>You could loop 50 times and play a move by instantiating the <a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Computer/RandomMoveTest.php">Chess\Computer\RandomMove</a> class like in the example below.</p>
<pre><code class="language-php">use Chess\Computer\RandomMove;
use Chess\Variant\Classical\Board;

$board = new Board();

for ($i = 0; $i &lt; 50; $i++) {
if ($move = (new RandomMove($board))-&gt;move()) {
$board-&gt;play($board-&gt;getTurn(), $move-&gt;pgn);
}
}

echo $board-&gt;getMovetext();
</code></pre>
<pre><code class="language-text">1.c4 g6 2.Nf3 Nf6 3.d4 c5 4.Nfd2 Rg8 5.Qa4 Rg7 6.a3 Qc7 7.Kd1 g5 8.h3 Kd8 9.f3 Nc6 10.f4 a6 11.Qxc6 Rg6 12.e3 Bg7 13.Nb3 h6 14.a4 e6 15.g3 Ne4 16.Ke2 g4 17.N3d2 e5 18.Qe6 Bf6 19.Kd1 h5 20.Na3 Bh8 21.dxe5 a5 22.b4 Nxg3 23.Nf3 Qd6+ 24.exd6 Rb8
</code></pre>
<p>The result obtained is a 24 move game since a move is considered to be completed after both players have played a turn.</p>
<h2 id="play-like-a-grandmaster">Play Like a Grandmaster</h2>
<p>✨ The <a href="https://github.com/chesslablab/chess-server/blob/main/data/players.json">players.json</a> file in the <a href="https://github.com/chesslablab/chess-server">Chess Server</a> contains thousands of games by titled FIDE players. This file can be generated with the command line tools available in the <a href="https://github.com/chesslablab/chess-data">Chess Data</a> repo.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/src/Computer/GrandmasterMove.php">Chess\Computer\GrandmasterMove</a> figures out the next move to be made based on the players.json file that is passed to its constructor.</p>
<pre><code class="language-php">use Chess\Computer\GrandmasterMove;
use Chess\Variant\Classical\Board;

$board = new Board();
$board-&gt;play('w', 'e4');

$move = (new Grandmaster(__DIR__.'/../data/players.json'))-&gt;move($board);
$gmMove = (new GrandmasterMove(__DIR__.'/../data/players.json'))-&gt;move($board);

print_r($move);
print_r($gmMove);
</code></pre>
<pre><code class="language-text">stdClass Object
(
[move] =&gt; e5
[pgn] =&gt; c5
[game] =&gt; Array
(
[Event] =&gt; Barmen-B
[Site] =&gt; Barmen
[Date] =&gt; 1905.??.??
[White] =&gt; Neumann, Augustin
[Black] =&gt; Spielmann, Rudolf
[Result] =&gt; 1/2-1/2
[ECO] =&gt; C63
[movetext] =&gt; 1.e4 e5 2.Nf3 Nc6 3.Bb5 f5 4.exf5 e4 5.Qe2 Qe7 6.Bxc6 bxc6 7.Nd4 Nf6 8.O-O c5 9.Nb5 d5 10.f3 c6 11.N5c3 Bxf5 12.fxe4 Bxe4 13.Nxe4 Qxe4 14.Qa6 Qe6 15.d3 Be7 16.Bf4 O-O 17.Nd2 Nh5 18.Rae1 Qg4 19.h3 Qg6 20.Be5 Bh4 21.Rxf8+ Rxf8 22.Rf1 Rxf1+ 23.Kxf1 Qe6 24.Nf3 Bg3 25.Bxg3 Nxg3+ 26.Kf2 Nf5 27.Kg1 h6 28.Qxa7 Qe3+ 29.Kh2 Qf4+ 30.Kg1 Qe3+ 31.Kh2 Qf2 32.Qd7 Ne3 33.Qe8+ Kh7
[Event] =&gt; Tilburg
[Site] =&gt; Tilburg
[Date] =&gt; 1993.??.??
[White] =&gt; Morozevich, Alexander
[Black] =&gt; Adams, Michael
[Result] =&gt; 1-0
[ECO] =&gt; B23
[movetext] =&gt; 1.e4 c5 2.Nc3 Nc6 3.f4 g6 4.Nf3 Bg7 5.Bb5 Nd4 6.Nxd4 cxd4 7.Ne2 a6 8.Ba4 b5 9.Bb3 e6 10.O-O Ne7 11.d3 O-O 12.Qe1 f5 13.Bd2 Nc6 14.Kh1 Bb7 15.Ng1 h6 16.Nf3 Kh7 17.Qg3 Qe7 18.Rae1 a5 19.a3 Rab8 20.Nh4 Qf7 21.Qh3 Ba8 22.Rf3 a4 23.Ba2 b4 24.Bc1 b3 25.cxb3 axb3 26.Bb1 d6 27.Bd2 Kg8 28.g4 Ne7 29.gxf5 gxf5 30.Rg3 Kh7 31.Nf3 Bf6 32.Ng5+ Bxg5 33.fxg5 Ng6 34.Qxh6+ Kg8 35.h4 f4 36.Rh3 Rb7 37.h5 Ne5 38.Rg1 Rc7 39.Rh4 Qe8 40.g6
)

)
</code></pre>
<p>1.e4 e5 is the move that a grandmaster would play. As you can see in this example, Chess\Grandmaster could find a response to 1.e4 returning the corresponding game's metadata.</p>
<p>🎉 Let's now put our knowledge of chess openings to the test.</p>
<h2 id="play-computer">Play Computer</h2>
<p>✨ UCI engines not only allow to play chess with the computer but are also a helpful tool when analyzing chess games.</p>
<p><a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/UciEngine/UciEngineTest.php">Chess\UciEngine\UciEngine</a> allows to play chess against the Stockfish chess engine using PHP, but first things first, make sure to install Stockfish on your computer.</p>
<p>✨ The Universal Chess Interface (UCI) is an open communication protocol that enables chess engines to communicate with user interfaces.</p>
<p>PHP Chess provides the <a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/UciEngine/UciEngineTest.php">Chess\UciEngine\UciEngine</a> class representing an UCI engine. To follow this tutorial make sure to install Stockfish if you haven't already.</p>
<pre><code class="language-text">sudo apt-get install stockfish
</code></pre>
<p>Then, you're set up to play chess against Stockfish as described in the following example.</p>
<p>Then, you are set up to play chess against the computer as described in the following example.</p>
<pre><code class="language-php">use Chess\UciEngine\UciEngine;
use Chess\UciEngine\Details\Limit;
use Chess\Variant\Classical\Board;
Expand All @@ -156,7 +176,7 @@ <h2 id="play-computer">Play Computer</h2>
</code></pre>
<pre><code class="language-text">1.e4 Nf6
</code></pre>
<p>PHP Chess classes can be combined to do different things. For example, you may want to play against Stockfish from this FEN position published in your favorite online publication.</p>
<p>You may want to play against Stockfish starting from a particular FEN with the help of <a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/FenToBoardFactoryTest.php">Chess\FenToBoardFactory</a>.</p>
<pre><code class="language-php">use Chess\FenToBoardFactory;
use Chess\UciEngine\UciEngine;
use Chess\UciEngine\Details\Limit;
Expand All @@ -173,8 +193,8 @@ <h2 id="play-computer">Play Computer</h2>
</code></pre>
<pre><code class="language-text">1.Rb1
</code></pre>
<p>The FEN is converted to a chessboard object as described in <a href="https://php-chess.docs.chesslablab.org/convert-fen-to-board/">Convert FEN to Board</a>. The <code>Skill Level</code> is set to <code>20</code> and the depth is set to <code>12</code> in order to get a more accurate response from Stockfish.</p>
<p>The same thing goes for PGN annotated games. This is how to play against Stockfish after loading a SAN movetext into a chess board object.</p>
<p>The FEN is converted to a chess board object as described in the <a href="https://php-chess.docs.chesslablab.org/data-conversion/#fen-to-board">Data Conversion</a> section. Then Stockfish's depth limit is set to <code>12</code> and the skill level to <code>20</code>.</p>
<p>The same thing goes to starting a game from a particular SAN movetext. As you can see in the example below, <a href="https://github.com/chesslablab/php-chess/blob/main/tests/unit/Play/SanPlayTest.php">Chess\Play\SanPlay</a> is used for this purpose.</p>
<pre><code class="language-php">use Chess\Play\SanPlay;
use Chess\UciEngine\UciEngine;
use Chess\UciEngine\Details\Limit;
Expand All @@ -195,7 +215,6 @@ <h2 id="play-computer">Play Computer</h2>
</code></pre>
<pre><code class="language-text">1.d4 Nf6 2.c4 c5 3.d5 e6 4.Nc3 exd5 5.cxd5 d6 6.e4 g6 7.Nf3 Bg7 8.h3
</code></pre>
<p>As you can see, Stockfish responds with 8.h3.</p>
<p>🎉 Can you beat the computer? Keep it up!</p>

</div>
Expand Down
Loading

0 comments on commit 3aed8e3

Please sign in to comment.