---
title: 'hdlib: VSA & Quantum ML Toolkit'
url: https://www.emergentmind.com/topics/hdlib
type: topic
---

# hdlib: VSA & Quantum ML Toolkit

hdlib is a Python library for designing Vector-Symbolic Architectures (VSA), also called Hyperdimensional Computing, and version 2.0 extends the original library with substantially broader machine-learning functionality within the same hypervector paradigm. The extension introduces significant enhancements to the existing supervised classification model, also enabling feature selection, together with a new regression model for predicting continuous variables, a clustering model for unsupervised learning, and a graph-based learning model. It also proposes the first implementation ever of Quantum Hyperdimensional Computing with quantum-powered arithmetic operations and a new Quantum Machine Learning model for supervised learning. The library remains open-source on GitHub under the MIT license, is distributed through the Python Package Index and Conda, and is documented through the official Wiki [2601.02509].

## 1. Design goals and scope

hdlib was created by Cumbo et al. (2023) to provide researchers with a lightweight, extensible Python framework for VSA. In version 2.0, the design is extended in three stated directions: deep integration of data-driven models within the same VSA paradigm; automated feature selection and hyperparameter optimization for improved model interpretability and performance; and the first implementation of Quantum Hyperdimensional Computing for quantum-accelerated VSA arithmetic and learning [2601.02509].

The resulting scope is unusually broad for a single VSA toolkit. It spans supervised classification, regression, clustering, graph learning, and quantum implementations of core arithmetic and supervised learning. This suggests a unification strategy in which symbolic encoding, memory construction, and prediction remain expressed through hypervector algebra even when the learning objective changes from class discrimination to continuous prediction, unsupervised partitioning, or graph inference.

## 2. Hypervector representation and core algebra

In hdlib, each symbol or data item is represented by a high-dimensional vector, or hypervector, $x \in \mathbb{R}^D$ or a bipolar vector in $\{+1,-1\}^D$. The library implements three core VSA operations: bundling, binding, and permutation. Bundling is superposition by vector addition, followed by optional normalization:

$$
\mathrm{bundle}(x,y)=x+y\approx x\oplus y .
$$

Binding is multiplicative association by element-wise product:

$$
\mathrm{bind}(x,y)=x\odot y ,
$$

where $\odot$ is the Hadamard product. Permutation provides role or tag encoding through a fixed random or learned permutation $\Pi$:

$$
\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.
$$

In practice, the permutation can be implemented as a cyclic rotation by $k$:

$$
[\Pi_k(x)]_i = x_{(i-k)\bmod D}.
$$

Similarity between hypervectors is typically measured either by cosine similarity,

$$
\mathrm{sim}(x,y)=\frac{x\cdot y}{\|x\|\|y\|},
$$

or by Hamming distance in the binary or bipolar case [2601.02509].

Theoretical remarks in the same source state that all core operations in classical mode are $O(D)$, whereas the quantum implementations reduce circuit depth to $O(\mathrm{poly}\log D)$. This suggests that hdlib treats hypervector algebra not merely as a representational substrate but as the computational interface across its classical and quantum subsystems.

## 3. Integrated learning models

Version 2.0 centers on four major extensions that embed machine-learning workflows directly into VSA data structures and operations.

| Component | Module or class | Function |
|---|---|---|
| Supervised classification | `hdlib.model.classification.ClassificationModel` | Class-memory learning with feature selection and auto-tuning |
| Clustering | `hdlib.model.clustering.ClusteringModel` | k-means in hypervector space |
| Regression | `hdlib.model.regression.RegressionEncoder`, `RegressionModel` | Continuous prediction with multi-model updates |
| Graph learning | `hdlib.model.graph.GraphModel` | Whole-graph hypervector encoding and edge inference |

In the classification model, each training sample with feature vector $f\in\mathbb{R}^n$ is converted into a hypervector by binding each feature value with a level hypervector and bundling all features:

$$
v_i=\mathrm{bundle}_{j=1}^n \; \mathrm{bind}\bigl(F_j,\;L_{\mathrm{level}(f_{ij})}\bigr).
$$

