Hypervector

class pyhdc.Hypervector(data: ArrayLike, encoding: Encoding, backend: Backend | None = None, metadata: Dict[str, Any] | None = None)[source]

Bases: object

A hypervector representation supporting multiple backends.

Similar to numpy’s ndarray, this class can represent a single hypervector or an array of hypervectors, and supports both numpy and PyTorch backends.

data: The underlying array (numpy.ndarray or torch.Tensor)

encoding: The encoding scheme used for operations

backend: The backend being used (‘numpy’ or ‘torch’)

bind(*others: Hypervector, batch_dim: int | None = None) → Hypervector[source]

Bind this hypervector with others.

Note: Batching via batch_dim is available at the Encoding class level, not at the instance method level (which always operates on single instances).

Parameters:

*others – Other hypervectors to bind
batch_dim – Passed through to Encoding.bind (instance methods don’t use batching)

Returns:

A new bound hypervector

bundle(*others: Hypervector, batch_dim: int | None = None) → Hypervector[source]

Bundle this hypervector with others.

Note: Batching via batch_dim is available at the Encoding class level, not at the instance method level (which always operates on single instances).

Parameters:

*others – Other hypervectors to bundle
batch_dim – Passed through to Encoding.bundle (instance methods don’t use batching)

Returns:

A new bundled hypervector

cpu() → Hypervector[source]: Move to CPU.

cuda(device: int | None = None) → Hypervector[source]: Move to CUDA device.

property device: Device | None: Get the device (for PyTorch backend).

property dtype: Any: Get the data type.

get_metadata() → Dict[str, Any][source]

Get operational metadata for this hypervector.

Returns:: Dictionary containing metadata from the operation that created this hypervector. Empty dict if no metadata available.

property ndim: int: Get the number of dimensions.

select(indices) → Hypervector[source]

Select hypervectors along the batch axis (axis 1).

Hypervectors are dimension-first (D, N); select keeps the columns at the given indices.

Parameters:: indices – Integer (non-negative) indices of the hypervectors to keep, as a sequence, numpy array, or tensor.
Returns:: A new Hypervector of shape (D, len(indices)) with the selected columns, preserving encoding, backend, and metadata.

property shape: Tuple[int, ...]: Get the shape of the hypervector.

similarity(other: 'Hypervector' | None = None) → float | np.ndarray | 'torch.Tensor'[source]

Compute similarity with another hypervector, or within a batch.

Parameters:: other – Another hypervector to compare with. If omitted, self must be a (D, N) batch and the similarity of column 0 against each remaining column is returned.
Returns:: Similarity score(s)

thin() → Hypervector[source]

Apply thinning operation.

Returns:: A new thinned hypervector

to(device: Device) → Hypervector[source]: Move to specified device (PyTorch only).

to_numpy() → Hypervector[source]: Convert to numpy backend.

to_torch(device: Device | None = None) → Hypervector[source]: Convert to PyTorch backend.

unbind(*others: Hypervector, batch_dim: int | None = None) → Hypervector[source]

Unbind this hypervector from others.

Note: Batching via batch_dim is available at the Encoding class level, not at the instance method level (which always operates on single instances).

Parameters:

*others – Other hypervectors to unbind
batch_dim – Passed through to Encoding.unbind (instance methods don’t use batching)

Returns:

A new unbound 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)[source]

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.
Returns:: float, ndarray, or Tensor depending on input shapes. See batched calling conventions.

Batch selection

Hypervector.select(indices)[source]

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, batch_dim=None)[source]

Bundle this hypervector with one or more others.

Parameters:

others – Additional Hypervector objects.
batch_dim – For 3-D inputs, the axis along which to bundle.

Returns:

Hypervector

Hypervector.bind(*others, batch_dim=None)[source]

Bind this hypervector with one or more others.

Parameters:: others – Additional Hypervector objects.
Returns:: Hypervector

Hypervector.unbind(*others, batch_dim=None)[source]

Unbind to recover a component.

Raises:: NotImplementedError – For encodings that do not support unbinding (e.g., BSDC_CDT).
Returns:: Hypervector

Hypervector.thin()[source]

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

Returns:: Hypervector

Backend and device conversion

Hypervector.to_numpy()[source]

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

Returns:: Hypervector

Hypervector.to_torch(device=None)[source]

Convert to PyTorch backend.

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

Hypervector.to(device)[source]

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()[source]

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

Returns:: Hypervector

Hypervector.cuda(device=None)[source]

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

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

Metadata

Hypervector.get_metadata()[source]

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)[source]

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

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

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