hdlib 2.1.0__py3-none-any.whl

hdlib/__init__.py

@@ -0,0 +1,16 @@
+"""__hdlib__ is a Python 3 library for building Vector-Symbolic Architectures (VSA, a.k.a. Hyperdimensional Computing).
+
+VSA is an emergent computing paradigm that works by combining vectors in a high-dimensional space for representing and 
+processing information. This approach recently shown promise in various domains for dealing with different kind of 
+computational problems, including artificial intelligence, cognitive science, robotics, natural language processing, 
+bioinformatics, medical informatics, cheminformatics, and internet of things among other scientific disciplines.
+
+The library is distributed under the MIT license as a Python package through PyPI and Conda on the _conda-forge_ channel.
+
+Please refer to the official [Wiki](https://github.com/cumbof/hdlib/wiki) for any information about the implemented 
+modules and how to use the library."""
+
+__author__ = ("Fabio Cumbo (fabio.cumbo@gmail.com)")
+
+__version__ = "2.1.0"
+__date__ = "Mar 10, 2026"

hdlib/arithmetic/__init__.py

@@ -0,0 +1,265 @@
+"""Implementation of the MAP arithmetic operators.
+
+This library also provides the same set of arithmetic functions also accessible as _Vector_'s class methods. 
+However, while the result of calling these functions from a _Vector_ object woule be applied in place, 
+invoking the same functions from the _hdlib.arithmetic_ module would initialize new _Vector_ objects."""
+
+import numpy as np
+
+from hdlib.space import Vector
+
+
+def bind(vector1: Vector, vector2: Vector) -> Vector:
+    """Bind vectors.
+
+    Parameters
+    ----------
+    vector1 : Vector
+        The first vector object.
+    vector2: Vector
+        The second vector object.
+
+    Returns
+    -------
+    Vector
+        A new vector object as the result of the bind operator on the two input vectors.
+
+    Raises
+    ------
+    Exception
+        If vectors have different sizes or different vector types.
+
+    Notes
+    -----
+    The bind operator has the following properties:
+    (i) invertible (unbind);
+    (ii) it distributes over bundling;
+    (iii) it preserves the distance;
+    (iv) the resulting vector is dissimilar to the input vectors.
+
+    Examples
+    --------
+    >>> from hdlib.space import Vector
+    >>> from hdlib.arithmetic import bind
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="binary")
+    >>> vector3 = bind(vector1, vector2)
+    >>> type(vector3)
+    <class 'hdlib.space.Vector'>
+
+    The bind function returns a new Vector object whose content is computed as the element-wise 
+    multiplication of the two input vectors.
+
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="bipolar")
+    >>> vector3 = bind(vector1, vector2)
+    Exception: Vector types are not compatible
+
+    The vector type of the two input vector is different and thus the binding cannot be performed.
+
+    >>> vector1 = Vector(size=10000, vtype="bipolar")
+    >>> vector2 = Vector(size=15000, vtype="bipolar")
+    >>> vector3 = bind(vector1, vector2)
+    Exception: Vectors must have the same size
+
+    It also throws an exception in case the size of the two input vectors is not the same.
+    """
+
+    if vector1.size != vector2.size:
+        raise Exception("Vectors must have the same size")
+
+    if vector1.vtype != vector2.vtype:
+        raise Exception("Vector types are not compatible")
+
+    if vector1.vtype == "bipolar":
+        # Element-wise multiplication
+        vector = vector1.vector * vector2.vector
+
+    elif vector1.vtype == "binary":
+        # Element-wise XOR
+        vector = vector1.vector.astype(int) ^ vector2.vector.astype(int)
+
+    tags = set(vector1.tags).union(set(vector2.tags))
+
+    return Vector(size=vector1.size, vector=vector, tags=tags, vtype=vector1.vtype, seed=vector1.seed)
+
+
+def bundle(vector1: Vector, vector2: Vector) -> Vector:
+    """Bundle vectors.
+
+    Parameters
+    ----------
+    vector1 : Vector
+        The first vector object.
+    vector2: Vector
+        The second vector object.
+
+    Returns
+    -------
+    Vector
+        A new vector object as the result of the bundle operator on the two input vectors.
+
+    Raises
+    ------
+    Exception
+        If vectors have different sizes or different vector types.
+
+    Notes
+    -----
+    The bundle operator has the following properties:
+    (i) the resulting vector is similar to the input vectors;
+    (ii) the more vectors are involved in bundling, the harder it is to determine the component vectors;
+    (iii) if several copies of any vector are included in bundling, the resulting vector is closer to the 
+    dominant vector than to the other components.
+
+    Examples
+    --------
+    >>> from hdlib.space import Vector
+    >>> from hdlib.arithmetic import bundle
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="binary")
+    >>> vector3 = budle(vector1, vector2)
+    >>> type(vector3)
+    <class 'hdlib.space.Vector'>
+
+    The bundle function returns a new Vector object whose content is computed as the element-wise sum 
+    of the two input vectors.
+
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="bipolar")
+    >>> vector3 = budle(vector1, vector2)
+    Exception: Vector types are not compatible
+
+    The vector type of the two input vector is different and thus the bundling cannot be performed.
+
+    >>> vector1 = Vector(size=10000, vtype="bipolar")
+    >>> vector2 = Vector(size=15000, vtype="bipolar")
+    >>> vector3 = budle(vector1, vector2)
+    Exception: Vectors must have the same size
+
+    It also throws an exception in case the size of the two input vectors is not the same.
+    """
+
+    if vector1.size != vector2.size:
+        raise Exception("Vectors must have the same size")
+
+    if vector1.vtype != vector2.vtype:
+        raise Exception("Vector types are not compatible")
+
+    if vector1.vtype == "bipolar":
+        # Element-wise addition
+        vector = vector1.vector + vector2.vector
+
+    elif vector1.vtype == "binary":
+        # Element-wise majority vote
+        vector = ((vector1.vector + vector2.vector) > 1).astype(int)
+
+    tags = set(vector1.tags).union(set(vector2.tags))
+
+    return Vector(size=vector1.size, vector=vector, tags=tags, vtype=vector1.vtype, seed=vector1.seed)
+
+
+def subtraction(vector1: Vector, vector2: Vector) -> Vector:
+    """Subtract two vectors.
+
+    Parameters
+    ----------
+    vector1 : Vector
+        The first vector object.
+    vector2: Vector
+        The second vector object.
+
+    Returns
+    -------
+    Vector
+        A new vector object as the result of the subtraction operator on the two input vectors.
+
+    Raises
+    ------
+    Exception
+        - If vectors have different sizes or different vector types;
+        - If vectors type is binary.
+
+    Examples
+    --------
+    >>> from hdlib.space import Vector
+    >>> from hdlib.arithmetic import subtraction
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="binary")
+    >>> vector3 = subtraction(vector1, vector2)
+    >>> type(vector3)
+    <class 'hdlib.space.Vector'>
+
+    The subtraction function returns a new Vector object whose content is computed as the element-wise 
+    subtraction of the two input vectors.
+
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = Vector(size=10000, vtype="bipolar")
+    >>> vector3 = subtraction(vector1, vector2)
+    Exception: Vector types are not compatible
+
+    The vector type of the two input vector is different and thus the subtraction cannot be performed.
+
+    >>> vector1 = Vector(size=10000, vtype="bipolar")
+    >>> vector2 = Vector(size=15000, vtype="bipolar")
+    >>> vector3 = subtraction(vector1, vector2)
+    Exception: Vectors must have the same size
+
+    It also throws an exception in case the size of the two input vectors is not the same.
+    """
+
+    if vector1.size != vector2.size:
+        raise Exception("Vectors must have the same size")
+
+    if vector1.vtype != vector2.vtype:
+        raise Exception("Vector types are not compatible")
+
+    if vector1.vtype == "bipolar":
+        # Element-wise subtraction
+        vector = vector1.vector - vector2.vector
+
+    elif vector1.vtype == "binary":
+        raise Exception("Subtraction is not available for binary vectors")
+
+    return Vector(size=vector1.size, vector=vector, tags=vector1.tags, vtype=vector1.vtype, seed=vector1.seed)
+
+
+def permute(vector: Vector, rotate_by: int=1) -> Vector:
+    """Permute a vector
+
+    Parameters
+    ----------
+    vector : Vector
+        The input vector object.
+    rotate_by: int
+        Rotate the input vector by `rotate_by` positions (the default is 1).
+
+    Returns
+    -------
+    Vector
+        A new vector object as the result of the permute operator on the input vector.
+
+    Notes
+    -----
+    The permute operator has the following properties:
+    (i) invertible;
+    (ii) it distributes over bundling and any elementwise operation;
+    (iii) it preserves the distance;
+    (iv) the resulting vector is dissimilar to the input vectors.
+
+    Examples
+    --------
+    >>> from hdlib.space import Vector
+    >>> from hdlib.arithmetic import permute
+    >>> vector1 = Vector(size=10000, vtype="binary")
+    >>> vector2 = permute(vector1, rotate_by=2)
+    >>> type(vector2)
+    <class 'hdlib.space.Vector'>
+
+    The permute function returns a new Vector object whose content is the same of the input 
+    vector rotated by 2 positions.
+    """
+
+    rolled = np.roll(vector.vector, rotate_by, axis=0)
+
+    return Vector(size=vector.size, vector=rolled, tags=vector.tags, vtype=vector.vtype, seed=vector.seed)