Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hyperdimensional-computing/torchhd
Torchhd is a Python library for Hyperdimensional Computing and Vector Symbolic Architectures
https://github.com/hyperdimensional-computing/torchhd
hd-computing hdc hyperdimensional-computing pytorch symbolic-ai vector-symbolic-architectures vsa
Last synced: about 8 hours ago
JSON representation
Torchhd is a Python library for Hyperdimensional Computing and Vector Symbolic Architectures
- Host: GitHub
- URL: https://github.com/hyperdimensional-computing/torchhd
- Owner: hyperdimensional-computing
- License: mit
- Created: 2022-05-02T23:32:45.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-18T13:47:22.000Z (6 months ago)
- Last Synced: 2024-04-28T05:17:59.201Z (5 months ago)
- Topics: hd-computing, hdc, hyperdimensional-computing, pytorch, symbolic-ai, vector-symbolic-architectures, vsa
- Language: Python
- Homepage: https://torchhd.readthedocs.io
- Size: 53.9 MB
- Stars: 206
- Watchers: 15
- Forks: 20
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# Torchhd
Torchhd is a Python library for _Hyperdimensional Computing_ (also known as _Vector Symbolic Architectures_).
- **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](https://pytorch.org/) 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](https://pypi.org/project/torch-hd/) and [Anaconda](https://anaconda.org/torchhd/torchhd). First, install PyTorch using their [installation instructions](https://pytorch.org/get-started/locally/). Then, use one of the following commands to install Torchhd:
```bash
pip install torch-hd
```
```bash
conda install -c torchhd torchhd
```
## Documentation
You can find documentation for Torchhd [on the website](https://torchhd.readthedocs.io).
Check out the [Getting Started](https://torchhd.readthedocs.io/en/stable/getting_started.html) page for a quick overview.
The API documentation is divided into several sections:
- [`torchhd`](https://torchhd.readthedocs.io/en/stable/torchhd.html)
- [`torchhd.embeddings`](https://torchhd.readthedocs.io/en/stable/embeddings.html)
- [`torchhd.structures`](https://torchhd.readthedocs.io/en/stable/structures.html)
- [`torchhd.models`](https://torchhd.readthedocs.io/en/stable/models.html)
- [`torchhd.memory`](https://torchhd.readthedocs.io/en/stable/memory.html)
- [`torchhd.datasets`](https://torchhd.readthedocs.io/en/stable/datasets.html)
You can improve the documentation by sending pull requests to this repository.
## Examples
We have several examples [in the repository](https://github.com/hyperdimensional-computing/torchhd/tree/main/examples). Here is a simple one to get you started:
```python
import torch, torchhd
d = 10000 # number of dimensions
# create the hypervectors for each symbol
keys = torchhd.random(3, d)
country, capital, currency = keys
usa, mex = torchhd.random(2, d) # United States and Mexico
wdc, mxc = torchhd.random(2, d) # Washington D.C. and Mexico City
usd, mxn = torchhd.random(2, d) # US Dollar and Mexican Peso
# create country representations
us_values = torch.stack([usa, wdc, usd])
us = torchhd.hash_table(keys, us_values)
mx_values = torch.stack([mex, mxc, mxn])
mx = torchhd.hash_table(keys, mx_values)
# combine all the associated information
mx_us = torchhd.bind(torchhd.inverse(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.cosine_similarity(usd_of_mex, memory)
# tensor([-0.0062, 0.0123, -0.0057, -0.0019, -0.0084, -0.0078, 0.0102, 0.0057, 0.3292])
# 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](https://redwood.berkeley.edu/wp-content/uploads/2020/05/kanerva2010what.pdf) 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. The similarity output shows that the Mexican Peso hypervector is indeed the most similar one.
## Supported HDC/VSA models
Currently, the library supports the following HDC/VSA models:
- [Multiply-Add-Permute (MAP)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.MAPTensor.html)
- [Binary Spatter Codes (BSC)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.BSCTensor.html)
- [Holographic Reduced Representations (HRR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.HRRTensor.html)
- [Fourier Holographic Reduced Representations (FHRR)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.FHRRTensor.html)
- [Binary Sparse Block Codes (B-SBC)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.BSBCTensor.html)
- [Vector-Derived Transformation Binding (VTB)](https://torchhd.readthedocs.io/en/stable/generated/torchhd.VTBTensor.html)
We welcome anyone to help with contributing more models to the library!
## About
Initial development of Torchhd was performed by [Mike Heddes](https://www.mikeheddes.nl/) and [Igor Nunes](https://sites.uci.edu/inunes/) 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
We are always looking for people that want to contribute to the library. If you are considering contributing for the first time we acknowledgde that this can be daunting, but fear not! You can look through the [open issues](https://github.com/hyperdimensional-computing/torchhd/issues) for inspiration on the kind of problems you can work on. If you are a researcher and want to contribute your work to the library, feel free to open a new issue so we can discuss the best strategy for integrating your work.
### Documentation
To build the documentation locally do the following:
1. Use `pip install -r docs/requirements.txt` to install the required packages.
2. Use `sphinx-build -b html docs build` to generate the html documentation in the `/build` directory.
To create a clean build, remove the `/build` and `/docs/generated` directories.
### Creating a New Release
1. Increment the version number in [version.py](https://github.com/hyperdimensional-computing/torchhd/blob/main/torchhd/version.py) using [semantic versioning](https://semver.org).
2. Create a new GitHub release. Set the tag according to [PEP 440](https://peps.python.org/pep-0440/), 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.
3. A GitHub release triggers a GitHub action that builds the library and publishes it to PyPi and Conda in addition to the documentation website.
### Running tests
To run the unit tests located in [`torchhd/tests`](https://github.com/hyperdimensional-computing/torchhd/tree/main/torchhd/tests) do the following:
1. Use `pip install -r dev-requirements.txt` to install the required development packages.
2. Then run the tests using just `pytest`.
Optionally, to measure the code coverage use `coverage run -m --omit="torchhd/tests/**" pytest` to create the coverage report. You can then view this report with `coverage report`.
### License
This library is [MIT licensed](https://github.com/hyperdimensional-computing/torchhd/blob/main/LICENSE).
To add the license to all source files, first install [`licenseheaders`](https://github.com/johann-petrak/licenseheaders) and then use `licenseheaders -t ./LICENSE -d ./torchhd`.
## Cite
Consider citing [our paper](https://jmlr.org/papers/v24/23-0300.html) published in the Journal of Machine Learning Research (JMLR) if you use Torchhd in your work:
```
@article{JMLR:v24:23-0300,
author = {Heddes, Mike and Nunes, Igor and Vergés, Pere and Kleyko, Denis and Abraham, Danny and Givargis, Tony and Nicolau, Alexandru and Veidenbaum, Alex},
title = {Torchhd: An Open Source Python Library to Support Research on Hyperdimensional Computing and Vector Symbolic Architectures},
journal = {Journal of Machine Learning Research},
year = {2023},
volume = {24},
number = {255},
pages = {1--10},
url = {http://jmlr.org/papers/v24/23-0300.html}
}
```