aprender-serve 0.64.0

/// PARITY-071c: Q8_0Block::dequantize() function
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity071c_dequantize_function() {
    use crate::quantize::Q8_0Block;

    println!("PARITY-071c: Q8_0Block::dequantize() Function");
    println!("==============================================");
    println!();
    println!("  ALGORITHM:");
    println!("    values[i] = quants[i] * scale");
    println!();

    // Create a known block
    let block = Q8_0Block {
        scale: 0.01,
        quants: [100i8; 32],
    };

    let values = block.dequantize();

    println!("  TEST: scale=0.01, quants=[100; 32]");
    println!("    Expected: values[i] = 100 * 0.01 = 1.0");
    println!("    Actual values[0]: {}", values[0]);

    assert!(
        (values[0] - 1.0).abs() < 1e-6,
        "PARITY-071c: Dequant correct"
    );
    assert_eq!(values.len(), 32, "PARITY-071c: 32 values returned");

    // Test round-trip
    let original = [0.5f32; 32];
    let quantized = Q8_0Block::quantize(&original);
    let recovered = quantized.dequantize();

    println!();
    println!("  ROUND-TRIP TEST: original=[0.5; 32]");
    println!("    Quantized scale: {:.6}", quantized.scale);
    println!("    Quantized quants[0]: {}", quantized.quants[0]);
    println!("    Recovered values[0]: {:.6}", recovered[0]);

    let error = (recovered[0] - original[0]).abs();
    println!("    Round-trip error: {:.6}", error);

    assert!(error < 0.01, "PARITY-071c: Round-trip error < 1%");
    println!();
    println!("  ✅ Q8_0Block::dequantize() verified");
}

/// PARITY-071d: Quantization error analysis
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity071d_error_analysis() {
    use crate::quantize::Q8_0Block;

    println!("PARITY-071d: Quantization Error Analysis");
    println!("=========================================");
    println!();

    // Test various value ranges
    let test_cases: [(f32, &str); 5] = [
        (1.0, "unit values"),
        (0.1, "small values"),
        (100.0, "large values"),
        (0.001, "tiny values"),
        (1000.0, "huge values"),
    ];

    println!("  ERROR ANALYSIS BY VALUE RANGE:");
    println!("    | Range        | Max Error | Rel Error |");
    println!("    |--------------|-----------|-----------|");

    for (scale, name) in test_cases {
        let values: [f32; 32] = core::array::from_fn(|i| scale * ((i as f32) / 31.0 * 2.0 - 1.0));

        let block = Q8_0Block::quantize(&values);
        let abs_error = block.quantization_error(&values);
        let rel_error = block.relative_error(&values);

        println!(
            "    | {:12} | {:.6} | {:.4}% |",
            name,
            abs_error,
            rel_error * 100.0
        );

        assert!(rel_error < 0.01, "PARITY-071d: Relative error < 1%");
    }

    println!();
    println!("  KEY FINDING: Q8_0 relative error < 1% for all ranges");
    println!("  This is acceptable for inference (not training)");
    println!();
    println!("  ✅ Quantization error analysis verified");
}

/// PARITY-071e: quantize_to_q8_blocks() function
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity071e_batch_quantization() {
    use crate::quantize::{dequantize_q8_blocks, quantize_to_q8_blocks};

    println!("PARITY-071e: quantize_to_q8_blocks() Function");
    println!("==============================================");
    println!();

    // Test with 3 blocks (96 values)
    let values: Vec<f32> = (0..96).map(|i| (i as f32 - 48.0) / 10.0).collect();

    let blocks = quantize_to_q8_blocks(&values).expect("quantization should succeed");

    println!("  INPUT: 96 f32 values");
    println!("  OUTPUT: {} Q8_0 blocks", blocks.len());

    assert_eq!(blocks.len(), 3, "PARITY-071e: 3 blocks created");

    // Test error on non-multiple of 32
    let bad_values = vec![1.0f32; 33];
    let result = quantize_to_q8_blocks(&bad_values);

    println!();
    println!("  ERROR TEST: 33 values (not multiple of 32)");
    assert!(result.is_err(), "PARITY-071e: Error on invalid length");
    println!("    ✅ Error correctly returned");

    // Test round-trip
    let recovered = dequantize_q8_blocks(&blocks);

    println!();
    println!("  ROUND-TRIP TEST:");
    println!("    Original length: {}", values.len());
    println!("    Recovered length: {}", recovered.len());

    let max_error: f32 = values
        .iter()
        .zip(recovered.iter())
        .map(|(a, b)| (a - b).abs())
        .fold(0.0f32, f32::max);

    println!("    Max round-trip error: {:.6}", max_error);

    assert!(max_error < 0.1, "PARITY-071e: Round-trip error reasonable");
    println!();
    println!("  ✅ quantize_to_q8_blocks() verified");
}

