Hypervector

Reference summary

Constructor

Hypervector(data, encoding, backend=None, metadata=None)

Normally you do not construct Hypervector directly: use encoding.generate(), encoding.zeros(), or encoding.from_array().

Properties

Property	Type	Description
`.data`	`ndarray` or `Tensor`	Underlying NumPy array or PyTorch tensor (read-only)
`.encoding`	`Encoding`	The encoding that produced this hypervector
`.backend`	`str`	`"numpy"` or `"torch"`
`.shape`	`tuple`	Shape of the underlying array (e.g., `(10000,)` or `(10000, 100)`)
`.ndim`	`int`	Number of dimensions (1 for a single HV, 2 for a batch)
`.dtype`	dtype	Data type of the underlying array (e.g., `float32`, `int8`)
`.device`	`str` or `None`	PyTorch device string (e.g., `"cuda:0"`); `None` for NumPy backend

Similarity

Hypervector.similarity(other=None, *, axis=None, mode='pairwise')

Compute similarity to another hypervector (or batch), or within a single batch when other is omitted.

Delegates to the encoding’s similarity function. Returns values in [-1, 1].

Parameters:

other – A Hypervector of the same encoding and backend. If omitted, self must be a (D, N) batch and the similarity of column 0 against each remaining column is returned.
axis – For a single (D, N, M, ...) batch, the batch axis to split on.
mode – "pairwise" (default) or "cross". With "cross", self (D, P) and other (D, M) give the full (P, M) cross-similarity matrix. other is required (None raises ValueError).

Returns:

float, ndarray, or Tensor depending on input shapes.

Batch selection

Hypervector.select(indices)

Select hypervectors (columns) from a (D, N) batch by index along the batch axis. Returns a (D, len(indices)) batch. Works on NumPy and PyTorch (list or array indices are accepted).

codebook = enc.generate(size=(10_000, 100))   # (10000, 100)
subset   = codebook.select([0, 2, 4])         # (10000, 3)

Bundle and bind

Hypervector.bundle(*others, axis=None, batch_dim=None)

Bundle this hypervector with one or more others. A batched operand is reduced automatically, axis= selects which batch axis to collapse.

Parameters:

others – Additional Hypervector objects.
axis – Batch axis (or tuple of axes) to reduce. Axis 0 cannot be reduced.
batch_dim – Deprecated as of 2.1.0, emits DeprecationWarning and will be removed in a future release. Pass a batched operand or use axis=.

Returns:

Hypervector

Hypervector.bind(*others, batch_dim=None)

Bind this hypervector with one or more others. Batched operands are handled automatically: element-wise binders broadcast, others are applied per column.

Parameters:

others – Additional Hypervector objects.
batch_dim – Deprecated as of 2.1.0, emits DeprecationWarning and will be removed in a future release. Pass a batched operand instead.

Returns:

Hypervector

Hypervector.unbind(*others, batch_dim=None)

Unbind to recover a component. Batched operands are handled automatically.

Parameters:: batch_dim – Deprecated as of 2.1.0, emits DeprecationWarning and will be removed in a future release. Pass a batched operand instead.
Raises:: NotImplementedError – For encodings that do not support unbinding (e.g., BSDC_CDT).
Returns:: Hypervector

Hypervector.thin()

Apply the encoding’s thinning operation (sparse binary encodings only). For encodings that do not thin, returns self unchanged.

Returns:: Hypervector

Unary operations

These four operate dimension-first. Axis 0 is always the dimension D, and each operation broadcasts over the trailing batch axes of a (D, N) or (D, N, M) input. Each delegates to the encoding (self._encoding.<op>) and returns a new Hypervector. Whether an operation is defined depends on the encoding family. The per-family behavior is listed below and resolved through the encoding’s EncodingSpec.

Hypervector.permute(shift=1)

Cyclic-shift permutation along axis 0 (the dimension). A positive shift rolls coordinates forward, a negative shift rolls them back and is the exact inverse of the positive shift. Every encoding defines permute: when an encoding does not supply its own permute_fn, the shared CyclicShift component is used, so all families support it by default.

Parameters:: shift – Integer number of positions to roll. Default 1.
Returns:: Hypervector

Hypervector.inverse()

The binding inverse: the element that unbinds what binding produced. The mechanism is family-specific (IdentityInverse for self-inverse binding, ReverseInverse for circular convolution, PhaseNegate for FHRR).

Raises:: NotImplementedError – For encodings whose EncodingSpec leaves inverse_fn at its default: MAP_C, VTB, MBAT, BSDC_CDT, BSDC_S, BSDC_SEG, and BSDC_THIN.
Returns:: Hypervector

Hypervector.normalize()

