Struct ChessVectorEngine

pub struct ChessVectorEngine { /* private fields */ }

Chess Vector Engine - Fully open source, production-ready chess engine with hybrid evaluation

A powerful chess engine that combines vector-based pattern recognition with advanced tactical search and NNUE neural network evaluation. All features are included in the open source release under MIT/Apache-2.0 licensing.

Core Capabilities (All Open Source)

• Position Encoding: Convert chess positions to 1024-dimensional vectors
• Similarity Search: Find similar positions using cosine similarity
• Tactical Search: Advanced 14+ ply search with PVS and sophisticated pruning
• Opening Book: Fast lookup for 50+ openings with ECO codes
• NNUE Evaluation: Neural network position assessment with incremental updates
• GPU Acceleration: CUDA/Metal/CPU with automatic device detection
• UCI Protocol: Complete UCI engine implementation with pondering and Multi-PV

Available Configurations

• Standard: Default engine with 14-ply tactical search and all features
• Strong: Enhanced configuration for correspondence chess (18+ ply)
• Lightweight: Performance-optimized for real-time applications

Examples

Basic Usage

use chess_vector_engine::ChessVectorEngine;
use chess::Board;

let mut engine = ChessVectorEngine::new(1024);
let board = Board::default();

// Add position with evaluation
engine.add_position(&board, 0.0);

// Find similar positions
let similar = engine.find_similar_positions(&board, 5);

Advanced Configuration

use chess_vector_engine::ChessVectorEngine;

// Create strong engine for correspondence chess
let mut engine = ChessVectorEngine::new_strong(1024);

// Check GPU acceleration availability (always available)
let _gpu_status = engine.check_gpu_acceleration();

// All advanced features are included in open source
println!("Engine created with full feature access");

Implementations

impl ChessVectorEngine

pub fn new(vector_size: usize) -> Self

Create a new chess vector engine with strategic motifs and tactical search enabled by default This provides fast startup with master-level strategic understanding

pub fn new_strong(vector_size: usize) -> Self

Create new engine with strong tactical search configuration for correspondence chess

pub fn new_lightweight(vector_size: usize) -> Self

Create a lightweight engine without tactical search (for performance-critical applications)

pub fn new_with_full_database(vector_size: usize) -> Self

Create engine with full position database loading (legacy approach, slower startup) Use this for training scenarios where you need access to millions of raw positions

pub fn new_adaptive( vector_size: usize, expected_positions: usize, use_case: &str, ) -> Self

Create a new chess vector engine with intelligent architecture selection based on expected dataset size and use case

pub fn new_with_lsh( vector_size: usize, num_tables: usize, hash_size: usize, ) -> Self

Create a new chess vector engine with LSH enabled

pub fn enable_lsh(&mut self, num_tables: usize, hash_size: usize)

Enable LSH indexing

pub fn add_positions_bulk( &mut self, positions: &[(Board, f32, ChessMove)], pb: &ProgressBar, ) -> Result<(), Box<dyn Error>>

Add multiple positions in bulk for better performance

pub fn add_position(&mut self, board: &Board, evaluation: f32)

Add a position with its evaluation to the knowledge base

pub fn find_similar_positions( &mut self, board: &Board, k: usize, ) -> Vec<(Array1<f32>, f32, f32)>

Find similar positions to the given board

pub fn find_similar_positions_with_indices( &self, board: &Board, k: usize, ) -> Vec<(usize, f32, f32)>

Find similar positions with indices for move recommendation

pub fn evaluate_position(&mut self, board: &Board) -> Option<f32>

Get evaluation for a position using VECTOR-FIRST approach (pattern recognition primary, tactical refinement secondary) This is the key method that makes our 998k position database the primary competitive advantage

pub fn evaluate_position_simplified( &mut self, board: &Board, ) -> CoreEvaluationResult

NEW: Simplified evaluation method demonstrating our core hypothesis Traditional Engine + Vector Similarity + Strategic Initiative = Unique Strategic Insights

