torch-hd

Torchhd is a Python library for Hyperdimensional Computing and Vector Symbolic Architectures

https://github.com/hyperdimensional-computing/torchhd

Science Score: 54.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
○
DOI references
○
Academic publication links
✓
Committers with academic emails
4 of 17 committers (23.5%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (16.7%) to scientific vocabulary

Keywords

hd-computing hdc hyperdimensional-computing pytorch symbolic-ai vector-symbolic-architectures vsa

Last synced: 6 months ago · JSON representation ·

Repository

Torchhd is a Python library for Hyperdimensional Computing and Vector Symbolic Architectures

Basic Info

Host: GitHub
Owner: hyperdimensional-computing
License: mit
Language: Python
Default Branch: main
Homepage: https://torchhd.readthedocs.io
Size: 54 MB

Statistics

Stars: 324
Watchers: 15
Forks: 29
Open Issues: 12
Releases: 38

Topics

hd-computing hdc hyperdimensional-computing pytorch symbolic-ai vector-symbolic-architectures vsa

Created almost 4 years ago · Last pushed 8 months ago

Metadata Files

Readme License Citation

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 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. First, install PyTorch using their installation instructions. 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.

Check out the Getting Started page for a quick overview.

The API documentation is divided into several sections:

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:

```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

usvalues = torch.stack([usa, wdc, usd]) us = torchhd.hashtable(keys, us_values)

mxvalues = torch.stack([mex, mxc, mxn]) mx = torchhd.hashtable(keys, mx_values)

combine all the associated information

mx_us = torchhd.bind(torchhd.inverse(us), mx)

query for the dollar of mexico

usdofmex = torchhd.bind(mx_us, usd)

memory = torch.cat([keys, usvalues, mxvalues], dim=0) torchhd.cosinesimilarity(usdof_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 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:

We welcome anyone to help with contributing more models to the library!

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

We are always looking for people that want to contribute to the library. If you are considering contributing for the first time we acknowledge that this can be daunting, but fear not! You can look through the open 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:

Use pip install -r docs/requirements.txt to install the required packages.
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

Increment the version number in version.py using semantic versioning.
Create 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.
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 do the following:

Use pip install -r dev-requirements.txt to install the required development packages.
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.

To add the license to all source files, first install licenseheaders and then use licenseheaders -t ./LICENSE -d ./torchhd.

Cite

Consider citing our paper 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} }

Owner

Name: hyperdimensional-computing
Login: hyperdimensional-computing
Kind: organization

Repositories: 1
Profile: https://github.com/hyperdimensional-computing

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this code for your research, please cite our paper."
authors:
- family-names: "Heddes"
  given-names: "Mike"
  orcid: "https://orcid.org/0000-0002-9276-458X"
- family-names: "Nunes"
  given-names: "Igor"
- family-names: "Vergés"
  given-names: "Pere"
- family-names: "Kleyko"
  given-names: "Denis"
- family-names: "Abraham"
  given-names: "Danny"
- family-names: "Givargis"
  given-names: "Tony"
- family-names: "Nicolau"
  given-names: "Alexandru"
- family-names: "Veidenbaum"
  given-names: "Alex"
title: "Torchhd: An Open Source Python Library to Support Research on Hyperdimensional Computing and Vector Symbolic Architectures"
url: "https://github.com/hyperdimensional-computing/torchhd"
preferred-citation:
  type: article
  authors:
  - family-names: "Heddes"
    given-names: "Mike"
    orcid: "https://orcid.org/0000-0002-9276-458X"
  - family-names: "Nunes"
    given-names: "Igor"
  - family-names: "Vergés"
    given-names: "Pere"
  - family-names: "Kleyko"
    given-names: "Denis"
  - family-names: "Abraham"
    given-names: "Danny"
  - family-names: "Givargis"
    given-names: "Tony"
  - family-names: "Nicolau"
    given-names: "Alexandru"
  - family-names: "Veidenbaum"
    given-names: "Alex"
  title: "Torchhd: An Open Source Python Library to Support Research on Hyperdimensional Computing and Vector Symbolic Architectures"
  journal: "Journal of Machine Learning Research"
  start: 1 # First page number
  end: 10 # Last page number
  volume: 24
  year: 2023
  url: http://jmlr.org/papers/v24/23-0300.html

GitHub Events

Total

Create event: 4
Issues event: 14
Release event: 6
Watch event: 82
Issue comment event: 17
Push event: 10
Pull request review event: 8
Pull request review comment event: 5
Pull request event: 5
Fork event: 4

Last Year

Create event: 4
Issues event: 14
Release event: 6
Watch event: 82
Issue comment event: 17
Push event: 10
Pull request review event: 8
Pull request review comment event: 5
Pull request event: 5
Fork event: 4

Committers

Last synced: 11 months ago

All Time

Total Commits: 250
Total Committers: 17
Avg Commits per committer: 14.706
Development Distribution Score (DDS): 0.26

Past Year

Commits: 13
Committers: 3
Avg Commits per committer: 4.333
Development Distribution Score (DDS): 0.308

Top Committers

Name	Email	Commits
Mike Heddes	m**s@g**m	185
Dheyay desai	d**n@u**u	24
github-actions[bot]	g****]	12
denkle	d**o@g**m	10
Milad Rahimi	m**o@G**m	3
igordeoliveiranunes	i**s@g**m	3
pereverges	4****s	3
Igor De Oliveira Nunes	i**d@p**u	1
pereverges	p**s@e**u	1
21leejenny	1****y	1
Caio Vieira	c**z@h**m	1
Danny Ibrahim	3****y	1
Ikko Eltociear Ashimine	e**r@g**m	1
Xiaofan Yu	x**u@u**u	1
linxinyuan	l**n@g**m	1
scken	3****n	1
verges	p**8@g**m	1

Committer Domains (Top 20 + Academic)

ucsd.edu: 1 estudiantat.upc.edu: 1 poison.ics.uci.edu: 1 uci.edu: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 76
Total pull requests: 66
Average time to close issues: 6 months
Average time to close pull requests: 5 days
Total issue authors: 18
Total pull request authors: 12
Average comments per issue: 1.47
Average comments per pull request: 0.89
Merged pull requests: 63
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 4
Pull requests: 6
Average time to close issues: N/A
Average time to close pull requests: 5 days
Issue authors: 4
Pull request authors: 3
Average comments per issue: 0.25
Average comments per pull request: 1.67
Merged pull requests: 6
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

mikeheddes (43)
rgayler (8)
Zeldax64 (4)
pereverges (3)
OMGAmici (2)
rishikanthc (2)
yinchen1233 (2)
m-spr (1)
uler3161 (1)
denkle (1)
ComradeCat1 (1)
anthonykasza (1)
zdx3578 (1)
thomas9t (1)
Conjure12 (1)

Pull Request Authors

mikeheddes (41)
denkle (11)
milad2073 (6)
21leejenny (2)
eltociear (2)
dheyay (2)
Zeldax64 (2)
igordeoliveiranunes (2)
pereverges (1)
Didanny (1)
Orienfish (1)

Top Labels

Issue Labels

enhancement (25) testing (2) bug (2) good first issue (2) documentation (1)

Pull Request Labels

Packages

Total packages: 2
Total downloads:
- pypi 634 last-month
Total docker downloads: 10

Total dependent packages: 1
(may contain duplicates)
Total dependent repositories: 1
(may contain duplicates)
Total versions: 47
Total maintainers: 2

pypi.org: torch-hd

Torchhd is a Python library for Hyperdimensional Computing and Vector Symbolic Architectures

Homepage: https://github.com/hyperdimensional-computing/torchhd
Documentation: https://torchhd.readthedocs.io
License: MIT
Latest release: 5.8.4
published 8 months ago

Versions: 46
Dependent Packages: 1
Dependent Repositories: 1
Downloads: 634 Last month
Docker Downloads: 10

Rankings

Docker downloads count: 4.1%

Dependent packages count: 4.7%

Stargazers count: 6.2%

Forks count: 8.7%

Average: 9.4%

Downloads: 11.0%

Dependent repos count: 21.8%

Maintainers (2)

mikeheddes rishikanthc

Last synced: 6 months ago

conda-forge.org: torch-hd

Homepage: https://github.com/hyperdimensional-computing/torchhd
License: MIT
Latest release: 2.2.2
published over 3 years ago

Versions: 1
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent repos count: 34.0%

Stargazers count: 42.3%

Average: 42.7%

Forks count: 43.4%

Dependent packages count: 51.2%

Last synced: 6 months ago

Dependencies

dev-requirements.txt pypi

black * development
flake8 * development
numpy * development
pandas * development
pytest * development
requests * development
torch * development
torchvision * development

docs/requirements.txt pypi

numpy *
pandas *
requests *
sphinx *
sphinx-rtd-theme *
torch *
torchvision *

setup.py pypi

numpy *
pandas *
requests *
torch *

.github/workflows/format.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

.github/workflows/publish.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite
pypa/gh-action-pypi-publish master composite

.github/workflows/test.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

torch-hd

Science Score: 54.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Torchhd

Installation

Documentation

Examples

create the hypervectors for each symbol

create country representations

combine all the associated information

query for the dollar of mexico

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.

Supported HDC/VSA models

About

Contributing

Documentation

Creating a New Release

Running tests

License

Cite

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: torch-hd

Rankings

Maintainers (2)

conda-forge.org: torch-hd

Rankings

Dependencies