Many minor but breaking changes + javadoc

- Adds MoveLibrary.getMoves
- AbstractMoveLibrary getRecord changed to getRecords, and no more
return optional.
- Removes BasicEntry
- OrderedUtils renamed to SortedUtils
- PhysicalCores.UnreachableException renamed to UnavailableException

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

@@ -16,7 +16,11 @@ It also provides you with other useful building blocks like a clock, PerfT tests
 # Known limitations
 - 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)).  
 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 serach, futility prunig, killer or null move, etc ...).
+- 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.
 
 ## TODO (maybe)
 - Make MoveLibrary implement AI?

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

@@ -5,7 +5,7 @@
 
 import com.fathzer.games.ai.evaluation.EvaluatedMove;
 import com.fathzer.games.ai.evaluation.Evaluation;
-import com.fathzer.games.util.OrderedUtils;
+import com.fathzer.games.util.SortedUtils;
 
 /** The result of a best move search.
  */
@@ -38,7 +38,7 @@ synchronized int getLow() {
 	 * @param value The evaluation of the move
 	 */
 	public synchronized void add(M move, Evaluation value) {
-		OrderedUtils.insert(this.result, new EvaluatedMove<M>(move, value));
+		SortedUtils.insert(this.result, new EvaluatedMove<M>(move, value));
 	}
 
 	/** Updates the evaluation of a move.

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

@@ -103,7 +103,7 @@ public void movesGenerated(int moveCount) {
 	}
 
 	/** Gets the duration of the search in milliseconds.
-	 * <br>This method returns the time elapsed since the call to {@link #start()} or since this instance was created if {@link #start()} has not been called yet.
+	 * <br>This method returns the time elapsed since the call to {@link #clear()} or since this instance was created if {@link #clear()} has not been called yet.
 	 * @return a positive long
 	 */
 	public long getDurationMs() {

src/main/java/com/fathzer/games/ai/iterativedeepening/IterativeDeepeningSearch.java

@@ -10,7 +10,7 @@
 import com.fathzer.games.ai.DepthFirstAI;
 import com.fathzer.games.ai.iterativedeepening.IterativeDeepeningEngine.Mute;
 import com.fathzer.games.ai.iterativedeepening.IterativeDeepeningEngine.SearchEventLogger;
-import com.fathzer.games.util.OrderedUtils;
+import com.fathzer.games.util.SortedUtils;
 import com.fathzer.games.ai.DepthFirstSearchParameters;
 import com.fathzer.games.ai.SearchResult;
 import com.fathzer.games.ai.evaluation.EvaluatedMove;
@@ -97,7 +97,7 @@ private static <M> List<EvaluatedMove<M>> complete(SearchResult<M> result, List<
 			return result.getList();
 		}
 		final var moves = new ArrayList<>(result.getList());
-		ended.stream().forEach(em -> OrderedUtils.insert(moves, em));
+		ended.stream().forEach(em -> SortedUtils.insert(moves, em));
 		return moves;
 	}
 

src/main/java/com/fathzer/games/ai/transposition/BasicEntry.java

@@ -35,6 +35,14 @@ public AlphaBetaState<M> accept(TranspositionTableEntry<M> entry, int depth, int
 		return state;
 	}
 
+	/** Processes an non exact transposition table entry.
+	 * <br>This method is called by {@link #accept(TranspositionTableEntry, int, int, int, IntUnaryOperator)} when entry is not null and it is not invalid and its type is not EXACT.
+	 * @param entry The entry
+	 * @param alpha The current alpha value
+	 * @param beta The current beta value
+	 * @param value The value stored in the entry, converted by the <code>toTTScoreConverter</code> function passed to the {@link #accept(TranspositionTableEntry, int, int, int, IntUnaryOperator)} method.
+	 * @param state The state to update (this state will be returned by @link #accept(TranspositionTableEntry, int, int, int, IntUnaryOperator)).
+	 */
 	protected void acceptNonExactRecord(TranspositionTableEntry<M> entry, int alpha, int beta, final int value, final AlphaBetaState<M> state) {
 		boolean updated = false;
 		if (LOWER_BOUND==entry.getEntryType()) {
@@ -71,6 +79,17 @@ public boolean store(TranspositionTable<M, B> table, long key, AlphaBetaState<M>
 		return table.store(key, type, state.getDepth(), toTTScoreConverter.applyAsInt(state.getValue()), state.getBestMove(), p-> shouldReplace(p, key, state.getDepth(), type));
 	}
 
+	/** Checks whether an entry should be replaced by new data.
+	 * @param entry The entry that is currently in the transposition table
+	 * @param newKey The new entry key
+	 * @param newDepth The new entry depth
+	 * @param newType The new entry type
+	 * @return true if the entry should be replaced, false otherwise. The default implementation returns true if:<ul>
+	 * <li>of course, the current entry is invalid</li>
+	 * <li>the new entry is exact and the current entry is not exact</li>
+	 * <li>the current entry and the new depth is &gt; the current depth</li>
+	 * </ul>
+	 */
 	protected boolean shouldReplace(TranspositionTableEntry<M> entry, long newKey, int newDepth, EntryType newType) {
 		if (!entry.isValid()) {
 			// Always write if no entry is in the table

src/main/java/com/fathzer/games/ai/transposition/BasicPolicy.java

@@ -4,8 +4,21 @@
 import java.util.Collections;
 import java.util.List;
 
+/** The type of a <a href="https://en.wikipedia.org/wiki/Transposition_table">transposition table</a> entry. 
+ */
 public enum EntryType {
-	INVALID, EXACT, LOWER_BOUND, UPPER_BOUND;
+	/** Entry is invalid (typically, not yet assigned) */
+	INVALID, 
+	/** Entry has an exact value */
+	EXACT, 
+	/** Entry has a lower bound value */
+	LOWER_BOUND, 
+	/** Entry has an upper bound value */
+	UPPER_BOUND;
 
-	public static final List<EntryType> ALL = Collections.unmodifiableList(Arrays.asList(EntryType.values())); 
+	/** A list of all entry types
+	 * <br>This list is immutable and can be used as a constant.
+	 * <br>It can also be used as a replacement for the standard {@link #values()} method that allocates a new array every time it is called.
+	 */
+	public static final List<EntryType> ALL = Collections.unmodifiableList(Arrays.asList(EntryType.values()));
 }

src/main/java/com/fathzer/games/ai/transposition/EntryType.java

@@ -1,7 +1,13 @@
 package com.fathzer.games.ai.transposition;
 
+/** A unit of size for memory size. */
 public enum SizeUnit {
-	MB(1024*1024), KB(1024), B(1);
+	/** Megabytes (1024KB) */
+	MB(1024*1024), 
+	/** Kilobytes (1024 Bytes) */
+	KB(1024), 
+	/** Bytes (1B) */
+	B(1);
 
 	private final int size;
 

src/main/java/com/fathzer/games/ai/transposition/SizeUnit.java

@@ -8,7 +8,7 @@
 /** A class that decide if a transposition table entry should be replaced or not.
  */
 public interface TranspositionTablePolicy<M, B extends MoveGenerator<M>> {
-    /** Process a transposition table entry.
+    /** Processes a transposition table entry.
      * <br>This method is called before iterating on possible moves to use entry data in order to speed up the Negamax algorithm.
      * <br>One can override it to customize how transposition table entries are used.
      * <br>The default behaviour is to return the value of entries with {@link EntryType#EXACT} type and depth &gt;= the current negamax depth and ignore others.

src/main/java/com/fathzer/games/ai/transposition/TranspositionTablePolicy.java

@@ -0,0 +1,3 @@
+/** <a href="https://en.wikipedia.org/wiki/Transposition_table">Transposition tables</a> related classes.
+*/
+package com.fathzer.games.ai.transposition;

src/main/java/com/fathzer/games/ai/transposition/package-info.java

@@ -1,5 +1,6 @@
 package com.fathzer.games.movelibrary;
 
+import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
 import java.util.Random;
@@ -59,9 +60,9 @@ public Function<List<R>, R> weightedMoveSelector() {
 
 	/** Gets the records related to a position.
 	 * @param board The position
-	 * @return A list of records, each of them describes a move. Or an empty optional if the position is not in the base
+	 * @return A list of records, each of them describes a move, an empty list if the position is not in the base
 	 */
-	protected abstract Optional<List<R>> getRecord(B board);
+	protected abstract List<R> getRecords(B board);
 
 	/** Converts a database record that describes an evaluated move to a move instance.
 	 * @param board The position
@@ -70,7 +71,7 @@ public Function<List<R>, R> weightedMoveSelector() {
 	 */
 	protected abstract EvaluatedMove<M> toEvaluatedMove(B board, R move);
 
-	/** Sets the move selector (the function that selects a move in the list of move records returned by {@link #getRecord(MoveGenerator)}
+	/** Sets the move selector (the function that selects a move in the list of move records returned by {@link #getRecords(MoveGenerator)}
 	 * <br>By default, the move is randomly chosen in the list.
 	 * @param moveSelector A move selector
 	 */
@@ -85,17 +86,25 @@ public void setNext(MoveLibrary<M, MoveGenerator<M>> next) {
 		this.other = next;
 	}
 
+	@Override
+	public List<EvaluatedMove<M>> getMoves(B board) {
+		final List<R> moves = getRecords(board);
+		if (moves.isEmpty()) {
+			return other==null ? Collections.emptyList() : other.getMoves(board);
+		}
+		return moves.stream().map(r -> toEvaluatedMove(board, r)).toList();
+	}
+
 	/** {@inheritDoc}
 	 * <br>If this library can't find a move for this position, and a 'next' library was linked with this using {@link #setNext(MoveLibrary)},
 	 * its apply method's result is returned.
 	 */
 	@Override
 	public Optional<EvaluatedMove<M>> apply(B board) {
-		final Optional<List<R>> theRecordO = getRecord(board);
-		if (theRecordO.isEmpty()) {
+		final List<R> moves = getRecords(board);
+		if (moves.isEmpty()) {
 			return other==null ? Optional.empty() : other.apply(board);
 		}
-		final List<R> moves = theRecordO.get();
 		final R selectedRecord = moveSelector.apply(moves);
 		return Optional.of(toEvaluatedMove(board, selectedRecord));
 	}

src/main/java/com/fathzer/games/movelibrary/AbstractMoveLibrary.java

@@ -1,5 +1,6 @@
 package com.fathzer.games.movelibrary;
 
+import java.util.List;
 import java.util.Optional;
 import java.util.function.Function;
 
@@ -12,6 +13,11 @@
  * @param <B> The type of game board
  */
 public interface MoveLibrary<M, B extends MoveGenerator<M>> extends Function<B, Optional<EvaluatedMove<M>>> {
+	/** Gets the moves for a position.
+	 * @param board a position
+	 * @return The moves available for the position in the library and their evaluations, or an empty list if it can't find any move.
+	 */
+	List<EvaluatedMove<M>> getMoves(B board);
 
 	/**
 	 * Gets the move to play for a position.

src/main/java/com/fathzer/games/movelibrary/MoveLibrary.java

@@ -7,8 +7,8 @@
 import java.util.ListIterator;
 
 /** A specialized list optimized to sort moves.
- * Some ai algorithm, like alpha-beta pruning can be greatly optimized when moves are sorted with the (a priori) best moves first.
- * Usually, the <i>a priori</i> considers a lot of possible moves as equivalent;
+ * <br>Some ai algorithm, like alpha-beta pruning can be greatly optimized when moves are sorted with the (a priori) best moves first.
+ * Usually, the <i>a priori</i> comparator considers a lot of possible moves as equivalent;
  * Typically, in chess, all non promotion, non capture moves are considered equivalent.<br>
  * As <a href="https://en.wikipedia.org/wiki/Sorting_algorithm#Classification">sort has a O(<i>n</i>&#160;log&#160;<i>n</i>) computational complexity</a>, an optimization is to sort only the promotion or capture moves.
  * This class does this optimization by excluding from the sort all moves with an evaluation of Integer.MIN_VALUE.