quantmllibrary 0.1.0__py3-none-any.whl

quantml/training/walk_forward.py

@@ -0,0 +1,190 @@
+"""
+Walk-forward optimization for time-series model training.
+
+Walk-forward optimization is essential for quant trading to prevent lookahead bias
+and properly evaluate model performance on out-of-sample data.
+"""
+
+from typing import List, Tuple, Optional, Callable, Any
+from enum import Enum
+
+
+class WindowType(Enum):
+    """Type of walk-forward window."""
+    EXPANDING = "expanding"  # Training window grows over time
+    ROLLING = "rolling"      # Training window has fixed size
+
+
+class WalkForwardOptimizer:
+    """
+    Walk-forward optimization for time-series cross-validation.
+    
+    This class manages train/test splits for time-series data, ensuring
+    no lookahead bias by only using past data for training.
+    
+    Attributes:
+        window_type: Type of window (expanding or rolling)
+        train_size: Initial training window size
+        test_size: Test window size
+        step_size: Step size for moving forward
+        min_train_size: Minimum training window size
+    
+    Examples:
+        >>> wfo = WalkForwardOptimizer(
+        >>>     window_type=WindowType.EXPANDING,
+        >>>     train_size=252,
+        >>>     test_size=21
+        >>> )
+        >>> for train_idx, test_idx in wfo.split(data, n_splits=5):
+        >>>     train_data = data[train_idx]
+        >>>     test_data = data[test_idx]
+    """
+    
+    def __init__(
+        self,
+        window_type: WindowType = WindowType.EXPANDING,
+        train_size: int = 252,
+        test_size: int = 21,
+        step_size: Optional[int] = None,
+        min_train_size: Optional[int] = None
+    ):
+        """
+        Initialize walk-forward optimizer.
+        
+        Args:
+            window_type: Type of window (expanding or rolling)
+            train_size: Initial training window size (in samples)
+            test_size: Test window size (in samples)
+            step_size: Step size for moving forward (default: test_size)
+            min_train_size: Minimum training window size (default: train_size)
+        """
+        self.window_type = window_type
+        self.train_size = train_size
+        self.test_size = test_size
+        self.step_size = step_size if step_size is not None else test_size
+        self.min_train_size = min_train_size if min_train_size is not None else train_size
+    
+    def split(self, data_length: int, n_splits: Optional[int] = None) -> List[Tuple[slice, slice]]:
+        """
+        Generate train/test splits.
+        
+        Args:
+            data_length: Total length of data
+            n_splits: Number of splits to generate (None for all possible)
+        
+        Returns:
+            List of (train_slice, test_slice) tuples
+        """
+        splits = []
+        start_idx = self.train_size
+        
+        split_count = 0
+        while start_idx + self.test_size <= data_length:
+            # Training window
+            if self.window_type == WindowType.EXPANDING:
+                train_start = 0
+                train_end = start_idx
+            else:  # ROLLING
+                train_start = start_idx - self.train_size
+                train_end = start_idx
+            
+            # Test window
+            test_start = start_idx
+            test_end = min(start_idx + self.test_size, data_length)
+            
+            # Ensure minimum training size
+            if train_end - train_start >= self.min_train_size:
+                train_slice = slice(train_start, train_end)
+                test_slice = slice(test_start, test_end)
+                splits.append((train_slice, test_slice))
+                
+                split_count += 1
+                if n_splits is not None and split_count >= n_splits:
+                    break
+            
+            # Move forward
+            start_idx += self.step_size
+        
+        return splits
+    
+    def get_splits(self, data_length: int, n_splits: Optional[int] = None) -> List[Tuple[List[int], List[int]]]:
+        """
+        Get train/test indices as lists.
+        
+        Args:
+            data_length: Total length of data
+            n_splits: Number of splits to generate
+        
+        Returns:
+            List of (train_indices, test_indices) tuples
+        """
+        splits = self.split(data_length, n_splits)
+        return [
+            (list(range(s[0].start, s[0].stop)), list(range(s[1].start, s[1].stop)))
+            for s in splits
+        ]
+
+
+def walk_forward_validation(
+    model: Any,
+    X: List,
+    y: List,
+    train_fn: Callable,
+    eval_fn: Callable,
+    window_type: WindowType = WindowType.EXPANDING,
+    train_size: int = 252,
+    test_size: int = 21,
+    n_splits: Optional[int] = None
+) -> List[dict]:
+    """
+    Perform walk-forward validation on a model.
+    
+    Args:
+        model: Model to train and evaluate
+        X: Feature data
+        y: Target data
+        train_fn: Function to train model: train_fn(model, X_train, y_train) -> trained_model
+        eval_fn: Function to evaluate: eval_fn(model, X_test, y_test) -> metrics_dict
+        window_type: Type of window
+        train_size: Initial training window size
+        test_size: Test window size
+        n_splits: Number of splits
+    
+    Returns:
+        List of evaluation metrics for each split
+    """
+    if len(X) != len(y):
+        raise ValueError("X and y must have same length")
+    
+    wfo = WalkForwardOptimizer(
+        window_type=window_type,
+        train_size=train_size,
+        test_size=test_size
+    )
+    
+    results = []
+    splits = wfo.get_splits(len(X), n_splits)
+    
+    for train_idx, test_idx in splits:
+        # Get train/test data
+        X_train = [X[i] for i in train_idx]
+        y_train = [y[i] for i in train_idx]
+        X_test = [X[i] for i in test_idx]
+        y_test = [y[i] for i in test_idx]
+        
+        # Train model
+        trained_model = train_fn(model, X_train, y_train)
+        
+        # Evaluate
+        metrics = eval_fn(trained_model, X_test, y_test)
+        metrics['train_size'] = len(train_idx)
+        metrics['test_size'] = len(test_idx)
+        metrics['train_start'] = train_idx[0]
+        metrics['train_end'] = train_idx[-1]
+        metrics['test_start'] = test_idx[0]
+        metrics['test_end'] = test_idx[-1]
+        
+        results.append(metrics)
+    
+    return results
+