Normalize to the entry distribution for the encoding. The mechanism is family-specific (SignNormalize to bipolar {-1, 0, +1} for MAP, L2Normalize to unit L2 length along axis 0 for HRR/VTB/MBAT, WrapPhase to [-pi, pi) for FHRR).

Raises:: NotImplementedError – For encodings whose EncodingSpec leaves normalize_fn at its default: BSC and all four BSDC variants (BSDC_CDT, BSDC_S, BSDC_SEG, BSDC_THIN).
Returns:: Hypervector

Hypervector.negative()

The bundling (additive) inverse: element-wise negation for the additive families (Negate).

Raises:: NotImplementedError – For encodings whose EncodingSpec leaves negative_fn at its default: FHRR, BSC, and all four BSDC variants (BSDC_CDT, BSDC_S, BSDC_SEG, BSDC_THIN).
Returns:: Hypervector

Backend and device conversion

Hypervector.to_numpy()

Convert to NumPy backend. Copies data if currently on PyTorch.

Returns:: Hypervector

Hypervector.to_torch(device=None)

Convert to PyTorch backend.

Parameters:: device – Target device string ("cpu", "cuda", etc.). None means CPU.
Returns:: Hypervector

Hypervector.to(device)

Move to a specific device. Equivalent to .to_torch(device) when on NumPy, or .data.to(device) when already on PyTorch.

Parameters:: device – Device string or torch.device.
Returns:: Hypervector

Hypervector.cpu()

Move to CPU. Equivalent to .to("cpu").

Returns:: Hypervector

Hypervector.cuda(device=None)

Move to CUDA. Equivalent to .to("cuda") or .to("cuda:<device>").

Parameters:: device – Optional CUDA device index (int).
Returns:: Hypervector

Metadata

Hypervector.get_metadata()

Return the metadata dictionary attached to this hypervector.

Most hypervectors have an empty metadata dict. MBAT binding stores the random matrices here, keyed by "matrices".

Returns:: Dict[str, Any]

Special methods

Hypervector.__getitem__(key)

Index or slice a batch hypervector.

batch = enc.generate(size=(10_000, 100))   # (10000, 100)
hv0   = batch[:, 0]        # shape (10000,): first hypervector (column 0)
first5 = batch[:, :5]      # shape (10000, 5): first five hypervectors

Operators route through the encoding, so each one raises per family exactly as the underlying method does. For +, *, and / a non-Hypervector right-hand operand returns NotImplemented, which Python turns into a TypeError. There are no reflected dunders, so other + hv with a non-hypervector other also raises TypeError.

a = enc.generate(size=10_000)
b = enc.generate(size=10_000)

bundled = a + b       # a.bundle(b)
bound   = a * b       # a.bind(b)
recov   = bound / b   # bound.unbind(b)
inv     = ~a          # a.inverse()
rolled  = a >> 3      # a.permute(shift=3)
back    = rolled << 3 # a.permute(shift=-3), inverse of >> 3

Hypervector.__add__(other): Bundle. Routes to self.bundle(other). other must be a Hypervector, any other type returns NotImplemented. Defined for all encodings.

Hypervector.__mul__(other): Bind. Routes to self.bind(other). other must be a Hypervector, any other type returns NotImplemented. Defined for all encodings. On a batched (ndim > 1) operand the non-element-wise binders (HRR convolution, shifting, matrix, VTB, BSDC_CDT) are applied per column, returning one batched result.

Hypervector.__truediv__(other)

Unbind. Routes to self.unbind(other). other must be a Hypervector, any other type returns NotImplemented.

Raises:: NotImplementedError – For BSDC_CDT (its unbinding_fn is the default raising stub).

Hypervector.__invert__()

Inverse. Routes to self.inverse().

Raises:: NotImplementedError – For MAP_C, VTB, MBAT, BSDC_CDT, BSDC_S, BSDC_SEG, and BSDC_THIN (see Hypervector.inverse()).

Hypervector.__rshift__(shift): Permute forward. Routes to self.permute(shift=int(shift)). shift must be integral (Python int or any numbers.Integral such as a NumPy integer) and must not be a bool; a bool, float, or other type returns NotImplemented (Python raises TypeError). Defined for all encodings.

Hypervector.__lshift__(shift): Permute backward. Routes to self.permute(shift=-int(shift)) and is the exact inverse of >> by the same amount. Same shift rule as Hypervector.__rshift__(): integral and not bool, else NotImplemented. Defined for all encodings.

Hypervector.__len__(): Return shape[0], which is the hypervector dimension D (axis 0), not the batch count, since batches are dimension-first (D, N).

Hypervector.__repr__(): Human-readable summary: shape, dtype, backend.