Skip to content

Base Classes

Core abstract classes that define the VSA interface.

AbstractHypervector

vsax.core.base.AbstractHypervector

Bases: ABC

Base class for all hypervector representations.

Wraps a JAX array and provides common operations for hypervectors. All concrete implementations must inherit from this class.

Parameters:

Name Type Description Default
vec ndarray

The underlying JAX array representing the hypervector.

 required
Source code in vsax/core/base.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class AbstractHypervector(ABC):
    """Base class for all hypervector representations.

    Wraps a JAX array and provides common operations for hypervectors.
    All concrete implementations must inherit from this class.

    Args:
        vec: The underlying JAX array representing the hypervector.
    """

    def __init__(self, vec: jnp.ndarray) -> None:
        """Initialize hypervector with underlying array.

        Args:
            vec: JAX array representing the hypervector.
        """
        self._vec = vec

    @property
    def vec(self) -> jnp.ndarray:
        """Return the underlying JAX array.

        Returns:
            The JAX array wrapped by this hypervector.
        """
        return self._vec

    @property
    def shape(self) -> tuple[int, ...]:
        """Return the shape of the hypervector.

        Returns:
            Tuple representing the shape of the underlying array.
        """
        return cast(tuple[int, ...], self._vec.shape)

    @property
    def dtype(self) -> jnp.dtype:
        """Return the data type of the hypervector.

        Returns:
            JAX dtype of the underlying array.
        """
        return self._vec.dtype

    @abstractmethod
    def normalize(self) -> "AbstractHypervector":
        """Normalize the hypervector.

        The normalization method depends on the representation type.
        For example, complex vectors normalize to unit magnitude (phase-only),
        while real vectors use L2 normalization.

        Returns:
            Normalized hypervector of the same type.
        """
        pass

    def to_numpy(self) -> np.ndarray:
        """Convert the hypervector to a NumPy array.

        Returns:
            NumPy array representation of the hypervector.
        """
        return np.array(self._vec)

    def __repr__(self) -> str:
        """Return string representation of the hypervector.

        Returns:
            String showing class name, shape, and dtype.
        """
        return f"{self.__class__.__name__}(shape={self.shape}, dtype={self.dtype})"

Attributes

vec property

Return the underlying JAX array.

Returns:

Type Description
ndarray

The JAX array wrapped by this hypervector.

shape property

Return the shape of the hypervector.

Returns:

Type Description
tuple[int, ...]

Tuple representing the shape of the underlying array.

dtype property

Return the data type of the hypervector.

Returns:

Type Description
dtype

JAX dtype of the underlying array.

Functions

normalize() abstractmethod

Normalize the hypervector.

The normalization method depends on the representation type. For example, complex vectors normalize to unit magnitude (phase-only), while real vectors use L2 normalization.

Returns:

Type Description
AbstractHypervector

Normalized hypervector of the same type.
Source code in vsax/core/base.py 
55
56
57
58
59
60
61
62
63
64
65
66
@abstractmethod
def normalize(self) -> "AbstractHypervector":
    """Normalize the hypervector.

    The normalization method depends on the representation type.
    For example, complex vectors normalize to unit magnitude (phase-only),
    while real vectors use L2 normalization.

    Returns:
        Normalized hypervector of the same type.
    """
    pass

to_numpy()

Convert the hypervector to a NumPy array.

Returns:

Type Description
ndarray

NumPy array representation of the hypervector.
Source code in vsax/core/base.py 
68
69
70
71
72
73
74
def to_numpy(self) -> np.ndarray:
    """Convert the hypervector to a NumPy array.

    Returns:
        NumPy array representation of the hypervector.
    """
    return np.array(self._vec)

AbstractOpSet

vsax.core.base.AbstractOpSet

Bases: ABC

Base class for VSA operation sets.

Defines the symbolic algebra operations for binding and bundling hypervectors. All operations work directly on JAX arrays, not on AbstractHypervector instances.

Concrete implementations (FHRR, MAP, Binary) must implement all abstract methods.

