# TurboVec Dimension Constraints: Multiple of 8 and Maximum 65536

> Discover TurboVec dimension constraints: learn why dimensions must be multiples of 8 and capped at 65536 to prevent errors with RyanCodrai/turbovec.

- Repository: [Ryan Codrai/turbovec](https://github.com/RyanCodrai/turbovec)
- Tags: internals
- Published: 2026-06-16

---

**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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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)

```python
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

```python
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

```python
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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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`](https://github.com/RyanCodrai/turbovec/blob/main/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.