For each class $c$, all sample hypervectors in that class are bundled to form a class memory:

$$
M_c=\sum_{i:y_i=c} v_i.
$$

Prediction is then performed by selecting the class maximizing similarity between the query hypervector and the class memory. The associated automation procedures are `stepwise_regression`, which selects a subset of features $F' \subseteq \{1\ldots n\}$ maximizing cross-validated accuracy, and `auto_tune`, which searches over $D\in[D_{\min},D_{\max}]$, the number of levels $L$, and distance metrics. The documented fit/predict workflow is: map each feature value to a discrete level hypervector; bind and bundle to produce $v_i$; bundle per class to form $M_c$; optionally run `stepwise_regression`; optionally run `auto_tune`; and predict via nearest-neighbor in VSA space [2601.02509].

The clustering model implements k-means in hypervector space. It initializes by randomly selecting $k$ hypervectors as centroids $C_1,\ldots,C_k$, assigns each sample $v_i$ to the cluster maximizing $\mathrm{sim}(v_i,C_j)$, and recomputes each centroid as the normalized bundled average of its assigned members:

$$
C_j=\frac{1}{|S_j|}\sum_{i:r_i=j} v_i,
$$

or equivalently,

$$
C_j=\mathrm{normalize}\bigl(\mathrm{bundle}_{i\in S_j}(v_i)\bigr).
$$

The procedure iterates until assignments stabilize or `max_iter` is reached.

The regression subsystem comprises two classes. `RegressionEncoder(D,n_features)` encodes continuous features into a $D$-dimensional hypervector through a nonlinear mapping,

$$
v(x)=\sum_{j=1}^n \alpha_j\,\mathrm{bind}\bigl(B_j,\;x_j\bigr)+\beta ,
$$

where $B_j$ are random base hypervectors and $\alpha_j,\beta$ are learned biases. `RegressionModel(D,n_features,k_models,\eta,T,\tau)` holds $k$ cluster prototypes $\{C_j\}$ and $k$ regression weight vectors $\{W_j\}$. For each sample $(x,y)$, the fit procedure encodes $x$, computes similarities $s_j=\mathrm{sim}(v,C_j)$ and confidences $p_j=\mathrm{softmax}(s_j)$, predicts

$$
\hat y=\sum_{j=1}^k p_j(W_j\cdot v),
$$

computes the error $e=y-\hat y$, updates each regression vector as

$$
W_j \leftarrow W_j + \eta\,p_j\,e\,v,
$$

and updates only the highest-confidence cluster by bundling the sample into $C_{j^*}$. Binary predictions via a threshold $\tau$ on $v\cdot W_j$ allow fast Hamming-distance inference when `quantized_prediction` is enabled.

## 4. Graph-based learning and compressed graph memory

`hdlib.model.graph.GraphModel` encodes an entire graph $G=(V,E)$ into a single hypervector $H$. The procedure begins by assigning a random hypervector $N_u$ to each node $u\in V$ and a hypervector $W_w$ to each edge-weight value $w$. For each node $u$, a local memory is built by bundling bound representations of its neighbors:

$$
M_u=\sum_{(u,v,w)\in E} \mathrm{bind}\bigl(N_v,\;W_w\bigr).
$$

For directed graphs, $M_u$ is permuted by $\Pi$ to encode direction. The graph is then compressed into one hypervector:

$$
H=\sum_{u\in V}\mathrm{bind}\bigl(N_u,\;M_u\bigr).
$$

The edge-existence query `edge_exists(u,v)` is implemented by unbinding the memory of $u$ from $H$, forming $\widetilde M_u=\mathrm{unbind}(H,N_u)$, and checking whether the similarity of $\mathrm{bind}(\widetilde M_u,N_v)$ to $W_w$ exceeds a threshold. The model also supports graph edge-weight prediction and an `error_mitigation` procedure that iteratively refines $\{M_u\}$ to reduce classification errors [2601.02509].

