Add new classifiers module with commonly used HD/VSA classifiers (#166)

* WIP add classify module

* [github-action] formatting fixes

* Add neuralHD

* Add neuralhd to __all__

* Add LeHDC implementation

* [github-action] formatting fixes

* Adding models QuantHD, CompHD, SparseHD and RefineHD

* [github-action] formatting fixes

* Add classifiers documentation

* [github-action] formatting fixes

* Add IntRVFL

* Fix bugs

* [github-action] formatting fixes

* Refactoring

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: pere verges <[email protected]>

Author: 3 people

docs/_templates/class_classifier.rst

@@ -0,0 +1,10 @@
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline}}
+
+.. autoclass:: {{ name }}
+    :members: fit, predict, accuracy
+    :special-members: __call__

docs/classifiers.rst

@@ -0,0 +1,23 @@
+.. _models:
+
+torchhd.classifiers
+=======================
+
+.. currentmodule:: torchhd.classifiers
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+    :template: class_classifier.rst
+    
+    Classifier
+    Vanilla
+    AdaptHD
+    OnlineHD
+    NeuralHD
+    DistHD
+    CompHD
+    SparseHD
+    QuantHD
+    LeHDC
+    IntRVFL

docs/index.rst

@@ -19,6 +19,7 @@ Torchhd is a Python library dedicated to *Hyperdimensional Computing* also known
    embeddings
    structures
    models
+   classifiers
    memory
    datasets
    utils

examples/classifiers.py

@@ -0,0 +1,83 @@
+import torch
+import torchhd
+from torchhd.datasets.isolet import ISOLET
+
+classifiers = [
+    "Vanilla",
+    "AdaptHD",
+    "OnlineHD",
+    "NeuralHD",
+    "DistHD",
+    "CompHD",
+    "SparseHD",
+    "QuantHD",
+    "LeHDC",
+    "IntRVFL",
+]
+
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+print("Using {} device".format(device))
+
+DIMENSIONS = 1024  # number of hypervector dimensions
+BATCH_SIZE = 12  # for GPUs with enough memory we can process multiple images at ones
+
+train_ds = ISOLET("../data", train=True, download=True)
+train_ld = torch.utils.data.DataLoader(train_ds, batch_size=BATCH_SIZE, shuffle=True)
+
+test_ds = ISOLET("../data", train=False, download=True)
+test_ld = torch.utils.data.DataLoader(test_ds, batch_size=BATCH_SIZE, shuffle=False)
+
+num_features = train_ds[0][0].size(-1)
+num_classes = len(train_ds.classes)
+
+std, mean = torch.std_mean(train_ds.data, dim=0, keepdim=False)
+
+
+def transform(sample):
+    return (sample - mean) / std
+
+
+train_ds.transform = transform
+test_ds.transform = transform
+
+params = {
+    "Vanilla": {},
+    "AdaptHD": {
+        "epochs": 10,
+    },
+    "OnlineHD": {
+        "epochs": 10,
+    },
+    "NeuralHD": {
+        "epochs": 10,
+        "regen_freq": 5,
+    },
+    "DistHD": {
+        "epochs": 10,
+        "regen_freq": 5,
+    },
+    "CompHD": {},
+    "SparseHD": {
+        "epochs": 10,
+    },
+    "QuantHD": {
+        "epochs": 10,
+    },
+    "LeHDC": {
+        "epochs": 10,
+    },
+    "IntRVFL": {},
+}
+
+for classifier in classifiers:
+    print()
+    print(classifier)
+
+    model_cls = getattr(torchhd.classifiers, classifier)
+    model: torchhd.classifiers.Classifier = model_cls(
+        num_features, DIMENSIONS, num_classes, device=device, **params[classifier]
+    )
+
+    model.fit(train_ld)
+    accuracy = model.accuracy(test_ld)
+    print(f"Testing accuracy of {(accuracy * 100):.3f}%")

setup.py

@@ -29,7 +29,7 @@
         "openpyxl",
     ],
     packages=find_packages(exclude=["docs", "torchhd.tests", "examples"]),
-    python_requires=">=3.6, <4",
+    python_requires=">=3.8, <4",
     project_urls={
         "Source": "https://github.com/hyperdimensional-computing/torchhd",
         "Documentation": "https://torchhd.readthedocs.io",

torchhd/__init__.py

@@ -25,6 +25,7 @@
 import torchhd.embeddings as embeddings
 import torchhd.structures as structures
 import torchhd.models as models
+import torchhd.classifiers as classifiers
 import torchhd.memory as memory
 import torchhd.datasets as datasets
 import torchhd.utils as utils
@@ -92,6 +93,7 @@
     "embeddings",
     "structures",
     "models",
+    "classifiers",
     "memory",
     "datasets",
     "utils",