net.viktorc.detroid.framework.uci

Interface UCIEngine

All Superinterfaces:

AutoCloseable, Closeable

All Known Subinterfaces:

ControllerEngine, TunableEngine

All Known Implementing Classes:

Detroid

public interface UCIEngine
extends Closeable

The interface needed to be implemented by an engine to ensure it is UCI compliant.

Author:

Viktor

Field Summary

Fields

Modifier and Type	Field and Description
static String	HASH_OPTION_NAME A standard spin type UCI option that determines the size of the hash tables used by the chess engine.
static String	OWN_BOOK_OPTION_NAME A standard check type UCI option that determines whether the engine should use its own book.
static String	START_POSITION A special UCI position command for the start position.
static String	THREADS_OPTION_NAME A standard spin type UCI option that determines the number of search threads to use.

Method Summary

Modifier and Type	Method and Description
default void	close()
String	getAuthor() Returns the name of the author of the engine.
DebugInformation	getDebugInfo() Returns an observable object containing information that is not related to the game but can help detecting bugs in debug mode.
short	getHashLoadPermill() Returns the load factor of the hash tables in permills.
String	getName() Returns the name of the engine.
Map<Option<?>,Object>	getOptions() Returns the options the engine offers and their values.
SearchInformation	getSearchInfo() Returns an observable object containing information about the results and statistics of the ongoing/last search.
void	init() Initialises the engine; e.g.
boolean	isInit() Returns whether the method init has already been called on the instance.
void	newGame() Resets the game.
boolean	play(String pacn) Prompts the engine to make the move defined in Pure Algebraic Coordinate Notation.
void	ponderHit() Signals to the engine that the move it was pondering on was actually played and it should keep searching in normal mode.
void	quit() Signals the engine that it should clean up and free the resources it has been using.
SearchResults	search(Set<String> searchMoves, Boolean ponder, Long whiteTime, Long blackTime, Long whiteIncrement, Long blackIncrement, Integer movesToGo, Integer depth, Long nodes, Integer mateDistance, Long searchTime, Boolean infinite) Prompts the engine to start searching the current position according to the specified parameters.
void	setDebugMode(boolean on) Notifies the engine whether it should keep updating the DebugInformation instance exposed by the getDebugInfo method with debug information strings.
default boolean	setHashSizeOption(int value) It attempts to set the hash size the engine should use if the option is provided by the engine.
default <T,U extends Option<T>> boolean	setOption(Class<U> optionType, String optionName, T value) It looks for an option of the specified type and name among the options provided by the engine, and if it is found, it attempts to set it to the specified value.
<T> boolean	setOption(Option<T> setting, T value) Sets an option defined by the engine to the specified value.
default boolean	setOwnBookOption(boolean value) It attempts to set whether the engine should use its own opening book if the option is provided by the engine.
default boolean	setPosition() Sets the current position of the engine to the starting position.
boolean	setPosition(String fen) Sends the current position to the engine.
default boolean	setThreadsOption(int value) It attempts to set the number of threads the engine should use if the option is provided by the engine.
void	stop() Prompts the engine to stop searching and return the best move found up until that point.

Field Detail

START_POSITION

static final String START_POSITION

A special UCI position command for the start position.

See Also:

Constant Field Values

OWN_BOOK_OPTION_NAME

static final String OWN_BOOK_OPTION_NAME

A standard check type UCI option that determines whether the engine should use its own book. It should be false by default.

See Also:

Constant Field Values

THREADS_OPTION_NAME

static final String THREADS_OPTION_NAME

A standard spin type UCI option that determines the number of search threads to use.

See Also:

Constant Field Values

HASH_OPTION_NAME

static final String HASH_OPTION_NAME

A standard spin type UCI option that determines the size of the hash tables used by the chess engine. Its unit is MB.

See Also:

Constant Field Values

Method Detail

init

void init()
   throws Exception

Initialises the engine; e.g. set up the tables, load parameters, etc. The engine is not expected to function properly without calling this method on the instance first.

Throws:

Exception - If the engine cannot be initialized due to some reason.

isInit

boolean isInit()

Returns whether the method init has already been called on the instance.

Returns:

Whether the engine has been initialized.

getName

String getName()

Returns the name of the engine.

Returns:

The name of the engine.

getAuthor

String getAuthor()

Returns the name of the author of the engine.

Returns:

The name of the author of the engine.

getOptions

Map<Option<?>,Object> getOptions()

Returns the options the engine offers and their values. Changes to the map are not propagated to the engine.

Returns:

The UCI options the engine offers and their values.

setOption

<T> boolean setOption(Option<T> setting,
                      T value)