This method shows our philosophy: we COMPLEMENT traditional evaluation with unique insights, not compete with it. Use this for cleaner understanding of our value proposition.

pub fn encode_position(&self, board: &Board) -> Array1<f32>

Encode a position to vector (public interface)

pub fn calculate_similarity(&self, board1: &Board, board2: &Board) -> f32

Calculate similarity between two boards

pub fn knowledge_base_size(&self) -> usize

Get the size of the knowledge base

pub fn get_position_ref(&self, index: usize) -> Option<(&Array1<f32>, f32)>

Get position and evaluation by index for motif extraction

pub fn get_board_by_index(&self, index: usize) -> Option<&Board>

Get board position by index for motif extraction

pub fn get_evaluation_by_index(&self, index: usize) -> Option<f32>

Get evaluation by index for motif extraction

pub fn load_strategic_database<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Load strategic motif database for instant pattern recognition

pub fn get_strategic_motif_evaluation(&mut self, board: &Board) -> f32

Get strategic motif evaluation using motif database (master-level positional understanding) Enhanced with material awareness and tactical safety

pub fn enable_strategic_motifs(&mut self) -> Result<(), Box<dyn Error>>

Enable strategic motif database with fast loading

pub fn save_training_data<P: AsRef<Path>>( &self, path: P, ) -> Result<(), Box<dyn Error>>

Save engine state (positions and evaluations) to file for incremental training

pub fn load_training_data_incremental<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Load training data incrementally (append to existing engine state) - OPTIMIZED

pub fn save_training_data_binary<P: AsRef<Path>>( &self, path: P, ) -> Result<(), Box<dyn Error>>

Save training data in optimized binary format with compression (5-15x faster than JSON)

pub fn load_training_data_binary<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Load training data from optimized binary format (5-15x faster than JSON)

pub fn load_training_data_mmap<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast memory-mapped loading for instant startup Uses memory-mapped files to load training data with zero-copy access (PREMIUM FEATURE)

pub fn load_training_data_msgpack<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast MessagePack binary format loading MessagePack is typically 10-20% faster than bincode

pub fn load_training_data_streaming_json<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast streaming JSON loader with parallel processing Processes JSON in chunks with multiple threads for better performance

pub fn load_training_data_compressed<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast compressed loading with zstd Zstd typically provides better compression ratios than LZ4 with similar speed

pub fn train_from_dataset_incremental(&mut self, dataset: &TrainingDataset)

Train from dataset incrementally (preserves existing engine state)

pub fn training_stats(&self) -> TrainingStats

Get current training statistics

pub fn auto_load_training_data(&mut self) -> Result<Vec<String>, Box<dyn Error>>

Auto-load training data from common file names if they exist

pub fn load_lichess_puzzles<P: AsRef<Path>>( &mut self, csv_path: P, ) -> Result<(), Box<dyn Error>>

Load Lichess puzzle database with enhanced features

pub fn load_lichess_puzzles_with_limit<P: AsRef<Path>>( &mut self, csv_path: P, max_puzzles: Option<usize>, ) -> Result<(), Box<dyn Error>>

Load Lichess puzzle database with optional limit

pub fn new_with_auto_load(vector_size: usize) -> Result<Self, Box<dyn Error>>

Create a new chess vector engine with automatic training data loading

pub fn new_with_fast_load(vector_size: usize) -> Result<Self, Box<dyn Error>>

Create a new chess vector engine with fast loading optimized for gameplay Prioritizes binary formats and skips expensive model rebuilding

pub fn new_with_auto_discovery( vector_size: usize, ) -> Result<Self, Box<dyn Error>>

Create a new engine with automatic file discovery and smart format selection Automatically discovers training data files and loads the optimal format

pub fn new_with_instant_load(vector_size: usize) -> Result<Self, Box<dyn Error>>

Ultra-fast instant loading - loads best available format without consolidation This is the fastest possible loading method for production use

pub fn check_gpu_acceleration(&self) -> Result<(), Box<dyn Error>>

Check if GPU acceleration feature is available

pub fn load_starter_dataset(&mut self) -> Result<(), Box<dyn Error>>