/// PARITY-071f: Integration summary
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity071f_integration_summary() {
    use crate::quantize::Q8_0Block;

    println!("PARITY-071f: Q8Block Integration Summary");
    println!("=========================================");
    println!();
    println!("  ╔═══════════════════════════════════════════════════════════╗");
    println!("  ║  PARITY-071: Q8Block Implementation - COMPLETE ✓         ║");
    println!("  ╚═══════════════════════════════════════════════════════════╝");
    println!();
    println!("  IMPLEMENTED:");
    println!("    ✅ Q8_0Block struct (scale: f32, quants: [i8; 32])");
    println!("    ✅ Q8_0Block::quantize(&[f32; 32]) -> Self");
    println!("    ✅ Q8_0Block::dequantize(&self) -> [f32; 32]");
    println!("    ✅ Q8_0Block::quantization_error()");
    println!("    ✅ Q8_0Block::relative_error()");
    println!("    ✅ quantize_to_q8_blocks(&[f32]) -> Vec<Q8_0Block>");
    println!("    ✅ dequantize_q8_blocks(&[Q8_0Block]) -> Vec<f32>");
    println!();
    println!("  PERFORMANCE CHARACTERISTICS:");
    println!("    - Storage: 36 bytes per 32 values (9 bits/value)");
    println!("    - Relative error: < 1%");
    println!("    - Suitable for dynamic activation quantization");
    println!();
    println!("  USE CASE:");
    println!("    ┌─────────────────────────────────────────────────────┐");
    println!("    │ 1. Compute F32 activations (forward pass)          │");
    println!("    │ 2. Q8_0Block::quantize(activations)                │");
    println!("    │ 3. fused_q4k_q8_dot(weights, q8_activations)       │");
    println!("    │ 4. Result: INT8 operations, 7x memory savings      │");
    println!("    └─────────────────────────────────────────────────────┘");
    println!();
    println!("  NEXT: PARITY-072 - Fused Q4xQ8 CPU kernel");

    // Verify the implementation exists
    let test_values = [1.0f32; 32];
    let block = Q8_0Block::quantize(&test_values);
    let recovered = block.dequantize();
    let error = block.relative_error(&test_values);

    assert!(error < 0.01, "PARITY-071f: Implementation working");
    assert!(
        (recovered[0] - test_values[0]).abs() < 0.01,
        "PARITY-071f: Round-trip works"
    );

    println!("  ✅ PARITY-071 Complete");
}

// ==================== PARITY-072: Fused Q4xQ8 CPU Kernel ====================
// Core optimization: Q4_K weights × Q8_0 activations without F32 intermediate
// Memory traffic reduction: ~25x theoretical (7.1x Q4K + 3.6x Q8)

/// PARITY-072a: Fused kernel signature and purpose
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity072a_kernel_signature() {
    println!("PARITY-072a: Fused Q4xQ8 Kernel Signature");
    println!("==========================================");
    println!();
    println!("  FUNCTION:");
    println!("    ┌─────────────────────────────────────────────────────┐");
    println!("    │ pub fn fused_q4k_q8_dot(                            │");
    println!("    │     q4k_data: &[u8],        // Q4_K raw bytes       │");
    println!("    │     q8_blocks: &[Q8_0Block] // Q8_0 activations     │");
    println!("    │ ) -> Result<f32>            // Dot product result   │");
    println!("    └─────────────────────────────────────────────────────┘");
    println!();
    println!("  PURPOSE:");
    println!("    Instead of:");
    println!("      1. Dequantize Q4_K → F32 weights (7.1x memory)");
    println!("      2. F32 activations (baseline)");
    println!("      3. dot(F32, F32)");
    println!();
    println!("    We do:");
    println!("      1. Read Q4_K directly (4.5 bits/weight)");
    println!("      2. Read Q8_0 activations (9 bits/value)");
    println!("      3. Fused dequant + dot in registers");
    println!();
    println!("  MEMORY SAVINGS:");
    println!("    | Operand     | Before    | After     | Savings |");
    println!("    |-------------|-----------|-----------|---------|");
    println!("    | Weights     | 32 bits   | 4.5 bits  | 7.1x    |");
    println!("    | Activations | 32 bits   | 9 bits    | 3.6x    |");
    println!("    | Combined    | 64 bits   | 13.5 bits | ~4.7x   |");

    assert!(true, "PARITY-072a: Kernel signature documented");
}

/// PARITY-072b: Verify fused kernel correctness
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity072b_correctness() {
    use crate::quantize::{fused_q4k_dot, fused_q4k_q8_dot, quantize_to_q8_blocks};

    println!("PARITY-072b: Fused Kernel Correctness");
    println!("=====================================");
    println!();

    // Create test Q4_K data (1 super-block = 256 values)
    // Q4_K format: 2 (d) + 2 (dmin) + 12 (scales) + 128 (qs) = 144 bytes
    let mut q4k_data = vec![0u8; 144];

    // Set d = 1.0 (f16: 0x3C00)
    q4k_data[0] = 0x00;
    q4k_data[1] = 0x3C;

    // Set dmin = 0.0 (f16: 0x0000)
    q4k_data[2] = 0x00;
    q4k_data[3] = 0x00;

    // Set scales to encode scale=1, min=0 for all 8 blocks
    // 6-bit scale values packed into 12 bytes
    for i in 0..12 {
        q4k_data[4 + i] = 0x41; // Encodes scale=1, min=0
    }

    // Set qs: all values = 8 (after dequant: d * scale * 8 - dmin * min = 8)
    for i in 0..128 {
        q4k_data[16 + i] = 0x88; // Low nibble = 8, high nibble = 8
    }

    // Create F32 activations (all 1.0)
    let f32_activations = vec![1.0f32; 256];

    // Compute reference with fused_q4k_dot (F32 activations)
    let reference = fused_q4k_dot(&q4k_data, &f32_activations).expect("fused_q4k_dot failed");

    // Quantize activations to Q8
    let q8_blocks = quantize_to_q8_blocks(&f32_activations).expect("quantize_to_q8_blocks failed");

    // Compute with fused_q4k_q8_dot
    let result = fused_q4k_q8_dot(&q4k_data, &q8_blocks).expect("fused_q4k_q8_dot failed");

    println!("  COMPARISON:");
    println!("    Reference (F32 activations): {:.6}", reference);
    println!("    Fused Q4xQ8 result:          {:.6}", result);

    let relative_error = if reference.abs() > 1e-6 {
        (result - reference).abs() / reference.abs()
    } else {
        (result - reference).abs()
    };

    println!(
        "    Relative error:              {:.4}%",
        relative_error * 100.0
    );

    // Allow up to 2% error due to Q8 quantization of activations
    assert!(
        relative_error < 0.02,
        "PARITY-072b: Fused kernel within 2% of reference"
    );

    println!();
    println!("  ✅ Fused Q4xQ8 kernel matches reference within 2%");
}

