Merge pull request #4 from fathzer-games/branch-release-0.0.1

0.0.1 release

Author: fathzer

.project

@@ -20,4 +20,15 @@
 		<nature>org.eclipse.jdt.core.javanature</nature>
 		<nature>org.eclipse.m2e.core.maven2Nature</nature>
 	</natures>
+	<filteredResources>
+		<filter>
+			<id>1739988148319</id>
+			<name></name>
+			<type>30</type>
+			<matcher>
+				<id>org.eclipse.core.resources.regexFilterMatcher</id>
+				<arguments>node_modules|\.git|__CREATED_BY_JAVA_LANGUAGE_SERVER__</arguments>
+			</matcher>
+		</filter>
+	</filteredResources>
 </projectDescription>

README.md

@@ -11,19 +11,24 @@ It provides you with a ready to use and highly configurable [iterative deepening
 In order to have a working engine for your favorite game, you have to implement your own MoveGenerator and Evaluator for this game ... and use one of the provided ai (I recommend IterativeDeepeningEngine).  
 You can implement your own transposition table and its policy (which positions to save or how to reuse them during the search). This library contains a basic implementation, try it to see if it is enough for your needs.
 
-# Known bugs
-- The AI always supposes a player that can't move loosed or make a draw ... which is not always the case (typically in [Reversi](https://en.wikipedia.org/wiki/Reversi)).
-- The iterative deepening search always stops deepening when it finds a winning move. It prevents finding other deeper winning moves. It's not a problem when playing a game, but for analysis, it is one.
+It also provides you with other useful building blocks like a clock, PerfT tests (for testing your move generator), or abstract implementations of move library (typically openings book for chess).
 
-## TODO
-- Filter the library moves with candidates moves in IterativeDeepengingEngine.
-- The transposition table *newPosition* method should have the board as an argument in order to, for instance, compute a generation number based on board characteristics.
+# Known limitations
+- The AI always supposes that when a player can't move the game is ended ... which is not always the case (typically in [Reversi](https://en.wikipedia.org/wiki/Reversi)).  
+This doesn't means that the AI can't be used to play Reversi. Simply, the reversi move generator should have a special '*can't play*' move returned when a player can't move but the game is not finished.
+- The Negamax is quite basic, it implements a highly configurable transposition and quiesce move search, but none other advanced algorithm (no PV search, futility pruning, killer or null move, etc ...).
+
+## TODO (probable breaking changes)
+- com.fathzer.games.ai.AbstractAI requires an ExecutionContext in its constructor. I think this is not a good approach (even it was mine ;-)) to have this non standard implementation detail exposed outside this public class. Moreover, this disallow building different multi-threading models in AI implementation. Typically it is currently impossible to use a fork/join pool to perform the search.
+As it seems, in real life, a new context is created at each AI invocation, a better approach would be to let the AI manage its own threading scheme, and simply pass a SearchContext to the constructor.
+- Some methods in `com.fathzer.games.ai/iterativedeepening` implicitly suppose that the move generator implement `HashProvider`. This may be changed for an explicit requirement.
+
+
+## TODO (maybe)
+- Make MoveLibrary implement AI?
 - There's probably a bug or something very misleading in ClockSettings: withNext has a number of plies arguments, but it seems that the usage is to deal with number of moves (not plies which are half moves).
 - Maybe TTAi scoreToTT and ttToScore would be at a better place in TranspositionTablePolicy. Another, maybe better, approach is to compute fixed (mat) values in Negamax class and have a flag in the table (and in its store method) to explicitly set the stored value as a fixed value. It would allow those values to be used regardless of the depth at which they are recorded.
-- EvaluatedMove.compareTo does not sort in natural order which can be confusing
 - There's a strange behavior with transposition table. There's some situations where a never replace strategy leads to a faster resolution. It is totally counter intuitive.
 - MoveGenerator:
   - It would be more efficient to have the moveGenerator generating directly an iterator of moves instead of a list of moves. It would allow to use incremental move generators that starts by returning, what can hope to be the best moves (for instance captures), and other moves if these first moves are consumed. Indeed, in alpha/beta ai, the first moves are often enough to trigger a cut, so generating all the moves is a waste of time.
-- Write tests and Documentation ;-)
-- Test with Sonar
-- Publish artifact on Maven central
+- Write more tests ;-)

pom.xml

@@ -9,7 +9,7 @@
 		<version>1.0.8</version>
 	</parent>
 	<artifactId>games-core</artifactId>