Source code in vsax/core/base.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class AbstractOpSet(ABC):
    """Base class for VSA operation sets.

    Defines the symbolic algebra operations for binding and bundling hypervectors.
    All operations work directly on JAX arrays, not on AbstractHypervector instances.

    Concrete implementations (FHRR, MAP, Binary) must implement all abstract methods.
    """

    @abstractmethod
    def bind(self, a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
        """Bind two hypervectors together.

        Binding creates a composite representation that is dissimilar to both inputs
        but can be unbound using the inverse operation. The specific binding operation
        depends on the algebra (e.g., circular convolution for FHRR, elementwise
        multiplication for MAP).

        Args:
            a: First hypervector as JAX array.
            b: Second hypervector as JAX array.

        Returns:
            Bound hypervector as JAX array.
        """
        pass

    @abstractmethod
    def bundle(self, *vecs: jnp.ndarray) -> jnp.ndarray:
        """Bundle multiple hypervectors into a single representation.

        Bundling creates a superposition that is similar to all inputs.
        The bundled vector can be queried to retrieve the constituent vectors.

        Args:
            *vecs: Variable number of hypervectors as JAX arrays.

        Returns:
            Bundled hypervector as JAX array.
        """
        pass

    @abstractmethod
    def inverse(self, a: jnp.ndarray) -> jnp.ndarray:
        """Compute the inverse of a hypervector.

        The inverse is used to unbind: if c = bind(a, b), then
        unbind(c, b) = bind(c, inverse(b)) ≈ a.

        Args:
            a: Hypervector as JAX array.

        Returns:
            Inverse hypervector as JAX array.
        """
        pass

    def unbind(self, a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
        """Unbind b from a to recover the original vector.

        If c = bind(a, b), then unbind(c, b) ≈ a.

        This provides an explicit, intuitive interface for unbinding operations.
        The default implementation uses: bind(a, inverse(b))

        Concrete operation sets may override this for efficiency or to provide
        specialized unbinding behavior.

        Args:
            a: Bound hypervector (result of bind operation).
            b: Hypervector to unbind.

        Returns:
            Recovered hypervector as JAX array.

        Example:
            >>> import jax.numpy as jnp
            >>> from vsax.ops import FHRROperations
            >>> ops = FHRROperations()
            >>> x = jnp.exp(1j * jnp.array([0.5, 1.0, 1.5]))
            >>> y = jnp.exp(1j * jnp.array([0.3, 0.7, 1.1]))
            >>> bound = ops.bind(x, y)
            >>> recovered = ops.unbind(bound, y)
            >>> # recovered ≈ x (with high similarity)
        """
        return self.bind(a, self.inverse(b))

    def unbind_left(self, a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
        """Left-unbind: recover y from z = bind(x, y) given x.

        For non-commutative algebras (e.g., quaternions), this computes:
            inverse(a) * b

        which recovers y from z = bind(x, y) when given x.

        For commutative algebras, this is equivalent to unbind(b, a).

        The default implementation uses: bind(inverse(a), b)

        Args:
            a: Hypervector used as first argument in binding (x).
            b: Bound hypervector (z = bind(x, y)).

        Returns:
            Recovered hypervector (y) as JAX array.

        Example:
            >>> # For quaternions (non-commutative):
            >>> z = ops.bind(x, y)  # z = x * y
            >>> recovered_y = ops.unbind_left(x, z)  # x⁻¹ * z = y
            >>>
            >>> # For FHRR/MAP (commutative), equivalent to unbind:
            >>> z = ops.bind(x, y)
            >>> recovered_y = ops.unbind_left(x, z)  # same as unbind(z, x)
        """
        return self.bind(self.inverse(a), b)

    def permute(self, a: jnp.ndarray, shift: int) -> jnp.ndarray:
        """Permute a hypervector by circular shift.

        This is an optional operation. The default implementation performs
        a circular shift, but concrete classes may override with different
        permutation strategies.

        Args:
            a: Hypervector as JAX array.
            shift: Number of positions to shift (positive = right, negative = left).

        Returns:
            Permuted hypervector as JAX array.
        """
        return jnp.roll(a, shift)

Functions

bind(a, b) abstractmethod

Bind two hypervectors together.

Binding creates a composite representation that is dissimilar to both inputs but can be unbound using the inverse operation. The specific binding operation depends on the algebra (e.g., circular convolution for FHRR, elementwise multiplication for MAP).

Parameters:

Name Type Description Default
a ndarray

First hypervector as JAX array.

 required
b ndarray

Second hypervector as JAX array.

 required

Returns:

Type Description
ndarray

Bound hypervector as JAX array.
Source code in vsax/core/base.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
@abstractmethod
def bind(self, a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
    """Bind two hypervectors together.

    Binding creates a composite representation that is dissimilar to both inputs
    but can be unbound using the inverse operation. The specific binding operation
    depends on the algebra (e.g., circular convolution for FHRR, elementwise
    multiplication for MAP).

    Args:
        a: First hypervector as JAX array.
        b: Second hypervector as JAX array.

    Returns:
        Bound hypervector as JAX array.
    """
    pass

bundle(*vecs) abstractmethod

Bundle multiple hypervectors into a single representation.

Bundling creates a superposition that is similar to all inputs. The bundled vector can be queried to retrieve the constituent vectors.

Parameters:

Name Type Description Default
*vecs ndarray

Variable number of hypervectors as JAX arrays.

 ()

Returns:

Type Description
ndarray

Bundled hypervector as JAX array.
Source code in vsax/core/base.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@abstractmethod
def bundle(self, *vecs: jnp.ndarray) -> jnp.ndarray:
    """Bundle multiple hypervectors into a single representation.

    Bundling creates a superposition that is similar to all inputs.
    The bundled vector can be queried to retrieve the constituent vectors.

    Args:
        *vecs: Variable number of hypervectors as JAX arrays.

    Returns:
        Bundled hypervector as JAX array.
    """
    pass

inverse(a) abstractmethod

Compute the inverse of a hypervector.

The inverse is used to unbind: if c = bind(a, b), then unbind(c, b) = bind(c, inverse(b)) ≈ a.

Parameters:

Name Type Description Default
a ndarray

Hypervector as JAX array.

 required

Returns:

Type Description
ndarray

Inverse hypervector as JAX array.
Source code in vsax/core/base.py 
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@abstractmethod
def inverse(self, a: jnp.ndarray) -> jnp.ndarray:
    """Compute the inverse of a hypervector.

    The inverse is used to unbind: if c = bind(a, b), then
    unbind(c, b) = bind(c, inverse(b)) ≈ a.

    Args:
        a: Hypervector as JAX array.

    Returns:
        Inverse hypervector as JAX array.
    """
    pass

unbind(a, b)

Unbind b from a to recover the original vector.

If c = bind(a, b), then unbind(c, b) ≈ a.

This provides an explicit, intuitive interface for unbinding operations. The default implementation uses: bind(a, inverse(b))

Concrete operation sets may override this for efficiency or to provide specialized unbinding behavior.

Parameters:

Name Type Description Default
a ndarray

Bound hypervector (result of bind operation).

 required
b ndarray

Hypervector to unbind.

 required

Returns:

Type Description
ndarray

Recovered hypervector as JAX array.
Example

import jax.numpy as jnp from vsax.ops import FHRROperations ops = FHRROperations() x = jnp.exp(1j * jnp.array([0.5, 1.0, 1.5])) y = jnp.exp(1j * jnp.array([0.3, 0.7, 1.1])) bound = ops.bind(x, y) recovered = ops.unbind(bound, y)

recovered ≈ x (with high similarity)
Source code in vsax/core/base.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def unbind(self, a: jnp.ndarray, b: jnp.ndarray) -> jnp.ndarray:
    """Unbind b from a to recover the original vector.

    If c = bind(a, b), then unbind(c, b) ≈ a.

    This provides an explicit, intuitive interface for unbinding operations.
    The default implementation uses: bind(a, inverse(b))

    Concrete operation sets may override this for efficiency or to provide
    specialized unbinding behavior.

    Args:
        a: Bound hypervector (result of bind operation).
        b: Hypervector to unbind.

    Returns:
        Recovered hypervector as JAX array.

    Example:
        >>> import jax.numpy as jnp
        >>> from vsax.ops import FHRROperations
        >>> ops = FHRROperations()
        >>> x = jnp.exp(1j * jnp.array([0.5, 1.0, 1.5]))
        >>> y = jnp.exp(1j * jnp.array([0.3, 0.7, 1.1]))
        >>> bound = ops.bind(x, y)
        >>> recovered = ops.unbind(bound, y)
        >>> # recovered ≈ x (with high similarity)
    """
    return self.bind(a, self.inverse(b))

permute(a, shift)

Permute a hypervector by circular shift.

This is an optional operation. The default implementation performs a circular shift, but concrete classes may override with different permutation strategies.

Parameters:

Name Type Description Default
a ndarray

Hypervector as JAX array.

 required
shift int

Number of positions to shift (positive = right, negative = left).

 required

Returns:

Type Description
ndarray

Permuted hypervector as JAX array.
Source code in vsax/core/base.py 
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def permute(self, a: jnp.ndarray, shift: int) -> jnp.ndarray:
    """Permute a hypervector by circular shift.

    This is an optional operation. The default implementation performs
    a circular shift, but concrete classes may override with different
    permutation strategies.

    Args:
        a: Hypervector as JAX array.
        shift: Number of positions to shift (positive = right, negative = left).

    Returns:
        Permuted hypervector as JAX array.
    """
    return jnp.roll(a, shift)