Load starter dataset for open source users

pub fn ultra_fast_load_any_format<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast loader for any format - optimized for massive datasets (PREMIUM FEATURE)

pub fn load_training_data_streaming_binary<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast streaming binary loader for massive datasets (900k+ positions) Uses streaming processing to handle arbitrarily large datasets

pub fn load_training_data_streaming_json_v2<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), Box<dyn Error>>

Ultra-fast streaming JSON loader for massive datasets (900k+ positions) Uses streaming processing with minimal memory footprint

pub fn new_for_massive_datasets( vector_size: usize, ) -> Result<Self, Box<dyn Error>>

Create engine optimized for massive datasets (100k-1M+ positions) Uses streaming loading and minimal memory footprint

pub fn convert_to_msgpack() -> Result<(), Box<dyn Error>>

Convert existing JSON training data to ultra-fast MessagePack format MessagePack is typically 10-20% faster than bincode with smaller file sizes

pub fn convert_a100_binary_to_json() -> Result<(), Box<dyn Error>>

Convert A100 binary training data to JSON format for use with other converters

pub fn convert_to_zstd() -> Result<(), Box<dyn Error>>

Convert existing training data to ultra-compressed Zstd format Zstd provides excellent compression with fast decompression

pub fn convert_to_mmap() -> Result<(), Box<dyn Error>>

Convert existing training data to memory-mapped format for instant loading This creates a file that can be loaded with zero-copy access

pub fn convert_json_to_binary() -> Result<Vec<String>, Box<dyn Error>>

Convert existing JSON training files to binary format for faster loading

pub fn is_lsh_enabled(&self) -> bool

Check if LSH is enabled

pub fn lsh_stats(&self) -> Option<LSHStats>

Get LSH statistics if enabled

pub fn enable_opening_book(&mut self)

Enable opening book with standard openings

pub fn set_opening_book(&mut self, book: OpeningBook)

Set custom opening book

pub fn is_opening_position(&self, board: &Board) -> bool

Check if position is in opening book

pub fn get_opening_entry(&self, board: &Board) -> Option<&OpeningEntry>

Get opening book entry for position

pub fn opening_book_stats(&self) -> Option<OpeningBookStats>

Get opening book statistics

pub fn add_position_with_move( &mut self, board: &Board, evaluation: f32, chess_move: Option<ChessMove>, move_outcome: Option<f32>, )

Add a move played from a position with its outcome

pub fn recommend_moves_with_tactical_search( &mut self, board: &Board, num_recommendations: usize, ) -> Vec<MoveRecommendation>

Recommend moves using tactical search for safety verification

pub fn is_move_tactically_safe( &mut self, board: &Board, chess_move: ChessMove, ) -> bool

Deep tactical safety verification with quiescence search

pub fn recommend_moves( &mut self, board: &Board, num_recommendations: usize, ) -> Vec<MoveRecommendation>

Get move recommendations based on similar positions and opening book

pub fn recommend_legal_moves( &mut self, board: &Board, num_recommendations: usize, ) -> Vec<MoveRecommendation>

Generate legal move recommendations (filters recommendations by legal moves)

pub fn enable_persistence<P: AsRef<Path>>( &mut self, db_path: P, ) -> Result<(), Box<dyn Error>>

Enable persistence with database

pub fn save_to_database(&self) -> Result<(), Box<dyn Error>>

Save engine state to database using high-performance batch operations

pub fn load_from_database(&mut self) -> Result<(), Box<dyn Error>>

Load engine state from database

pub fn new_with_persistence<P: AsRef<Path>>( vector_size: usize, db_path: P, ) -> Result<Self, Box<dyn Error>>

Create engine with persistence enabled and auto-load from database

pub fn auto_save(&self) -> Result<(), Box<dyn Error>>

Auto-save to database (if persistence is enabled)

pub fn is_persistence_enabled(&self) -> bool

Check if persistence is enabled

pub fn database_position_count(&self) -> Result<i64, Box<dyn Error>>

Get database position count