Sets an option defined by the engine to the specified value.

Type Parameters:

T - The type of the value the option holds.

Parameters:

setting - The UCI option to set.

value - The value to which the option should be set.

Returns:

Whether the setting was successfully set to the value, i.e. the option exists and it is an allowed value.

setDebugMode

void setDebugMode(boolean on)

Notifies the engine whether it should keep updating the DebugInformation instance exposed by the getDebugInfo method with debug information strings.

Parameters:

on - Whether the engine should run in debug mode.

newGame

void newGame()

Resets the game. It might be a good idea for the engine to wipe the hash tables at this point.

setPosition

boolean setPosition(String fen)

Sends the current position to the engine. The string "startpos" denotes the starting position and should be handled by the engine.

Parameters:

fen - The current position in FEN.

Returns:

Whether the position could be successfully set up.

play

boolean play(String pacn)

Prompts the engine to make the move defined in Pure Algebraic Coordinate Notation.

Parameters:

pacn - The move to play in PACN.

Returns:

Whether the move was successfully made.

search

SearchResults search(Set<String> searchMoves,
                     Boolean ponder,
                     Long whiteTime,
                     Long blackTime,
                     Long whiteIncrement,
                     Long blackIncrement,
                     Integer movesToGo,
                     Integer depth,
                     Long nodes,
                     Integer mateDistance,
                     Long searchTime,
                     Boolean infinite)

Prompts the engine to start searching the current position according to the specified parameters.

Parameters:

searchMoves - A set of the moves to search at the root node in pure algebraic coordinate notation.

ponder - Whether the engine should search in pondering mode.

whiteTime - The time left on the clock for white in ms.

blackTime - The time left on the clock for black in ms.

whiteIncrement - Increment per move in ms.

blackIncrement - Increment per move in ms.

movesToGo - The number of moves until the next time control.

depth - The depth to which the position should be searched. If it is 0, the engine should return the score determined by the quiescence search or if it is not implemented, the static evaluation score.

nodes - The maximum number of nodes that should be searched.

mateDistance - Search for a mate in x.

searchTime - Search exactly this number of ms.

infinite - Whether the position should be searched infinitely.

Returns:

The best move found and optionally the suggested ponder move in pure algebraic coordinate notation and optionally the search score and search score type.

stop

void stop()

Prompts the engine to stop searching and return the best move found up until that point. It should cause the search method to terminate within a few milliseconds at most. If the engine is not searching at the time of the call, it should be ignored. It should block until the search is finished.

ponderHit

void ponderHit()

Signals to the engine that the move it was pondering on was actually played and it should keep searching in normal mode.

getSearchInfo

SearchInformation getSearchInfo()

Returns an observable object containing information about the results and statistics of the ongoing/last search.

Returns:

An observable object containing information about the results and statistics of the ongoing/last search.

getHashLoadPermill

short getHashLoadPermill()

Returns the load factor of the hash tables in permills.

Returns:

The load factor of the hash tables in permills.

getDebugInfo

DebugInformation getDebugInfo()

Returns an observable object containing information that is not related to the game but can help detecting bugs in debug mode.

Returns:

An observable object containing information that is not related to the game but can help detecting bugs in debug mode.

quit

void quit()

Signals the engine that it should clean up and free the resources it has been using.

setPosition

default boolean setPosition()

Sets the current position of the engine to the starting position.

Returns:

Whether the position could be successfully set up.

setOption

default <T,U extends Option<T>> boolean setOption(Class<U> optionType,
                                                  String optionName,
                                                  T value)

It looks for an option of the specified type and name among the options provided by the engine, and if it is found, it attempts to set it to the specified value.

Type Parameters:

T - The value type of the option.

U - The option type.

Parameters:

optionType - The type of the option to look for.

optionName - The name of the option.

value - The value to which it should be set.

Returns:

Whether the option was found and successfully set.

setOwnBookOption

default boolean setOwnBookOption(boolean value)

It attempts to set whether the engine should use its own opening book if the option is provided by the engine.

Parameters:

value - Whether the engine should use its own opening book.

Returns:

Whether the option was successfully set.

setHashSizeOption

default boolean setHashSizeOption(int value)

It attempts to set the hash size the engine should use if the option is provided by the engine.

Parameters:

value - The hash size to use (in bytes).

Returns:

Whether the option was successfully set.

setThreadsOption

default boolean setThreadsOption(int value)

It attempts to set the number of threads the engine should use if the option is provided by the engine.

Parameters:

value - The number of search threads the engine should use.

Returns:

Whether the option was successfully set.

close

default void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable