Module ternary_vec 

Packed ternary vector representation.

This module implements the bitsliced balanced ternary representation that serves as the internal substrate for fast dot/bind/bundle operations.

Bitsliced Design

See docs/BITSLICED_TERNARY_DESIGN.md for comprehensive documentation.

Representation: 2 bits per dimension

• 00 = Z (0)
• 01 = P (+1)
• 10 = N (-1)
• 11 = unused (treated as Z)

Key Features

• Word-level parallelism: 32 trits per u64 word
• Bitplane separation: Even bits (P plane), odd bits (N plane)
• SIMD-friendly: Branchless operations, vectorization-ready
• GPU-ready: Coalesced memory access, no divergence

Performance

• Dot product: 32 trits per word operation
• Bind: Pure bitwise operations (AND, OR, shift)
• Bundle: Saturating addition via bitwise logic
• Memory: 2 bits per trit (optimal for ternary encoding)

When to Use

Use PackedTritVec when:

• Vector density ≥ 25%
• Performing bulk operations (dot, bind, bundle)
• SIMD/GPU acceleration is needed
• Throughput over latency

Use SparseVec when:

• Vector density < 25%
• Random access patterns
• Incremental construction
• Memory is constrained

Future Enhancements

• Explicit SIMD (AVX2, AVX-512, NEON) - Phase 2
• GPU acceleration (CUDA, OpenCL) - Phase 5
• See IMPLEMENTATION_PLAN.md for roadmap

Structs

PackedTritVec