VonRosenchild / torchhd

Torchhd is a Python library for Hyperdimensional Computing

Torchhd

Torchhd is a Python library for Hyperdimensional Computing.

• Easy-to-use: Torchhd makes it painless to develop a wide range of Hyperdimensional Computing (HDC) applications and algorithms. For someone new to the field we provide Pythonic abstractions and examples to get you started fast. For the experienced researchers we made the library modular by design, giving you endless flexibility to prototype new ideas in no-time.
• Performant: The library is build on top of the high-performance PyTorch library, giving you optimized tensor execution without the headaches. Moreover, PyTorch makes it effortless to accelerate your code on a GPU.

Installation

Torchhd is hosted on PyPi and Anaconda, use one of the following commands to install:

pip install torch-hd

conda install -c torchhd torchhd

Documentation

You can find documentation for Torchhd on the website.

Check out the Getting Started page for a quick overview.

The API documentation is divided into several sections:

• torchhd.functional
• torchhd.embeddings
• torchhd.structures
• torchhd.datasets

You can improve the documentation by sending pull requests to this repository.

Examples

We have several examples in the repository. Here is a simple one to get you started:

import torch, torchhd

d = 10000  # number of dimensions

# create the hypervectors for each symbol
country = torchhd.random_hv(1, d)
capital = torchhd.random_hv(1, d)
currency = torchhd.random_hv(1, d)

usa = torchhd.random_hv(1, d)  # United States
mex = torchhd.random_hv(1, d)  # Mexico

wdc = torchhd.random_hv(1, d)  # Washington D.C.
mxc = torchhd.random_hv(1, d)  # Mexico City

usd = torchhd.random_hv(1, d)  # US Dollar
mxn = torchhd.random_hv(1, d)  # Mexican Peso

# create country representations
keys = torch.cat([country, capital, currency], dim=0)

us_values = torch.cat([usa, wdc, usd])
US = torchhd.functional.hash_table(keys, us_values)

mx_values = torch.cat([mex, mxc, mxn])
MX = torchhd.functional.hash_table(keys, mx_values)

MX_US = torchhd.bind(US, MX)

# query for the dollar of mexico
usd_of_mex = torchhd.bind(MX_US, usd)

memory = torch.cat([keys, us_values, mx_values], dim=0)
torchhd.functional.cosine_similarity(usd_of_mex, memory)
# tensor([ 0.0133,  0.0062, -0.0115,  0.0066, -0.0007,  0.0149, -0.0034,  0.0084,  0.3334])
# The hypervector for the Mexican Peso is the most similar.

This example is from the paper What We Mean When We Say "What's the Dollar of Mexico?": Prototypes and Mapping in Concept Space by Kanerva. It first creates hypervectors for all the symbols that are used in the computation, i.e., the variables for country, capital, and currency and their values for both countries. These hypervectors are then combined to make a single hypervector for each country using a hash table structure. A hash table encodes key-value pairs as: k1 * v1 + k2 * v2 + ... + kn * vn. The hash tables are then bound together to form their combined representation which is finally queried by binding with the Dollar hypervector to obtain the approximate Mexican Peso hypervector. From the similarity output it shows that the Mexican Peso hypervector is indeed the most similar one.

About

Initial development of Torchhd was performed by Mike Heddes and Igor Nunes as part of their research in Hyperdimensional Computing at the University of California, Irvine. The library was extended with significant contributions from Pere Vergés and Dheyay Desai. Torchhd later merged with a project by Rishikanth Chandrasekaran who worked on similar problems as part of his research at the University of California, San Diego.

Contributing

Documentation

To build the documentation locally, use pip install -r docs/requirements.txt to install the required packages. Then, with sphinx-build -b html docs build you can generate the html documentation in the /build directory. To create a clean build, remove the /build and /docs/generated directories.

Creating a New Release

• A GitHub release triggers a GitHub action that builds the library and publishes it to PyPi and Conda in addition to the documentation website.
• Before creating a new GitHub release, increment the version number in version.py using semantic versioning.
• When creating a new GitHub release, set the tag according to PEP 440, e.g., v1.5.2, and provide a clear description of the changes. You can use GitHub's "auto-generate release notes" button. Look at previous releases for examples.

License

This library is MIT licensed.

Cite

Consider citing our paper if you use Torchhd in your work:

@article{heddes2022torchhd,
  title={Torchhd: An Open-Source Python Library to Support Hyperdimensional Computing Research},
  author={Heddes, Mike and Nunes, Igor and Vergés, Pere and Desai, Dheyay and Givargis, Tony and Nicolau, Alexandru},
  journal={arXiv preprint arXiv:2205.09208},
  year={2022}
}