Struct ChessVectorEngine

pub struct ChessVectorEngine { /* private fields */ }

Chess Vector Engine - 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. Features an open-core architecture with runtime license verification for premium capabilities.

Core Capabilities

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

Feature Tiers

• Open Source: Basic functionality, 6-ply search, similarity search, opening book
• Premium: GPU acceleration, NNUE networks, 10+ ply search, multi-threading
• Enterprise: Distributed training, unlimited positions, enterprise analytics

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);

With Premium Features

use chess_vector_engine::{ChessVectorEngine, FeatureTier};

// Create engine with premium features (requires license)
let mut engine = ChessVectorEngine::new_with_tier(1024, FeatureTier::Premium);

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

// Premium features are now available (with valid license)
println!("Engine created with premium tier access");

Implementations

impl ChessVectorEngine

pub fn new(vector_size: usize) -> Self

Create a new chess vector engine

pub fn new_with_tier(vector_size: usize, tier: FeatureTier) -> Self

Create new engine with specific feature tier

pub fn get_feature_tier(&self) -> &FeatureTier

Get current feature tier

pub fn upgrade_tier(&mut self, new_tier: FeatureTier)

Upgrade feature tier (for license activation)

pub fn is_feature_available(&self, feature: &str) -> bool

Check if a feature is available

pub fn require_feature(&self, feature: &str) -> Result<(), FeatureError>

Require a feature (returns error if not available)

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_position(&mut self, board: &Board, evaluation: f32)

Add a position with its evaluation to the knowledge base

pub fn find_similar_positions( &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 hybrid approach (opening book + pattern evaluation + tactical search)

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 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_premium<P: AsRef<Path>>( &mut self, csv_path: P, ) -> Result<(), Box<dyn Error>>

Load Lichess puzzle database with premium features (Premium+)

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

Load limited Lichess puzzle database (Open Source)

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 new_with_license(vector_size: usize, license_url: String) -> Self

Create engine with license verification system

pub fn new_with_offline_license(vector_size: usize) -> Self

Create engine with offline license verification

pub async fn activate_license( &mut self, key: &str, ) -> Result<FeatureTier, LicenseError>

Activate license key

pub async fn check_licensed_feature( &mut self, feature: &str, ) -> Result<(), FeatureError>

Check if feature is licensed (async version with license verification)

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

Load license cache from disk

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

Save license cache to disk

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_manifold_learning( &mut self, compression_ratio: f32, ) -> Result<(), String>

Enable manifold learning with specified compression ratio

pub fn train_manifold_learning(&mut self, epochs: usize) -> Result<(), String>

Train manifold learning on existing positions

pub fn enable_manifold_lsh( &mut self, num_tables: usize, hash_size: usize, ) -> Result<(), String>

Enable LSH for manifold space

pub fn is_manifold_enabled(&self) -> bool

Check if manifold learning is enabled and trained

pub fn manifold_compression_ratio(&self) -> Option<f32>

Get manifold learning compression ratio

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

Load pre-trained manifold models from database This enables compressed similarity search without retraining

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( &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 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.

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

Performs copy-assignment from source.