quantml/utils/__init__.py

@@ -0,0 +1,51 @@
+"""
+QuantML Utilities
+
+This module provides utility functions for profiling, gradient checking,
+model serialization, and CPU-optimized operations.
+"""
+
+from quantml.utils.profiling import (
+    timing,
+    measure_latency,
+    measure_latency_microseconds,
+    PerformanceProfiler,
+    benchmark
+)
+
+from quantml.utils.gradient_check import (
+    check_gradients,
+    gradient_check_layer,
+    print_gradient_check_results,
+    quick_gradient_check
+)
+
+from quantml.utils.serialization import (
+    save_model,
+    load_model,
+    save_checkpoint,
+    load_checkpoint,
+    get_model_state_dict,
+    set_model_state_dict
+)
+
+__all__ = [
+    # Profiling
+    'timing',
+    'measure_latency',
+    'measure_latency_microseconds',
+    'PerformanceProfiler',
+    'benchmark',
+    # Gradient checking
+    'check_gradients',
+    'gradient_check_layer',
+    'print_gradient_check_results',
+    'quick_gradient_check',
+    # Serialization
+    'save_model',
+    'load_model',
+    'save_checkpoint',
+    'load_checkpoint',
+    'get_model_state_dict',
+    'set_model_state_dict',
+]

quantml/utils/gradient_check.py