pub fn enable_tactical_search(&mut self, config: TacticalConfig)

Enable tactical search with the given configuration

pub fn enable_tactical_search_default(&mut self)

Enable tactical search with default configuration

pub fn configure_hybrid_evaluation(&mut self, config: HybridConfig)

Configure hybrid evaluation settings

pub fn is_tactical_search_enabled(&self) -> bool

Check if tactical search is enabled

pub fn enable_parallel_search(&mut self, num_threads: usize)

Enable parallel tactical search with specified number of threads

pub fn is_parallel_search_enabled(&self) -> bool

Check if parallel search is enabled

pub fn enable_strategic_evaluation(&mut self, config: StrategicConfig)

Enable strategic evaluation for proactive, initiative-based play This transforms the engine from reactive to proactive by adding:

• Initiative assessment and attacking potential evaluation
• Strategic plan generation and execution
• Piece coordination analysis for attacks
• Proactive move generation instead of just responding

pub fn enable_strategic_evaluation_default(&mut self)

Enable strategic evaluation with default balanced configuration

pub fn enable_strategic_evaluation_aggressive(&mut self)

Enable aggressive strategic configuration for maximum initiative

pub fn enable_strategic_evaluation_positional(&mut self)

Enable positional strategic configuration for long-term planning

pub fn is_strategic_evaluation_enabled(&self) -> bool

Check if strategic evaluation is enabled

pub fn get_strategic_evaluation( &self, board: &Board, ) -> Option<StrategicEvaluation>

Get strategic evaluation for a position (if strategic evaluator is enabled)

pub fn generate_proactive_moves(&self, board: &Board) -> Vec<(ChessMove, f32)>

Generate proactive moves using strategic evaluation Returns moves ordered by strategic value (highest first)

pub fn should_play_aggressively(&self, board: &Board) -> bool

Check if the engine should play aggressively in current position

pub fn enable_nnue(&mut self) -> Result<(), Box<dyn Error>>

Enable NNUE neural network evaluation for fast position assessment Automatically loads default_hybrid.config if present, otherwise creates new NNUE

pub fn enable_nnue_with_auto_load( &mut self, auto_load: bool, ) -> Result<(), Box<dyn Error>>

Enable NNUE with optional auto-loading of default model

pub fn enable_nnue_with_config( &mut self, config: NNUEConfig, ) -> Result<(), Box<dyn Error>>

Enable NNUE with custom configuration (bypasses auto-loading)

pub fn enable_nnue_with_model( &mut self, model_path: &str, ) -> Result<(), Box<dyn Error>>

Enable NNUE and load a specific pre-trained model

pub fn quick_fix_nnue_if_needed(&mut self) -> Result<(), Box<dyn Error>>

Quick NNUE training if weights weren’t properly loaded

pub fn configure_nnue( &mut self, config: NNUEConfig, ) -> Result<(), Box<dyn Error>>

Configure NNUE settings (only works if NNUE is already enabled)

pub fn is_nnue_enabled(&self) -> bool

Check if NNUE neural network evaluation is enabled

pub fn train_nnue( &mut self, positions: &[(Board, f32)], ) -> Result<f32, Box<dyn Error>>

Train NNUE on position data (requires NNUE to be enabled)

pub fn hybrid_config(&self) -> &HybridConfig

Get current hybrid configuration

pub fn is_opening_book_enabled(&self) -> bool

Check if opening book is enabled

pub fn self_play_training( &mut self, config: SelfPlayConfig, ) -> Result<usize, Box<dyn Error>>

Run self-play training to generate new positions

pub fn continuous_self_play( &mut self, config: SelfPlayConfig, iterations: usize, save_path: Option<&str>, ) -> Result<usize, Box<dyn Error>>

Run continuous self-play training with periodic saving

pub fn adaptive_self_play( &mut self, base_config: SelfPlayConfig, target_strength: f32, ) -> Result<usize, Box<dyn Error>>

Self-play with adaptive difficulty (engine gets stronger as it learns)

Trait Implementations

impl Clone for ChessVectorEngine

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.