Sorted in-memory table mapping Huffman-encoded positions to scores. More...

#include <OpeningBook.h>

Public Member Functions
	OpeningBook (const std::filesystem::path &bookPath, const bool is_8ply, const bool with_distances)
	Load an opening book with explicit flavour selection.
	OpeningBook (const std::filesystem::path &bookPath)
	Load an opening book and auto-detect its flavour.
auto	getBook () const
	Copy of the underlying sorted (key, value) array.
void	init (const std::filesystem::path &bookPath, const bool is_8ply, const bool with_distances)
	Re-initialise the book in place.
auto	getEntry (const size_t entryIdx) const
	Random-access getter for raw book entries.
auto	getBookSize () const
	Number of entries currently held in memory.
int	getNPly () const
	Number of stones-on-board the book covers (8 or 12).
int	convertValue (const int value, const Board &b) const
	Translate a raw book value into the engine's score convention.
bool	isInBook (const Board &b) const
	Test whether the exact (non-mirrored) position is in the book.
int	getBoardValue (const Board &b) const
	Retrieve the engine score for a position covered by the book.

Static Public Member Functions
static std::tuple< key_t, int >	readline (std::ifstream &file, const bool with_distances, const bool is_8ply)
	Read a single entry from a binary book stream.
static std::vector< std::tuple< key_t, value_t > >	readBook (const std::filesystem::path &filename, const bool with_distances=true, const bool is_8ply=false)
	Slurp an entire opening book file into memory.
template<typename T>
static int	sign (T value)
	Numerical sign function returning -1, 0 or +1.

Static Public Attributes
static constexpr auto	NONE_VALUE = std::numeric_limits<value_t>::min()
	Sentinel returned when a position is not present in the book.

Detailed Description

Sorted in-memory table mapping Huffman-encoded positions to scores.

Lookups use binary search over Board::toHuffman() keys. Lookups automatically check the mirrored variant if the original key is not in the book, since only one of the two symmetric positions is stored on disk.

Definition at line 41 of file OpeningBook.h.

Constructor & Destructor Documentation

◆ OpeningBook() [1/2]

BitBully::OpeningBook::OpeningBook	(	const std::filesystem::path &	bookPath,
		const bool	is_8ply,
		const bool	with_distances )

inlineexplicit

Load an opening book with explicit flavour selection.

Parameters

bookPath	Path to the binary book file.
is_8ply	`true` to load the 8-ply database, `false` for the 12-ply database.
with_distances	`true` if the file stores distance-to-mate information in a dedicated byte (only valid for the 12-ply database).

Exceptions

std::invalid_argument if bookPath does not exist.

Definition at line 109 of file OpeningBook.h.

Here is the call graph for this function:

◆ OpeningBook() [2/2]

BitBully::OpeningBook::OpeningBook ( const std::filesystem::path & bookPath )

inlineexplicit

Load an opening book and auto-detect its flavour.

The flavour is inferred from the on-disk file size.

Parameters

bookPath Path to the binary book file.

Exceptions

std::invalid_argument if bookPath does not exist.

Definition at line 122 of file OpeningBook.h.

Here is the call graph for this function:

Member Function Documentation

◆ convertValue()

int BitBully::OpeningBook::convertValue	(	const int	value,
		const Board &	b ) const

inline

Translate a raw book value into the engine's score convention.

If the loaded book does not include distance information the value is already in the engine's scoring system and is returned unchanged. Otherwise the distance-to-mate stored in value is converted to the compact +/- ((moves_left)/2 + 1) representation used elsewhere.

Parameters

value	Raw book value.
b	Position the value was retrieved for.

Returns: Score in the engine's convention.

Definition at line 317 of file OpeningBook.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getBoardValue()

int BitBully::OpeningBook::getBoardValue ( const Board & b ) const

inlinenodiscard

Retrieve the engine score for a position covered by the book.

Looks up the position by its Huffman key, falls back to the mirrored variant, and applies a couple of well-known special cases for missing 8-ply / 12-ply entries (e.g. player Yellow with an immediate win is intentionally absent from the on-disk databases).

Parameters

b	Position to look up. Must contain exactly getNPly() stones; otherwise the function returns NONE_VALUE.

Returns: Engine score, or NONE_VALUE if b is not covered by the book.

Definition at line 352 of file OpeningBook.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getBook()

auto BitBully::OpeningBook::getBook ( ) const

inline

