TurboVec Dimension Constraints: Multiple of 8 and Maximum 65536

TurboVec requires all vector dimensions to be multiples of 8 and enforces a hard ceiling of 65,536 dimensions, raising a ValueError immediately if either limit is violated during index creation or file loading.

TurboVec is a high-performance quantized vector store developed in the RyanCodrai/turbovec repository. To ensure SIMD alignment and prevent runaway memory allocation, the library implements strict dimension constraints for turbovec that are validated at both initialization and persistence layers before any index data is allocated.

Why TurboVec Enforces Dimension Constraints

TurboVec’s quantization engine relies on fixed-width SIMD operations that require memory-aligned vector dimensions. By restricting dimensions to multiples of 8, the library guarantees that vector data can be processed in uniform 64-bit (8-byte) chunks without padding overhead. Simultaneously, the 65,536 dimension cap (defined as MAX_DIM = 65536) protects against accidental out-of-memory errors when loading large indexes.

The Two Hard Limits

Multiple of 8 Requirement

The dimensionality (dim) must be divisible by 8. According to the test suite in turbovec-python/tests/test_security.py, the parametrized test test_load_rejects_non_multiple_of_8_dim explicitly validates this constraint by rejecting values such as 12, 7, and 100. Attempting to initialize a store with a non-compliant dimension triggers an immediate validation error.

Maximum Dimension Cap (65536)

To prevent enormous memory allocations, TurboVec caps dim at MAX_DIM = 65536. The test test_load_rejects_oversized_dim in turbovec-python/tests/test_security.py (lines 101–106) documents this ceiling, ensuring any dimension larger than 65,536 is rejected during the loading process.

Where Constraints Are Enforced in the Source Code

Dimension validation is distributed across the Python bindings and test infrastructure:

• turbovec-python/tests/test_security.py – Contains the primary validation logic. The tests test_load_rejects_non_multiple_of_8_dim and test_load_rejects_oversized_dim define the acceptable range and assert that ValueError is raised for non-compliant inputs.
• turbovec-python/python/turbovec/_persist.py – Part of the consistency-checking pipeline for persisted indexes; relies on valid dimensions being established before serialization.
• turbovec-python/python/turbovec/_dedup.py – Deduplication logic expects vectors to satisfy the dimension constraints before processing.

Practical Code Examples

Loading a Valid Index (dim = 128)

from turbovec import TurboQuantVectorStore

# Assuming "vectors.tvim" was created with dim=128, bit_width=4

store = TurboQuantVectorStore.from_file("vectors.tvim")
print(store._index.dim)    # → 128

Invalid Dimension: Not a Multiple of 8

from turbovec import TurboQuantVectorStore
import pytest

# This raises ValueError because 30 is not divisible by 8

with pytest.raises(ValueError):
    TurboQuantVectorStore.from_params(dim=30, bit_width=4)

Invalid Dimension: Exceeds Maximum Size

from turbovec import TurboQuantVectorStore

# This raises ValueError because 70000 > 65536

TurboQuantVectorStore.from_params(dim=70000, bit_width=4)

# → ValueError: dim > MAX_DIM (65536)

Summary

• TurboVec dimension constraints require dim to be a multiple of 8 and less than or equal to 65,536.
• Violations are caught by test_load_rejects_non_multiple_of_8_dim and test_load_rejects_oversized_dim in turbovec-python/tests/test_security.py, raising ValueError before memory allocation.
• The MAX_DIM = 65536 constant prevents excessive resource consumption.
• Validation occurs at both index creation (from_params) and file loading (from_file) entry points.

Frequently Asked Questions

What happens if I try to use a dimension that is not a multiple of 8?

TurboVec raises a ValueError immediately upon initialization. The validation logic in turbovec-python/tests/test_security.py explicitly rejects dimensions like 12, 7, or 100, ensuring only multiples of 8 are accepted.

Is 65,536 the absolute maximum dimension for TurboVec?

Yes. As defined by MAX_DIM = 65536 in the source code, any dimension exceeding this value triggers test_load_rejects_oversized_dim to fail, protecting the system from massive memory allocations.

Can I bypass these dimension constraints by modifying the source files?

No. The constraints are hardcoded in the validation layer and enforced by the underlying C++ quantization engine. Even if you modified turbovec-python/python/turbovec/_persist.py, the core library would reject non-compliant dimensions during the actual vector processing.

Where can I find the validation tests for these constraints?

The primary validation tests are located in turbovec-python/tests/test_security.py. Look for test_load_rejects_non_multiple_of_8_dim (lines 54–57) and test_load_rejects_oversized_dim (lines 101–106) to see the exact assertion logic and boundary values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}