VSA - Main API¶

The VSA class is the main entry point for creating and using VSA models in HoloVec.

VSA Factory Class¶

class holovec.VSA[source]¶

Bases: object

High-level factory interface for creating VSA models.

This class provides a simple, unified API for creating and using different VSA models. It’s the recommended entry point for most users.

Examples

>>> # Create a MAP model with default settings
>>> model = VSA.create('MAP')
>>>
>>> # Create FHRR with specific dimension and backend
>>> model = VSA.create('FHRR', dim=512, backend='torch', device='cuda')
>>>
>>> # Use the model
>>> a, b = model.random(), model.random()
>>> c = model.bind(a, b)
>>> similarity = model.similarity(a, model.unbind(c, b))

Methods

`create`	Create a VSA model with the specified configuration.
`available_models`	Return list of available model names.

classmethod create(model_type: str, dim: int = 10000, backend: str | Backend | None = None, space: str | None = None, seed: int | None = None, **kwargs) → VSAModel[source]¶

Create a VSA model with the specified configuration.

Parameters:

model_type – Model name (‘MAP’, ‘FHRR’, ‘HRR’, ‘BSC’, etc.)
dim – Dimensionality of hypervectors
backend – Backend name (‘numpy’, ‘torch’, ‘jax’), a Backend instance, or None for the default backend
space – Vector space name or None for model’s default
seed – Random seed for reproducibility
**kwargs – Additional arguments passed to backend (e.g., device=’cuda’)

Returns:

VSA model instance

Raises:

ValueError – If model_type is not recognized

Examples

>>> model = VSA.create('MAP', dim=10000)
>>> model = VSA.create('FHRR', dim=512, backend='torch', device='cuda')
>>> model = VSA.create('MAP', space='real')  # Use real-valued MAP

classmethod available_models() → list[str][source]¶

Return list of available model names.

Returns:: List of model names that can be used with create()

classmethod model_info(model_type: str) → dict[source]¶

Get information about a specific model.

Parameters:: model_type – Model name
Returns:: Dictionary with model properties

Example

>>> info = VSA.model_info('FHRR')
>>> print(info['is_exact_inverse'])  # True

Quick Start¶

The simplest way to create a VSA model:

from holovec import VSA

# Create a model with defaults
model = VSA.create('FHRR', dim=10000, seed=42)

# Generate random vectors
a = model.random(seed=1)
b = model.random(seed=2)

# Bind (associate)
c = model.bind(a, b)

# Unbind (recover)
a_recovered = model.unbind(c, b)

# Check similarity
similarity = model.similarity(a, a_recovered)
print(f"Similarity: {similarity:.3f}")  # ~1.0

Model Selection¶

Choose a model based on your requirements:

Model	Best For	Inverse	Space	Key Feature
MAP	Hardware, speed	Self-inverse	Bipolar	Simple multiplication
FHRR	Capacity, accuracy	Exact inverse	Complex	FFT-based, best capacity
HRR	General purpose	Approximate	Real	Circular convolution
BSC	Memory efficiency	Self-inverse	Binary	Sparse binary
BSDC	High capacity	Self-inverse	Sparse	Block-structured
GHRR	Custom geometry	Tunable	Matrix	Generalized algebra
VTB	Transform binding	Learnable	Real	Vector-derived

See Choosing a VSA Model for detailed guidance.

Backend Selection¶

Choose a backend for different hardware:

# NumPy (CPU, default)
model = VSA.create('FHRR', dim=10000, backend='numpy')

# PyTorch (GPU)
model = VSA.create('FHRR', dim=10000, backend='torch', device='cuda')

# JAX (JIT/TPU)
model = VSA.create('FHRR', dim=10000, backend='jax')

See Backends and Performance for performance comparisons.

Creating Models¶

Basic creation:

model = VSA.create('MAP', dim=10000, seed=42)

With specific backend:

model = VSA.create('FHRR', dim=10000, backend='torch', device='cuda')

With custom vector space:

from holovec.spaces import create_space

space = create_space('bipolar', dim=10000, backend='numpy')
model = VSA.create('MAP', space=space)

Check available options:

# List all models
print(VSA.available_models())
# ['MAP', 'FHRR', 'HRR', 'BSC', 'BSDC', 'GHRR', 'VTB']

# List available backends
print(VSA.available_backends())
# ['numpy', 'torch', 'jax']

Common Operations¶

Once you have a model, these are the most common operations:

Binding (association):

# Bind two vectors (like key-value pairs)
bound = model.bind(key, value)

Unbinding (recovery):

# Recover value given key
recovered = model.unbind(bound, key)

Bundling (superposition):

# Combine multiple vectors
bundle = model.bundle([vec1, vec2, vec3])

Similarity:

# Measure similarity (cosine-like)
sim = model.similarity(vec1, vec2)  # Returns float in [-1, 1]

Permutation (for sequences):

# Shift/rotate vector (model-dependent)
permuted = model.permute(vec, k=1)

See VSAModel for the complete API.

Functional Interface¶

For direct model creation without the factory:

from holovec import create_model

model = create_model('FHRR', dim=10000, seed=42)

This is equivalent to VSA.create() but as a function.

holovec.create_model(model_type: str, **kwargs) → VSAModel[source]¶

Convenience function to create a VSA model.

This is an alias for VSA.create() for users who prefer functional style.