Update README and formatting + new release

Author: mikeheddes

README.md

@@ -1,17 +1,91 @@
-# Hyperdimensional Computing Library
+<h1 align="center">
+    <a href="https://mikeheddes.github.io/hdc-lib">Hyperdimensional Computing Library</a><br/>
 
-The `hdc` library is a comprehensive package for all hyperdimensional computing related tasks.
+</h1>
+<p align="center">
+    <a href="https://github.com/mikeheddes/hdc-lib/blob/main/LICENSE">
+    <img alt="GitHub license" src="https://img.shields.io/badge/license-MIT-orange.svg?style=flat" /></a>
+    <a href="https://pypi.org/project/hdc/"><img alt="pypi version" src="https://img.shields.io/pypi/v/hdc.svg?style=flat&color=orange" /></a>
+    <a href="https://github.com/mikeheddes/hdc-lib/actions/workflows/test.yml?query=branch%3Amain"><img alt="tests status" src="https://img.shields.io/github/workflow/status/mikeheddes/hdc-lib/Testing/main?label=tests&style=flat" /></a>
+    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" />
+</p>
+
+This is a Python library for Hyperdimensional Computing.
+
+* **Easy-to-use:** This library 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
 
+The library is hosted on PyPi and Conda, use one of the following commands to install:
+
 ```bash
-# Note: torch is a prerequisite of hdc, see: https://pytorch.org/get-started/locally/ for an installation guide.
 pip install hdc
 ```
 
-## Creating a new release
+```bash
+conda install -c conda-forge hdc
+```
+
+## Documentation
+
+You can find the library's documentation [on the website](https://mikeheddes.github.io/hdc-lib).
+
+## Examples
+
+We have several examples [in the repository](/examples/). Here is a simple one to get you started:
+
+```python
+import hdc
+import torch
+
+d = 10000  # number of dimensions
+
+### create a hypervector for each symbol
+# keys for each field of the dictionary: fruit, weight, and season
+keys = hdc.functional.random_hv(3, d)
+# fruits are: apple, lemon, mango
+fruits = hdc.functional.random_hv(3, d)
+# there are 10 weight levels
+weights = hdc.functional.level_hv(10, d)
+# the for seasons: winter, spring, summer, fall
+seasons = hdc.functional.circular_hv(4, d)
+
+# map a float between min, max to an index of size 10
+# we map the 10 weight levels between 0 to 200 grams
+weight_index = hdc.functional.value_to_index(149.0, 0, 200, 10)
+
+values = torch.stack([
+    fruits[0],
+    weights[weight_index],
+    seasons[3],
+])
+# creates a dictionary: 
+# record = key[0] * value[0] + key[1] * value[1] + key[2] * value[2]
+record = hdc.functional.struct(keys, values)
+
+#### Similar Python code
+# 
+# record = dict(
+#     fruit="apple", 
+#     weight=149.0,
+#     season="fall"
+# )
+# 
+```
+
+This example creates a hypervector that represents the record of a fruit, storing its species, weight, and growing season as one hypervector. This is achieved by combining the atomic information units into a structure (similar to a Python dictionary).
+
+You will notice that we first declare all the symbols which are used to represent information. Note the type of hypervector used for each type of information, the fruits and keys use random hypervectors as they represent unrelated information whereas the weights and seasons use level and circular-hypervectors because they have linear and circular-correlations, respectively.
+
+## Contributing
+
+### 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 [setup.py](/setup.py) using [semantic versioning](https://semver.org).
+- When creating a new GitHub release, set the tag to be "v{version number}", e.g., v1.5.2, and provide a clear description of the changes.
 
-- Before creating a new release, increment the version number by 0.1 to have the workflow update the PyPi documentation.
-- On creating a new release, set the tag to be "v{version number}". Example: v0.5
+### License
 
-New release should update both the PyPi library as well as documentation website.
+This library is [MIT licensed](./LICENSE).

hdc/datasets/airfoil_self_noise.py

@@ -7,6 +7,7 @@
 import math
 from .utils import download_file, unzip_file
 
+
 class AirfoilSelfNoise(data.Dataset):
     """NASA data set <https://archive.ics.uci.edu/ml/datasets/airfoil+self-noise>`_, obtained from a series of aerodynamic and acoustic tests of two and three-dimensional airfoil blade sections conducted in an anechoic wind tunnel.
 
@@ -21,6 +22,7 @@ class AirfoilSelfNoise(data.Dataset):
         target_transform (callable, optional): A function/transform that takes in the
             target and transforms it.
     """
+
     def __init__(
         self,
         root: str,
@@ -69,22 +71,25 @@ def __getitem__(self, index: int) -> Tuple[torch.FloatTensor, torch.FloatTensor]
             label = self.target_transform(label)
 
         return sample, label
-    
+
     def _check_integrity(self) -> bool:
         if not os.path.isdir(self.root):
             return False
-        
+
         # Check if root directory contains the required data file
-        has_data_file = os.path.isfile(os.path.join(self.root, "airfoil_self_noise.dat"))
+        has_data_file = os.path.isfile(
+            os.path.join(self.root, "airfoil_self_noise.dat")
+        )
         if has_data_file:
             return True
-        
+
         return False
 
     def _load_data(self):
         file_name = "airfoil_self_noise.dat"
-        data = pd.read_csv(os.path.join(self.root, file_name), 
-                    delim_whitespace=True, header=None)
+        data = pd.read_csv(
+            os.path.join(self.root, file_name), delim_whitespace=True, header=None
+        )
         self.data = torch.tensor(data.values[:, :-1], dtype=torch.float)
         self.targets = torch.tensor(data.values[:, -1], dtype=torch.float)
 
@@ -94,13 +99,10 @@ def download(self):
         if self._check_integrity():
             print("Files already downloaded and verified")
             return
-        
+
         zip_file_path = os.path.join(self.root, "airfoil_self_noise.dat")
 
         download_file(
             "https://archive.ics.uci.edu/ml/machine-learning-databases/00291/airfoil_self_noise.dat",
-             zip_file_path)
-
-        
-
-
+            zip_file_path,
+        )

hdc/datasets/pamap.py

@@ -230,7 +230,7 @@ def _load_data(self):
             features = torch.tensor(data.values, dtype=torch.long)
             clean_labels = torch.cat((clean_labels, labels))
             clean_features = torch.cat((clean_features, features))
-        
+
         self.data = clean_features
         self.targets = clean_labels
 

setup.py

@@ -1,11 +1,23 @@
+"""A setuptools based setup module.
+See:
+https://packaging.python.org/guides/distributing-packages-using-setuptools/
+https://github.com/pypa/sampleproject
+"""
 from setuptools import setup
 
 setup(
     name="hdc",
-    version="0.4",
-    description="A python library for hyperdimensional computing",
+    version="0.5.0",
+    description="Python library for Hyperdimensional Computing",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
     url="https://github.com/mikeheddes/hdc-lib",
     license="MIT",
+    install_requires=open("requirements.txt").readlines(),
     packages=["hdc"],
-    zip_safe=False,
+    python_requires=">=3.6, <4",
+    project_urls={
+        "Source": "https://github.com/mikeheddes/hdc-lib/",
+        "Documentation": "https://mikeheddes.github.io/hdc-lib/",
+    },
 )