The same source gives the graph-encoding complexity as $O(|E|+|V|)$ to build and $O(1)$ per edge query. It also reports graph edge-prediction accuracy above $90\%$ on synthetic and real-world networks, outperforming prior VSA graph encodings associated in the summary with Poduval et al. (2022). A plausible implication is that hdlib treats graph structure as a memory retrieval problem rather than as a separate graph-native optimization framework.

## 5. Quantum Hyperdimensional Computing

The quantum subsystem, `hdlib.arithmetic.quantum`, uses Qiskit to implement VSA arithmetic with quantum circuits. Bipolar hypervectors $x\in\{\pm 1\}^D$ are encoded as phases on a $D$-qubit uniform superposition,

$$
|\psi_x\rangle = \frac{1}{\sqrt D}\sum_i e^{i\pi(1-x_i)/2}|i\rangle .
$$

Quantum binding is implemented as element-wise phase addition through a phase oracle $O_{x,y}$:

$$
O_{x,y}: |i\rangle \mapsto e^{i(\phi_i^{(x)}+\phi_i^{(y)})}|i\rangle .
$$

Quantum bundling is implemented through LCU together with Oblivious Amplitude Amplification to construct $(|\psi_x\rangle+|\psi_y\rangle)/\sqrt 2$. Quantum permutation applies QFT, phase shifts, and inverse QFT to enact a cyclic shift. Similarity is estimated by a Hadamard Test circuit computing $\mathrm{Re}\langle\psi_x|\psi_y\rangle=\cos\theta$ [2601.02509].

`QuantumClassificationModel` wraps classical bundling or quantum bundling and then measures similarities with `run_hadamard_test` to build and compare class memories. The pseudocode given for quantum binding is: prepare $|\psi_x\rangle\otimes|\psi_y\rangle$; apply controlled-phase gates encoding $\phi_i^{(x)}+\phi_i^{(y)}$; uncompute ancilla.

The performance summary states that QHDC similarity computations scale with $O(\log D)$ circuit depth, while the theoretical discussion more generally states that quantum implementations reduce circuit depth to $O(\mathrm{poly}\log D)$. The text characterizes this as promising speedups for extremely high dimensions. This suggests that the principal quantum contribution is not a change in VSA semantics, but a change in the arithmetic realization of standard VSA operators.

## 6. Distribution, usage patterns, and empirical profile

hdlib 2.0 is distributed as an open-source project on GitHub under the MIT license, can be installed with `pip install hdlib` or `conda install -c conda-forge hdlib`, and provides documentation and examples through the official Wiki. The usage examples in the documentation cover basic arithmetic through `bind`, `bundle`, and `permute`; classical classification through `ClassificationModel`; feature selection through `stepwise_regression`; clustering through `ClusteringModel`; regression through `RegressionEncoder` and `RegressionModel`; graph learning through `GraphModel`; and quantum classification through `QuantumClassificationModel` together with `phase_oracle_gate` and `run_hadamard_test` [2601.02509].

The benchmark summary explicitly notes that exact numbers are dataset-dependent. Within that qualification, the reported empirical profile is as follows: classification accuracy improved by $3$–$7$ percentage points over hdlib 1.0 on biological and chemical datasets, attributed to `auto_tune` and feature selection; regression RMSE was reduced by approximately $10\%$ compared to a single-model VSA regressor identified as Hernández-Cano et al. (2021); clustering purity on benchmark UCI data matched classic k-means within $\pm 1\%$ while converging in fewer iterations due to vector normalization; graph edge-prediction accuracy exceeded $90\%$ on synthetic and real-world networks; feature selection removed up to $50\%$ of dimensions with less than $1\%$ drop in classification accuracy; and experiments showed up to $20\%$ noise tolerance in input features before accuracy degraded by more than $5\%$. The source also states that bundling inherently denoises noisy data.

Taken together, these characteristics position hdlib 2.0 as a unified and extensible VSA framework for classical and quantum machine learning. Its organization around core hypervector algebra, specialized model classes, and automated tuning tools indicates a library intended for prototyping and deploying brain-inspired machine-learning pipelines across diverse scientific domains.

Source: https://www.emergentmind.com/topics/hdlib