Copy of the underlying sorted (key, value) array.

Definition at line 137 of file OpeningBook.h.

Here is the caller graph for this function:

◆ getBookSize()

auto BitBully::OpeningBook::getBookSize ( ) const

inlinenodiscard

Number of entries currently held in memory.

Definition at line 201 of file OpeningBook.h.

Here is the caller graph for this function:

◆ getEntry()

auto BitBully::OpeningBook::getEntry ( const size_t entryIdx ) const

inlinenodiscard

Random-access getter for raw book entries.

Parameters

entryIdx Zero-based entry index.

Returns: Tuple of (Huffman key, value).

Exceptions

std::out_of_range if entryIdx exceeds the book size.

Definition at line 196 of file OpeningBook.h.

Here is the caller graph for this function:

◆ getNPly()

int BitBully::OpeningBook::getNPly ( ) const

inline

Number of stones-on-board the book covers (8 or 12).

Definition at line 262 of file OpeningBook.h.

Here is the caller graph for this function:

◆ init()

void BitBully::OpeningBook::init	(	const std::filesystem::path &	bookPath,
		const bool	is_8ply,
		const bool	with_distances )

inline

Re-initialise the book in place.

Replaces the currently loaded data with the contents of bookPath. Uses the same flavour parameters as the explicit three-argument OpeningBook constructor.

Parameters

bookPath	Path to the binary book file.
is_8ply	Select the 8-ply database.
with_distances	Indicate that the book stores distances.

Exceptions

std::invalid_argument if bookPath does not exist.

Definition at line 151 of file OpeningBook.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isInBook()

bool BitBully::OpeningBook::isInBook ( const Board & b ) const

inlinenodiscard

Test whether the exact (non-mirrored) position is in the book.

Note: Most positions are stored only in one of the two mirror-symmetric variants. To accept either variant use getBoardValue() and compare against NONE_VALUE.

Parameters

b	Position to check.

Returns: true if the position is stored verbatim.

Definition at line 335 of file OpeningBook.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readBook()

std::vector< std::tuple< key_t, value_t > > BitBully::OpeningBook::readBook	(	const std::filesystem::path &	filename,
		const bool	with_distances = true,
		const bool	is_8ply = false )

inlinestatic

Slurp an entire opening book file into memory.

Parameters

filename	Path to the binary book file.
with_distances	Whether the file stores distance-to-mate bytes.
is_8ply	Whether the file is the 8-ply database.

Returns: Sorted vector of (key, value) pairs. Empty if the file cannot be opened.

Definition at line 273 of file OpeningBook.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readline()

std::tuple< key_t, int > BitBully::OpeningBook::readline	(	std::ifstream &	file,
		const bool	with_distances,
		const bool	is_8ply )

inlinestatic

Read a single entry from a binary book stream.

Decodes one (Huffman key, value) pair according to the chosen flavour.

Parameters

file	Input stream positioned at the start of an entry.
with_distances	`true` if the book stores a separate distance byte; `false` if the value is packed into the lowest two bits of the key.
is_8ply	`true` to read 3-byte 8-ply keys, `false` for 4-byte 12-ply keys.

Returns: The decoded (key, value) pair, or {0, 0} if the read fails.

Definition at line 216 of file OpeningBook.h.

Here is the caller graph for this function:

◆ sign()

template<typename T>

int BitBully::OpeningBook::sign ( T value )

inlinestatic

Numerical sign function returning -1, 0 or +1.

Template Parameters

T	Any signed arithmetic type.

Parameters

value Input value.

Returns: Sign of value.

Definition at line 301 of file OpeningBook.h.

Here is the caller graph for this function:

Member Data Documentation

◆ NONE_VALUE

auto BitBully::OpeningBook::NONE_VALUE = std::numeric_limits<value_t>::min()

staticconstexpr

Sentinel returned when a position is not present in the book.

Definition at line 97 of file OpeningBook.h.

The documentation for this class was generated from the following file:

src/OpeningBook.h

	BitBully 0.0.78 A fast, perfect-play Connect-4 engine in modern C++

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ OpeningBook() [1/2]

◆ OpeningBook() [2/2]

Member Function Documentation

◆ convertValue()

◆ getBoardValue()

◆ getBook()

◆ getBookSize()

◆ getEntry()

◆ getNPly()

◆ init()

◆ isInBook()

◆ readBook()

◆ readline()

◆ sign()

Member Data Documentation

◆ NONE_VALUE