Struct TranspositionTable 

pub struct TranspositionTable { /* private fields */ }

A map of game state values referenced by the states’ fingerprints.

A game state can be the result of different sequences of the same (or a different) set of moves. This technique is used to cache the value of a game state regardless of the moves used to reach it, thus the name “transposition” table. The purpose of the “transposition” table has been extended to become simply a cache of game state values, so it is more aptly named “game state value cache” – but the old name persists.

As a speed and memory optimization in this implementation, slots in the table are not unique to the state being stored, and a value may be overwritten when a new value is added. A value is overwritten only when its “quality” is less than or equal to the “quality” of the value being added.

Note

The fingerprint is assumed to be a random and uniformly distributed 64-bit value. It is assumed to never be u64::MAX.

Examples

let mut table = TranspositionTable::new(1000, 100);

// Store a value
table.update(12345, 0.75, 5);

// Retrieve the value
if let Some((value, quality)) = table.check(12345, 0) {
    assert_eq!(value, 0.75);
    assert_eq!(quality, 5);
}

Implementations

impl TranspositionTable

pub fn new(size: usize, max_age: i16) -> Self

Creates a new TranspositionTable

Arguments

• size - Number of entries in the table
• max_age - Maximum age of entries allowed in the table

Examples

let table = TranspositionTable::new(1000, 50);
// Table is ready to use with 1000 entries and max age of 50

Panics

Panics if size is 0 or max_age is 0 or negative.

let table = TranspositionTable::new(0, 50); // This will panic

pub fn check(&mut self, fingerprint: u64, min_q: i16) -> Option<(f32, i16)>

Returns the value and quality of a state if they are stored in the table and its quality is above the specified minimum (if specified). Otherwise, None is returned.

Arguments

• fingerprint - Fingerprint of state to be checked for
• min_q - Minimum quality. If less than 0, it is not used.

Returns

optional result as (value, quality)

Panics

Panics if fingerprint is u64::MAX.

Side Effects

• Resets the age of the entry to 0 if found.

Examples

let mut table = TranspositionTable::new(100, 10);

// Store a value with quality 5
table.update(12345, 1.5, 5);

// Check with no minimum quality
assert_eq!(table.check(12345, -1), Some((1.5, 5)));

// Check with minimum quality of 3 (should succeed)
assert_eq!(table.check(12345, 3), Some((1.5, 5)));

// Check with minimum quality of 10 (should fail)
assert_eq!(table.check(12345, 10), None);

// Check non-existent entry
assert_eq!(table.check(99999, -1), None);

pub fn update(&mut self, fingerprint: u64, value: f32, quality: i16)

Updates (or adds) an entry in the table if its quality is greater than or equal to the existing entry’s quality

Arguments

• fingerprint - Fingerprint of state to be stored
• value - Value to be stored
• quality - Quality of the value

Panics

Panics if fingerprint is u64::MAX. Panics if quality is negative.

Examples

let mut table = TranspositionTable::new(100, 10);

// Add a new entry
table.update(12345, 1.0, 5);
assert_eq!(table.check(12345, -1), Some((1.0, 5)));

// Try to update with lower quality (should not replace)
table.update(12345, 2.0, 3);
assert_eq!(table.check(12345, -1), Some((1.0, 5))); // Original value

// Update with higher quality (should replace)
table.update(12345, 2.0, 7);
assert_eq!(table.check(12345, -1), Some((2.0, 7))); // New value

pub fn set(&mut self, fingerprint: u64, value: f32, quality: i16)

Sets an entry in the table.

This method adds or updates an entry in the table, regardless of its quality.

Arguments

• fingerprint - Fingerprint of state to be stored
• value - Value to be stored
• quality - Quality of the value

Panics

Panics if fingerprint is u64::MAX. Panics if quality is negative.

Examples

let mut table = TranspositionTable::new(100, 10);

// Set an entry
table.set(12345, 1.5, 5);
assert_eq!(table.check(12345, -1), Some((1.5, 5)));

// Set again with lower quality (should still replace)
table.set(12345, 2.5, 3);
assert_eq!(table.check(12345, -1), Some((2.5, 3)));

pub fn age(&mut self)

The T-table is persistent. So in order to gradually dispose of entries that are no longer relevant, entries that have not been referenced for a while are removed.

This method increments the age of all entries and removes entries that exceed the maximum age.

Examples

let mut table = TranspositionTable::new(100, 2); // max_age = 2

// Add an entry
table.set(12345, 1.0, 5);
assert_eq!(table.check(12345, -1), Some((1.0, 5)));

// Age the table once - entry should still be there
table.age();
assert_eq!(table.check(12345, -1), Some((1.0, 5))); // Age reset by check

// Age twice more without accessing - entry should be removed
table.age();
table.age();
table.age();
assert_eq!(table.check(12345, -1), None); // Entry aged out