@@ -0,0 +1,274 @@
+"""
+Gradient checking utilities for verifying autograd correctness.
+
+This module provides numerical gradient checking to verify that the
+analytical gradients computed by the autograd engine are correct.
+"""
+
+from typing import Callable, List, Tuple, Optional, Union
+from quantml.tensor import Tensor
+
+
+def check_gradients(
+    func: Callable[[Tensor], Tensor],
+    inputs: Tensor,
+    eps: float = 1e-5,
+    rtol: float = 1e-3,
+    atol: float = 1e-5
+) -> Tuple[bool, List[dict]]:
+    """
+    Compare analytical gradients to numerical gradients.
+    
+    Uses finite differences to compute numerical gradients and compares
+    them to the analytical gradients from backpropagation.
+    
+    Args:
+        func: Function that takes a tensor and returns a scalar tensor
+        inputs: Input tensor to compute gradients for
+        eps: Small value for finite differences (default: 1e-5)
+        rtol: Relative tolerance for comparison (default: 1e-3)
+        atol: Absolute tolerance for comparison (default: 1e-5)
+    
+    Returns:
+        Tuple of (passed, details) where:
+        - passed: True if all gradients match within tolerance
+        - details: List of dicts with 'index', 'numerical', 'analytical', 'diff'
+    
+    Examples:
+        >>> def f(x):
+        ...     return ops.sum(ops.mul(x, x))  # sum(x^2)
+        >>> x = Tensor([[1.0, 2.0, 3.0]], requires_grad=True)
+        >>> passed, details = check_gradients(f, x)
+        >>> print(passed)  # True
+        >>> # Analytical gradient should be 2*x = [2.0, 4.0, 6.0]
+    """
+    # Create a copy with requires_grad=True
+    x = Tensor(inputs.data, requires_grad=True)
+    
+    # Forward pass
+    y = func(x)
+    
+    # Backward pass to get analytical gradients
+    y.backward()
+    analytical_grad = x.grad
+    
+    # Get flattened data
+    if isinstance(x.data[0], list):
+        flat_data = [val for row in x.data for val in row]
+        shape_2d = True
+        rows = len(x.data)
+        cols = len(x.data[0])
+    else:
+        flat_data = list(x.data)
+        shape_2d = False
+        rows = 1
+        cols = len(x.data)
+    
+    # Flatten analytical gradient
+    if analytical_grad is not None:
+        if isinstance(analytical_grad, list):
+            if analytical_grad and isinstance(analytical_grad[0], list):
+                flat_analytical = [val for row in analytical_grad for val in row]
+            else:
+                flat_analytical = list(analytical_grad)
+        else:
+            # NumPy array
+            flat_analytical = analytical_grad.flatten().tolist()
+    else:
+        flat_analytical = [0.0] * len(flat_data)
+    
+    # Compute numerical gradients using central differences
+    numerical_grads = []
+    details = []
+    all_passed = True
+    
+    for i in range(len(flat_data)):
+        # Perturb positively
+        data_plus = flat_data.copy()
+        data_plus[i] += eps
+        
+        # Reshape to original shape
+        if shape_2d:
+            reshaped_plus = [data_plus[r*cols:(r+1)*cols] for r in range(rows)]
+        else:
+            reshaped_plus = data_plus
+        
+        x_plus = Tensor(reshaped_plus, requires_grad=False)
+        y_plus = func(x_plus)
+        
+        # Extract scalar value
+        y_plus_val = _get_scalar(y_plus)
+        
+        # Perturb negatively
+        data_minus = flat_data.copy()
+        data_minus[i] -= eps
+        
+        if shape_2d:
+            reshaped_minus = [data_minus[r*cols:(r+1)*cols] for r in range(rows)]
+        else:
+            reshaped_minus = data_minus
+        
+        x_minus = Tensor(reshaped_minus, requires_grad=False)
+        y_minus = func(x_minus)
+        y_minus_val = _get_scalar(y_minus)
+        
+        # Central difference
+        numerical = (y_plus_val - y_minus_val) / (2 * eps)
+        numerical_grads.append(numerical)
+        
+        # Get analytical gradient for this index
+        analytical = float(flat_analytical[i]) if i < len(flat_analytical) else 0.0
+        
+        # Compare
+        diff = abs(numerical - analytical)
+        rel_diff = diff / (abs(analytical) + atol) if abs(analytical) > atol else diff
+        
+        passed = diff <= atol or rel_diff <= rtol
+        if not passed:
+            all_passed = False
+        
+        # Compute 2D index if applicable
+        if shape_2d:
+            idx_tuple = (i // cols, i % cols)
+        else:
+            idx_tuple = (i,)
+        
+        details.append({
+            'index': idx_tuple,
+            'numerical': numerical,
+            'analytical': analytical,
+            'diff': diff,
+            'rel_diff': rel_diff,
+            'passed': passed
+        })
+    
+    return all_passed, details
+
+
+def _get_scalar(t: Tensor) -> float:
+    """Extract scalar value from tensor."""
+    data = t.data
+    if isinstance(data, list):
+        if len(data) == 0:
+            return 0.0
+        if isinstance(data[0], list):
+            return float(data[0][0])
+        return float(data[0])
+    # NumPy array or scalar
+    try:
+        return float(data.flat[0])
+    except (AttributeError, TypeError):
+        return float(data)
+
+
+def gradient_check_layer(
+    layer,
+    input_tensor: Tensor,
+    eps: float = 1e-5,
+    rtol: float = 1e-3,
+    atol: float = 1e-5
+) -> Tuple[bool, dict]:
+    """
+    Check gradients for a layer's parameters.
+    
+    Verifies that the gradients w.r.t. the layer's weights and biases
+    are correctly computed.
+    
+    Args:
+        layer: A layer with forward() method and parameters() method
+        input_tensor: Input to pass through the layer
+        eps: Small value for finite differences
+        rtol: Relative tolerance
+        atol: Absolute tolerance
+    
+    Returns:
+        Tuple of (passed, results) where results contains gradient check
+        details for each parameter.
+    
+    Examples:
+        >>> from quantml.models import Linear
+        >>> from quantml import ops
+        >>> layer = Linear(3, 2)
+        >>> x = Tensor([[1.0, 2.0, 3.0]])
+        >>> passed, results = gradient_check_layer(layer, x)
+    """
+    from quantml import ops
+    
+    results = {}
+    all_passed = True
+    
+    # Get parameters
+    params = layer.parameters()
+    
+    for param_idx, param in enumerate(params):
+        param_name = f"param_{param_idx}"
+        
+        # Define function that uses this parameter
+        def func_for_param(p):
+            # Temporarily replace parameter data
+            old_data = param.data
+            param._data = p.data if hasattr(p, 'data') else p
+            if hasattr(param, '_np_array'):
+                param._np_array = None  # Clear cached numpy
+            
+            # Forward pass
+            out = layer.forward(input_tensor)
+            
+            # Sum to get scalar
+            scalar_out = ops.sum(out)
+            
+            # Restore
+            param._data = old_data
+            
+            return scalar_out
+        
+        # Check gradients for this parameter
+        passed, details = check_gradients(func_for_param, param, eps, rtol, atol)
+        
+        if not passed:
+            all_passed = False
+        
+        results[param_name] = {
+            'passed': passed,
+            'details': details
+        }
+    
+    return all_passed, results
+
+
+def print_gradient_check_results(passed: bool, details: List[dict]) -> None:
+    """
+    Print formatted gradient check results.
+    
+    Args:
+        passed: Overall pass/fail status
+        details: List of detail dicts from check_gradients
+    """
+    print("=" * 60)
+    print("GRADIENT CHECK RESULTS")
+    print("=" * 60)
+    print(f"Overall: {'PASSED ✓' if passed else 'FAILED ✗'}")
+    print("-" * 60)
+    print(f"{'Index':<15} {'Numerical':<15} {'Analytical':<15} {'Diff':<12} {'Status':<8}")
+    print("-" * 60)
+    
+    for d in details:
+        status = "✓" if d['passed'] else "✗"
+        print(f"{str(d['index']):<15} {d['numerical']:<15.6f} {d['analytical']:<15.6f} {d['diff']:<12.2e} {status:<8}")
+    
+    print("=" * 60)
+
+
+def quick_gradient_check(func: Callable, inputs: Tensor) -> bool:
+    """
+    Quick gradient check that returns True if gradients are correct.
+    
+    Args:
+        func: Function to check
+        inputs: Input tensor
+    
+    Returns:
+        True if gradients pass, False otherwise
+    """
+    passed, _ = check_gradients(func, inputs)
+    return passed

quantml/utils/logging.py

@@ -0,0 +1,181 @@
+"""
+Centralized logging system for QuantML.
+
+Provides structured logging with file rotation and experiment tracking.
+"""
+
+import logging
+import sys
+import os
+from logging.handlers import RotatingFileHandler
+from typing import Optional, Dict, Any
+from datetime import datetime
+import json
+
+
+def setup_logger(
+    name: str = "quantml",
+    log_level: str = "INFO",
+    log_dir: Optional[str] = None,
+    log_file: Optional[str] = None,
+    console_output: bool = True
+) -> logging.Logger:
+    """
+    Set up a logger with file and console handlers.
+    
+    Args:
+        name: Logger name
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_dir: Directory for log files (default: ./logs)
+        log_file: Log file name (default: quantml_YYYYMMDD.log)
+        console_output: Whether to output to console
+    
+    Returns:
+        Configured logger
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(getattr(logging, log_level.upper()))
+    
+    # Remove existing handlers
+    logger.handlers.clear()
+    
+    # Create formatters
+    detailed_formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    simple_formatter = logging.Formatter(
+        '%(asctime)s - %(levelname)s - %(message)s',
+        datefmt='%H:%M:%S'
+    )
+    
+    # Console handler
+    if console_output:
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setLevel(logging.INFO)
+        console_handler.setFormatter(simple_formatter)
+        logger.addHandler(console_handler)
+    
+    # File handler with rotation
+    if log_dir is None:
+        log_dir = "./logs"
+    
+    os.makedirs(log_dir, exist_ok=True)
+    
+    if log_file is None:
+        log_file = f"quantml_{datetime.now().strftime('%Y%m%d')}.log"
+    
+    log_path = os.path.join(log_dir, log_file)
+    
+    file_handler = RotatingFileHandler(
+        log_path,
+        maxBytes=10 * 1024 * 1024,  # 10MB
+        backupCount=5
+    )
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(detailed_formatter)
+    logger.addHandler(file_handler)
+    
+    return logger
+
+
+def log_experiment_start(
+    logger: logging.Logger,
+    config: Dict[str, Any],
+    experiment_id: Optional[str] = None
+):
+    """
+    Log experiment start with metadata.
+    
+    Args:
+        logger: Logger instance
+        config: Experiment configuration dictionary
+        experiment_id: Optional experiment ID
+    """
+    logger.info("=" * 70)
+    logger.info("EXPERIMENT START")
+    logger.info("=" * 70)
+    
+    if experiment_id:
+        logger.info(f"Experiment ID: {experiment_id}")
+    
+    logger.info(f"Timestamp: {datetime.now().isoformat()}")
+    logger.info(f"Configuration: {json.dumps(config, indent=2)}")
+    
+    # Try to get git hash if available
+    try:
+        import subprocess
+        git_hash = subprocess.check_output(
+            ['git', 'rev-parse', 'HEAD'],
+            stderr=subprocess.DEVNULL
+        ).decode().strip()
+        logger.info(f"Git commit: {git_hash}")
+    except Exception:
+        pass
+    
+    logger.info("=" * 70)
+
+
+def log_experiment_end(
+    logger: logging.Logger,
+    metrics: Dict[str, Any],
+    experiment_id: Optional[str] = None
+):
+    """
+    Log experiment end with results.
+    
+    Args:
+        logger: Logger instance
+        metrics: Experiment metrics dictionary
+        experiment_id: Optional experiment ID
+    """
+    logger.info("=" * 70)
+    logger.info("EXPERIMENT END")
+    logger.info("=" * 70)
+    
+    if experiment_id:
+        logger.info(f"Experiment ID: {experiment_id}")
+    
+    logger.info(f"Timestamp: {datetime.now().isoformat()}")
+    logger.info(f"Metrics: {json.dumps(metrics, indent=2)}")
+    logger.info("=" * 70)
+
+
+def log_training_progress(
+    logger: logging.Logger,
+    epoch: int,
+    train_loss: float,
+    val_loss: Optional[float] = None,
+    metrics: Optional[Dict[str, float]] = None
+):
+    """
+    Log training progress.
+    
+    Args:
+        logger: Logger instance
+        epoch: Current epoch
+        train_loss: Training loss
+        val_loss: Validation loss (optional)
+        metrics: Additional metrics (optional)
+    """
+    msg = f"Epoch {epoch}: Train Loss = {train_loss:.6f}"
+    if val_loss is not None:
+        msg += f", Val Loss = {val_loss:.6f}"
+    if metrics:
+        metric_str = ", ".join([f"{k} = {v:.4f}" for k, v in metrics.items()])
+        msg += f", {metric_str}"
+    logger.info(msg)
+
+
+def get_logger(name: str = "quantml") -> logging.Logger:
+    """
+    Get or create a logger instance.
+    
+    Args:
+        name: Logger name
+    
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)
+