hdlib: VSA & Quantum ML Toolkit

• hdlib is a Python library for designing Vector-Symbolic Architectures using high-dimensional hypervectors for both classical and quantum machine learning.
• It extends functionality with integrated models for supervised classification, regression, clustering, and graph learning enhanced by automated feature selection and hyperparameter tuning.
• Quantum Hyperdimensional Computing is implemented to achieve reduced circuit depth, promising significant speedups in processing extremely high-dimensional data.

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 (Cumbo et al., 5 Jan 2026).

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 (Cumbo et al., 5 Jan 2026).

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 (Cumbo et al., 5 Jan 2026).

Theoretical remarks in the same source state that all core operations in classical mode are $\{+1,-1\}^D$0, whereas the quantum implementations reduce circuit depth to $\{+1,-1\}^D$1. 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 $\{+1,-1\}^D$2 is converted into a hypervector by binding each feature value with a level hypervector and bundling all features:

$\{+1,-1\}^D$3

For each class $\{+1,-1\}^D$4, all sample hypervectors in that class are bundled to form a class memory:

$\{+1,-1\}^D$5

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 $\{+1,-1\}^D$6 maximizing cross-validated accuracy, and auto_tune, which searches over $\{+1,-1\}^D$7, the number of levels $\{+1,-1\}^D$8, and distance metrics. The documented fit/predict workflow is: map each feature value to a discrete level hypervector; bind and bundle to produce $\{+1,-1\}^D$9; bundle per class to form $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$0; optionally run stepwise_regression; optionally run auto_tune; and predict via nearest-neighbor in VSA space (Cumbo et al., 5 Jan 2026).

The clustering model implements k-means in hypervector space. It initializes by randomly selecting $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$1 hypervectors as centroids $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$2, assigns each sample $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$3 to the cluster maximizing $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$4, and recomputes each centroid as the normalized bundled average of its assigned members:

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

or equivalently,

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

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 $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$7-dimensional hypervector through a nonlinear mapping,

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

where $\mathrm{bundle}(x,y)=x+y\approx x\oplus y .$9 are random base hypervectors and $\mathrm{bind}(x,y)=x\odot y ,$0 are learned biases. RegressionModel(D,n_features,k_models,\eta,T,\tau) holds $\mathrm{bind}(x,y)=x\odot y ,$1 cluster prototypes $\mathrm{bind}(x,y)=x\odot y ,$2 and $\mathrm{bind}(x,y)=x\odot y ,$3 regression weight vectors $\mathrm{bind}(x,y)=x\odot y ,$4. For each sample $\mathrm{bind}(x,y)=x\odot y ,$5, the fit procedure encodes $\mathrm{bind}(x,y)=x\odot y ,$6, computes similarities $\mathrm{bind}(x,y)=x\odot y ,$7 and confidences $\mathrm{bind}(x,y)=x\odot y ,$8, predicts

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

computes the error $\odot$0, updates each regression vector as

$\odot$1

and updates only the highest-confidence cluster by bundling the sample into $\odot$2. Binary predictions via a threshold $\odot$3 on $\odot$4 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 $\odot$5 into a single hypervector $\odot$6. The procedure begins by assigning a random hypervector $\odot$7 to each node $\odot$8 and a hypervector $\odot$9 to each edge-weight value $\Pi$0. For each node $\Pi$1, a local memory is built by bundling bound representations of its neighbors:

$\Pi$2

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

$\Pi$5

The edge-existence query edge_exists(u,v) is implemented by unbinding the memory of $\Pi$6 from $\Pi$7, forming $\Pi$8, and checking whether the similarity of $\Pi$9 to $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$0 exceeds a threshold. The model also supports graph edge-weight prediction and an error_mitigation procedure that iteratively refines $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$1 to reduce classification errors (Cumbo et al., 5 Jan 2026).

The same source gives the graph-encoding complexity as $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$2 to build and $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$3 per edge query. It also reports graph edge-prediction accuracy above $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$4 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 $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$5 are encoded as phases on a $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$6-qubit uniform superposition,

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

Quantum binding is implemented as element-wise phase addition through a phase oracle $$\mathrm{permute}(x)=\Pi(x), \quad \Pi\in\{0,1\}^{D\times D}.$$8:

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

Quantum bundling is implemented through LCU together with Oblivious Amplitude Amplification to construct $k$0. Quantum permutation applies QFT, phase shifts, and inverse QFT to enact a cyclic shift. Similarity is estimated by a Hadamard Test circuit computing $k$1 (Cumbo et al., 5 Jan 2026).

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 $k$2; apply controlled-phase gates encoding $k$3; uncompute ancilla.

The performance summary states that QHDC similarity computations scale with $k$4 circuit depth, while the theoretical discussion more generally states that quantum implementations reduce circuit depth to $k$5. 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 (Cumbo et al., 5 Jan 2026).

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 $k$6–$k$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 $k$8 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 $k$9 while converging in fewer iterations due to vector normalization; graph edge-prediction accuracy exceeded $[\Pi_k(x)]_i = x_{(i-k)\bmod D}.$0 on synthetic and real-world networks; feature selection removed up to $[\Pi_k(x)]_i = x_{(i-k)\bmod D}.$1 of dimensions with less than $[\Pi_k(x)]_i = x_{(i-k)\bmod D}.$2 drop in classification accuracy; and experiments showed up to $[\Pi_k(x)]_i = x_{(i-k)\bmod D}.$3 noise tolerance in input features before accuracy degraded by more than $[\Pi_k(x)]_i = x_{(i-k)\bmod D}.$4. 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.