API Reference

Quick reference for HoloVec's public API.

VSA Factory

from holovec import VSA

# Create model
model = VSA.create(
    model_name,       # 'FHRR', 'MAP', 'HRR', 'BSC', 'BSDC', 'BSDC_SEG', 'GHRR', 'VTB'
    dim=2048,         # Dimensionality
    backend='numpy',  # 'numpy', 'torch', 'jax'
    device=None,      # 'cpu', 'cuda', 'mps' (PyTorch only)
    seed=None,        # Random seed
    **kwargs          # Model-specific options
)

# Query available backends
info = VSA.backend_info()
# {'numpy': True, 'torch': True, 'jax': False}

---

Model Operations

All models implement:

# Random vector generation
vec = model.random(seed=None)

# Core operations
c = model.bind(a, b)           # Binding
a = model.unbind(c, b)         # Unbinding
d = model.bundle([a, b, c])    # Bundling
e = model.permute(a, k=1)      # Permutation
a = model.unpermute(e, k=1)    # Reverse permutation

# Similarity
sim = model.similarity(a, b)   # Similarity measure (0-1)

# Normalization
v_norm = model.normalize(v)    # Normalize to unit

# Properties
model.dimension                # Vector dimensionality
model.model_name               # Model name string
model.is_self_inverse          # bool
model.is_commutative           # bool
model.is_exact_inverse         # bool

---

Encoders

FractionalPowerEncoder

from holovec.encoders import FractionalPowerEncoder

encoder = FractionalPowerEncoder(
    model,             # VSA model
    min_val=0,         # Minimum input value
    max_val=100,       # Maximum input value
    bandwidth=1.0,     # Resolution control
    base=None          # Base vector (random if None)
)

vec = encoder.encode(value)

ThermometerEncoder

from holovec.encoders import ThermometerEncoder

encoder = ThermometerEncoder(
    model,             # VSA model
    levels=5           # Number of ordinal levels
)

vec = encoder.encode(level)  # level in 1..levels

LevelEncoder

from holovec.encoders import LevelEncoder

encoder = LevelEncoder(
    model,                                    # VSA model
    levels=["cat", "dog", "bird"]            # Category labels
)

vec = encoder.encode("cat")

PositionBindingEncoder

from holovec.encoders import PositionBindingEncoder

encoder = PositionBindingEncoder(
    model,             # VSA model
    max_length=100     # Maximum sequence length
)

vec = encoder.encode([item1, item2, item3])
pos_vec = encoder.get_position_vector(i)

NGramEncoder

from holovec.encoders import NGramEncoder

encoder = NGramEncoder(
    model,             # VSA model
    n=3                # N-gram size
)

vec = encoder.encode([item1, item2, item3, item4])

TrajectoryEncoder

from holovec.encoders import TrajectoryEncoder

encoder = TrajectoryEncoder(
    model,                  # VSA model
    use_permutation=True    # Encoding strategy
)

vec = encoder.encode([point1, point2, point3])

ImageEncoder

from holovec.encoders import ImageEncoder

encoder = ImageEncoder(
    model,             # VSA model
    height=28,         # Image height
    width=28           # Image width
)

vec = encoder.encode(image_array)  # Shape: (height, width)

VectorEncoder

from holovec.encoders import VectorEncoder

encoder = VectorEncoder(
    model,                        # VSA model
    n_dims=3,                     # Feature dimensions
    min_vals=[0, 0, 0],          # Per-dimension minimum
    max_vals=[100, 100, 100]     # Per-dimension maximum
)

vec = encoder.encode([50, 75, 25])

---

Retrieval

Codebook

from holovec.retrieval import Codebook

# Create
cb = Codebook(
    items={"label": vector, ...},
    backend=model.backend
)

# Access
vec = cb["label"]
cb["new_label"] = new_vector
del cb["label"]

# Query
"label" in cb          # Membership
len(cb)                # Size
list(cb)               # Labels
list(cb.values())      # Vectors
list(cb.items())       # (label, vector) pairs

# Persistence
cb.save("file.json")
cb = Codebook.load("file.json", backend=backend)

ItemStore

from holovec.retrieval import ItemStore

store = ItemStore(model)
store.fit(codebook)

# K-nearest neighbors
results = store.query(vec, k=5)
# [(label, similarity), ...]

# Threshold query
results = store.query_threshold(vec, threshold=0.5)

# Batch query
results = store.batch_query([vec1, vec2, ...], k=3)

AssocStore

from holovec.retrieval import AssocStore

store = AssocStore(model)
store.store(key_vec, value_vec)
retrieved = store.retrieve(key_vec)

---

Cleanup

from holovec.utils.cleanup import BruteForceCleanup, ResonatorCleanup

# Brute force
cleanup = BruteForceCleanup(model, threshold=None)
cleaned, label, sim = cleanup.cleanup(noisy_vec, codebook)

# Resonator
cleanup = ResonatorCleanup(
    model,
    iterations=10,
    soft=True,
    convergence_threshold=0.999
)
cleaned, label, sim = cleanup.cleanup(noisy_vec, codebook)

# Factorization (resonator only)
factors = cleanup.factorize(composite_vec, [codebook1, codebook2])

---

Backend Operations

# Access backend
backend = model.backend

# Common operations
backend.zeros(shape, dtype)
backend.ones(shape, dtype)
backend.random(shape)
backend.random_normal(shape)

backend.add(a, b)
backend.multiply(a, b)
backend.dot(a, b)
backend.conjugate(a)

backend.fft(a)
backend.ifft(a)
backend.roll(a, shift, axis=0)

backend.norm(a)
backend.normalize(a)

backend.to_numpy(a)
backend.from_numpy(arr)

# Capabilities
backend.supports_gpu()
backend.supports_complex()
backend.supports_sparse()

---

Model-Specific

FHRR

model = VSA.create('FHRR', dim=2048)

# Fractional power (continuous encoding)
result = model.fractional_power(vec, exponent=2.5)

GHRR

model = VSA.create('GHRR', dim=100, matrix_size=3, diagonality=0.5)

# Test non-commutativity
sim = model.test_non_commutativity(a, b)

# Compute diagonality
diag = model.compute_diagonality(vec)

BSDC

model = VSA.create('BSDC', dim=10000, sparsity=0.01)

# Measure actual sparsity
actual = model.measure_sparsity(vec)

# Restore target sparsity
vec_rehashed = model.rehash(vec)

BSDC-SEG

model = VSA.create('BSDC_SEG', dim=10000, segments=100)

model.segments         # Number of segments
model.segment_length   # Length per segment

BSC

model = VSA.create('BSC', dim=10000)

# Convert representations
bipolar = model.to_bipolar(binary_vec)
binary = model.from_bipolar(bipolar_vec)

---

See Also

• Quick Start — Getting started
• Models — Model comparison
• Encoders Overview — Encoder selection