-	<version>0.0.12-SNAPSHOT</version>
+	<version>0.0.1</version>
 
 	<name>games-core</name>
 	<description>A core library to help implement two players games.</description>
@@ -41,16 +41,22 @@
 			<version>5.10.2</version>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>com.fathzer</groupId>
+			<artifactId>jchess-perft-dataset</artifactId>
+			<version>2.0.0</version>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.mockito</groupId>
 			<artifactId>mockito-junit-jupiter</artifactId>
-			<version>5.1.1</version>
+			<version>5.16.0</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
 			<groupId>com.github.bhlangonijr</groupId>
 			<artifactId>chesslib</artifactId>
-			<version>1.3.3</version>
+			<version>1.3.4</version>
 			<scope>test</scope>
 		</dependency>
 		<dependency>
@@ -60,4 +66,43 @@
 			<scope>test</scope>
 		</dependency>
 	</dependencies>
+	
+	<build>
+		<plugins>
+			<plugin>
+			    <groupId>org.jacoco</groupId>
+			    <artifactId>jacoco-maven-plugin</artifactId>
+			    <version>0.8.12</version>
+			    <configuration>
+			        <excludes>
+			            <!-- Exclude the PhysicalCores class from code coverage because it is too tiedly coupled with the runtime environment -->
+			            <exclude>**/PhysicalCores.class</exclude>
+			            <exclude>**/experimental/*</exclude>
+			        </excludes>
+			     </configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-javadoc-plugin</artifactId>
+				<version>3.6.3</version>
+				<configuration>
+					<source>8</source>
+					<docencoding>UTF-8</docencoding>
+					<overview>${basedir}/overview.html</overview>
+					<header>${project.version}</header>
+					<bottom>${project.version}</bottom>
+					<excludePackageNames>:*.experimental</excludePackageNames>
+				</configuration>
+				<executions>
+					<execution>
+						<id>javadoc_generation</id>
+						<phase>package</phase>
+						<goals>
+							<goal>jar</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+		</plugins>
+	</build>
 </project>

src/main/java/com/fathzer/games/Color.java

@@ -6,7 +6,10 @@
  * <br>Ok, ok, so let say "white" means "X" and "black" means "O". The important thing is to identify both players, isn't it?.
  */
 public enum Color {
-	WHITE, BLACK;
+	/** White player */
+	WHITE, 
+	/** Black player */
+	BLACK;
 
 	static {
 		WHITE.opposite = BLACK;

src/main/java/com/fathzer/games/GameHistory.java

@@ -37,6 +37,9 @@ public enum TerminationCause {
 	private Status extraStatus;
 	private TerminationCause terminationCause;
 
+	/** Creates a new game history.
+	 * @param board The board of the game at its start
+	 */
 	@SuppressWarnings("unchecked")
 	public GameHistory(B board) {
 		this.startBoard = (B) board.fork();
@@ -66,14 +69,24 @@ public boolean add(M move) {
 		return result;
 	}
 
+	/** Gets the start board.
+	 * @return a board instance.
+	 */
 	public B getStartBoard() {
 		return startBoard;
 	}
 
+	/** Gets the current board.
+	 * @return board instance.
+	 */
 	public B getBoard() {
 		return board;
 	}
 
+	/** Gets the list of moves added to this history using the {@link #add(Move)} method.
+	 * @return a list of moves
+	 * @see #add(Move)
+	 */
 	public List<M> getMoves() {
 		return moves;
 	}
@@ -97,17 +110,30 @@ public void earlyEnd(Status status, TerminationCause terminationCause) {
 		this.terminationCause = terminationCause;
 	}
 
+	/** Gets the current game status.
+	 * @return A status. The one set with the {@link #earlyEnd(Status, TerminationCause)} method or the one returned by the {@link #getBoardStatus(B)} method. 
+	 */
 	public Status getStatus() {
 		if (extraStatus!=null) {
 			return extraStatus;
 		}
 		return getBoardStatus(board);
 	}
 
+	/** Gets the current termination cause.
+	 * @return a non null termination cause
+	 * @see #earlyEnd(Status, TerminationCause)
+	 */
 	public TerminationCause getTerminationCause() {
 		return this.terminationCause;
 	}
 
+	/** Gets the current game status, excluding status set by {@link #earlyEnd(Status, TerminationCause)} method.
+	 * <br>The default implementation returns the status returned by {@link MoveGenerator#getContextualStatus()} if it is not <code>PLAYING</code>.
+	 * If its is <code>PLAYING</code> but there are no legal moves, then the result of {@link MoveGenerator#getEndGameStatus()} is returned.
+	 * @param board The board.
+	 * @return A status.
+	 */
 	protected Status getBoardStatus(B board) {
 		Status status = board.getContextualStatus();
 		if (status==Status.PLAYING && board.getLegalMoves().isEmpty()) {

src/main/java/com/fathzer/games/MoveGenerator.java

@@ -1,7 +1,6 @@
 package com.fathzer.games;
 
 import java.util.List;
-import java.util.stream.Collectors;
 
 import com.fathzer.games.util.exec.Forkable;
 
@@ -70,7 +69,7 @@ default List<M> getLegalMoves() {
 				unmakeMove();
 			}
 			return ok;
-		}).collect(Collectors.toList());
+		}).toList();
 	}
 
 	/** This method is called before evaluating a position or looking for a previous evaluation in a transposition table.

src/main/java/com/fathzer/games/Status.java

@@ -3,7 +3,14 @@
 /** The status of a game (playing, draw, white or black won).
  */
 public enum Status {
-	PLAYING, DRAW, WHITE_WON, BLACK_WON;
+	/** The game is still playing */
+	PLAYING, 
+	/** The game ends with a draw */
+	DRAW, 
+	/** The white player has won */
+	WHITE_WON, 
+	/** The black player has won */
+	BLACK_WON;
 
 	/** Gets the winner's color.
 	 * @return A color or null if there's no winner

src/main/java/com/fathzer/games/ai/AI.java

@@ -4,33 +4,25 @@
 
 /** An AI able to find the best move(s) during a game.
  * @param <M> Implementation of the Move interface to use
+ * @param <P> Implementation of the SearchParameters interface to use
  */
-public interface AI<M> {
+public interface AI<M, P extends SearchParameters> {
 
     /**
-     * Gets best moves evaluations at the given search depth
+     * Gets best moves evaluations with the given search parameters
      * <br>This method works on all possible moves for the position. If you want to work on reduced move set, you can use {@link #getBestMoves(List, SearchParameters)} methods
      * @param parameters The search parameters
      * @return The search result
      */
-    SearchResult<M> getBestMoves(SearchParameters parameters);
+    SearchResult<M> getBestMoves(P parameters);
 
     /**
-     * Gets best moves evaluations at the given search depth
+     * Gets best moves evaluations at the given search parameters
      * <br>This methods evaluates provided moves in the list order. In order to maximize cutoff in some algorithm (like {@link Negamax}),
      * you should order the list in from what is estimated to be the best move to the worst one.
      * @param possibleMoves A list of moves to evaluate. If one of these moves is impossible, result is not specified (It may crash or return a wrong result, etc...).
      * @param parameters The search parameters
      * @return The search result. 
      */
-    SearchResult<M> getBestMoves(List<M> possibleMoves, SearchParameters parameters);
-    
-	public void interrupt();
-
-	public boolean isInterrupted();
-
-	/** Gets the statistic related to last search call.
-	 * @return The statistics
-	 */
-	SearchStatistics getStatistics();
+    SearchResult<M> getBestMoves(List<M> possibleMoves, P parameters);
 }

src/main/java/com/fathzer/games/ai/AbstractAI.java

@@ -8,11 +8,19 @@
 import com.fathzer.games.Status;
 import com.fathzer.games.ai.evaluation.Evaluator;
 import com.fathzer.games.util.exec.ExecutionContext;
+import com.fathzer.games.util.exec.Interruptible;
 
-public abstract class AbstractAI<M, B extends MoveGenerator<M>> implements AI<M> {
+/** An abstract {@link DepthFirstAI} implementation.
+ * @param <M> Implementation of the Move interface to use
+ * @param <B> Implementation of the MoveGenerator interface to use
+ */
+public abstract class AbstractAI<M, B extends MoveGenerator<M>> implements DepthFirstAI<M, DepthFirstSearchParameters>, Interruptible {
 	private final ExecutionContext<SearchContext<M,B>> context;
 	private boolean interrupted;
 
+	/** Constructor
+	 * @param context The context to use for the search
+	 */
 	protected AbstractAI(ExecutionContext<SearchContext<M,B>> context) {
 		this.context = context;
 		this.interrupted = false;
@@ -23,23 +31,34 @@ public SearchStatistics getStatistics() {
 		return context.getContext().getStatistics();
 	}
 
+	/**
+	 * Gets the context used for the search.
+	 * @return the context
+	 */
 	public SearchContext<M, B> getContext() {
 		return context.getContext();
 	}
 
 	@Override
-    public SearchResult<M> getBestMoves(SearchParameters params) {
+    public SearchResult<M> getBestMoves(DepthFirstSearchParameters params) {
 		getContext().getStatistics().clear();
 		List<M> moves = getContext().getGamePosition().getMoves();
 		getStatistics().movesGenerated(moves.size());
 		return this.getBestMoves(moves, params);
     }
 
 	@Override
-    public SearchResult<M> getBestMoves(List<M> moves, SearchParameters params) {
-		return getBestMoves(moves, params, (m,lowestInterestingScore)->rootEvaluation(m,params.getDepth(),lowestInterestingScore));
+    public SearchResult<M> getBestMoves(List<M> moves, DepthFirstSearchParameters params) {
+		return getBestMoves(moves, params, (m,lowestInterestingScore)->rootEvaluation(m,params.getDepth(), lowestInterestingScore));
     }
 
+	/**
+	 * Evaluates a root move of the search tree.
+	 * @param move The move to evaluate
+	 * @param depth The depth of the search
+	 * @param lowestInterestingScore The lowest interesting score under which the evaluation is not interesting (typically this can be used to cut the tree when this evaluation can't be reached)
+	 * @return The score of the move (the score is computed by the {@link #getRootScore(int, int)} method), or null if the move is not valid
+	 */
 	protected Integer rootEvaluation(M move, final int depth, int lowestInterestingScore) {
     	if (lowestInterestingScore==Integer.MIN_VALUE) {
     		// WARNING: -Integer.MIN_VALUE is equals to ... Integer.MIN_VALUE
@@ -56,15 +75,29 @@ protected Integer rootEvaluation(M move, final int depth, int lowestInterestingS
         }
 	}
 
+	/** 
+	 * Gets the score of a root move.
+	 * @param depth The depth of the search
+	 * @param lowestInterestingScore The lowest interesting score under which the evaluation is not interesting (typically this can be used to cut the tree when this evaluation can't be reached)
+	 * @return The score of the move
+	 */
 	protected abstract int getRootScore(final int depth, int lowestInterestingScore);
 
-	protected SearchResult<M> getBestMoves(List<M> moves, SearchParameters params, BiFunction<M,Integer, Integer> rootEvaluator) {
-        final SearchResult<M> search = new SearchResult<>(params.getSize(), params.getAccuracy());
-		context.execute(moves.stream().map(m -> getRootEvaluationTask(params, rootEvaluator, search, m)).toList());
+	/**
+	 * Performs a search on a list of moves.
+	 * <br>It is called by the {@link #getBestMoves(List, DepthFirstSearchParameters)} method and uses the execution context to process the moves (see {@link ExecutionContext#execute(Collection)}).
+	 * @param moves The moves to evaluate
+	 * @param params The parameters of the search
+	 * @param rootEvaluator A function that evaluates the root moves
+	 * @return The search result
+	 */
+	protected SearchResult<M> getBestMoves(List<M> moves, DepthFirstSearchParameters params, BiFunction<M,Integer, Integer> rootEvaluator) {
+        final SearchResult<M> search = new SearchResult<>(params);
+		context.execute(moves.stream().map(m -> getRootEvaluationTask(rootEvaluator, search, m)).toList());
         return search;
     }
 
-	private Runnable getRootEvaluationTask(SearchParameters params, BiFunction<M, Integer, Integer> rootEvaluator, final SearchResult<M> search, M m) {
+	private Runnable getRootEvaluationTask(BiFunction<M, Integer, Integer> rootEvaluator, final SearchResult<M> search, M m) {
 		return () -> {
 				final Integer score = rootEvaluator.apply(m, search.getLow());
 				if (!isInterrupted() && score!=null) {
@@ -84,11 +117,18 @@ public void interrupt() {
 		interrupted = true;
 	}
 
+	/**
+	 * Gets the score when the game ended during the search (for instance, for chess, when the last move played during the search is a mate).
+	 * @param evaluator The evaluator used (returned by {@link SearchContext#getEvaluator()})
+	 * @param status The status of the game
+	 * @param depth The current search depth
+	 * @param maxDepth The maximum depth of the search
+	 * @return The score. The default implementation returns 0 for a draw, otherwise it considers the player loose and returns -{@link Evaluator#getWinScore(int)}.
+	 */
 	protected int getScore(final Evaluator<M,B> evaluator, final Status status, final int depth, int maxDepth) {
 		if (Status.DRAW==status) {
 			return 0;
 		} else {
-			//FIXME Maybe there's some games where the player wins if it can't move...
 			return -evaluator.getWinScore(maxDepth-depth);
 		}
 	}