/// PARITY-072c: Memory traffic analysis
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity072c_memory_analysis() {
    println!("PARITY-072c: Memory Traffic Analysis");
    println!("====================================");
    println!();

    // Analysis for 256-value dot product (1 Q4_K super-block)
    let values = 256;

    // Traditional approach: dequant then dot
    let f32_weights = values * 4; // 32 bits each
    let f32_activations_trad = values * 4; // 32 bits each
    let traditional_bytes = f32_weights + f32_activations_trad;

    // Fused Q4_K × F32: weights quantized, activations F32
    let q4k_bytes = 144; // 1 super-block
    let f32_activations_fused = values * 4;
    let fused_q4k_f32_bytes = q4k_bytes + f32_activations_fused;

    // Fused Q4_K × Q8: both quantized
    let q8_bytes = (values / 32) * 36; // 8 Q8 blocks × 36 bytes
    let fused_q4k_q8_bytes = q4k_bytes + q8_bytes;

    println!("  MEMORY TRAFFIC FOR {} VALUES:", values);
    println!("    | Approach        | Weights | Activations | Total   |");
    println!("    |-----------------|---------|-------------|---------|");
    println!(
        "    | Traditional     | {} B   | {} B       | {} B  |",
        f32_weights, f32_activations_trad, traditional_bytes
    );
    println!(
        "    | Fused Q4K×F32   | {} B   | {} B       | {} B |",
        q4k_bytes, f32_activations_fused, fused_q4k_f32_bytes
    );
    println!(
        "    | Fused Q4K×Q8    | {} B   | {} B        | {} B   |",
        q4k_bytes, q8_bytes, fused_q4k_q8_bytes
    );
    println!();
    println!("  SAVINGS:");
    println!(
        "    Traditional → Q4K×F32: {:.1}x",
        traditional_bytes as f64 / fused_q4k_f32_bytes as f64
    );
    println!(
        "    Traditional → Q4K×Q8:  {:.1}x",
        traditional_bytes as f64 / fused_q4k_q8_bytes as f64
    );
    println!(
        "    Q4K×F32 → Q4K×Q8:      {:.1}x",
        fused_q4k_f32_bytes as f64 / fused_q4k_q8_bytes as f64
    );

    let savings = traditional_bytes as f64 / fused_q4k_q8_bytes as f64;
    assert!(
        savings > 4.0,
        "PARITY-072c: Q4K×Q8 saves >4x memory traffic"
    );

    println!();
    println!("  ✅ Memory traffic reduction verified");
}

/// PARITY-072d: Validation error handling
#[test]
#[cfg(feature = "gpu")]
#[serial_test::serial]
fn test_parity072d_validation() {
    use crate::quantize::{fused_q4k_q8_dot, Q8_0Block};

    println!("PARITY-072d: Validation Error Handling");
    println!("======================================");
    println!();

    // Test 1: Invalid Q4_K data length
    let bad_q4k = vec![0u8; 100]; // Not multiple of 144
    let q8_blocks = vec![
        Q8_0Block {
            scale: 1.0,
            quants: [0i8; 32]
        };
        8
    ];

    let result = fused_q4k_q8_dot(&bad_q4k, &q8_blocks);
    println!("  TEST 1: Q4_K length not multiple of 144");
    assert!(result.is_err(), "PARITY-072d: Should reject invalid Q4_K");
    println!("    ✅ Error correctly returned");

    // Test 2: Q8 block count mismatch
    let good_q4k = vec![0u8; 144]; // 1 super-block = 256 values
    let wrong_q8_count = vec![
        Q8_0Block {
            scale: 1.0,
            quants: [0i8; 32]
        };
        4
    ]; // Should be 8

    let result = fused_q4k_q8_dot(&good_q4k, &wrong_q8_count);
    println!();
    println!("  TEST 2: Q8 block count mismatch (4 vs 8 expected)");
    assert!(result.is_err(), "PARITY-072d: Should reject wrong Q8 count");
    println!("    ✅ Error correctly returned");

    println!();
    println!("  ✅ Validation error handling verified");
}