Skip to content

BinaryHypervector

Binary hypervector with bipolar or binary encoding.

vsax.representations.BinaryHypervector

Bases: AbstractHypervector

Binary hypervector with bipolar {-1, +1} or binary {0, 1} values.

BinaryHypervector represents hypervectors using discrete binary values. It supports two modes: - Bipolar: values in {-1, +1} (default, recommended) - Binary: values in {0, 1}

Binary hypervectors are efficient for hardware implementation and provide good performance with XOR binding and majority bundling operations.

Parameters:

Name Type Description Default
vec ndarray

JAX array containing binary values.

 required
bipolar bool

If True, expects {-1, +1} values. If False, expects {0, 1} values.

 True

Raises:

Type Description
ValueError

If vec contains values outside the expected binary set.
Example

import jax.numpy as jnp vec = jnp.array([1, -1, 1, -1]) hv = BinaryHypervector(vec, bipolar=True) normalized = hv.normalize() # No-op for binary assert jnp.array_equal(normalized.vec, vec)

Source code in vsax/representations/binary_hv.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
class BinaryHypervector(AbstractHypervector):
    """Binary hypervector with bipolar {-1, +1} or binary {0, 1} values.

    BinaryHypervector represents hypervectors using discrete binary values.
    It supports two modes:
    - Bipolar: values in {-1, +1} (default, recommended)
    - Binary: values in {0, 1}

    Binary hypervectors are efficient for hardware implementation and provide
    good performance with XOR binding and majority bundling operations.

    Args:
        vec: JAX array containing binary values.
        bipolar: If True, expects {-1, +1} values. If False, expects {0, 1} values.

    Raises:
        ValueError: If vec contains values outside the expected binary set.

    Example:
        >>> import jax.numpy as jnp
        >>> vec = jnp.array([1, -1, 1, -1])
        >>> hv = BinaryHypervector(vec, bipolar=True)
        >>> normalized = hv.normalize()  # No-op for binary
        >>> assert jnp.array_equal(normalized.vec, vec)
    """

    def __init__(self, vec: jnp.ndarray, bipolar: bool = True) -> None:
        """Initialize binary hypervector.

        Args:
            vec: JAX array with binary values.
            bipolar: If True, values should be {-1, +1}.
                    If False, values should be {0, 1}.

        Raises:
            ValueError: If vec contains invalid values for the chosen mode.
        """
        self._bipolar = bipolar

        # Validate binary values
        unique_vals = jnp.unique(vec)

        if bipolar:
            valid_set = jnp.array([-1, 1])
            if not jnp.all(jnp.isin(unique_vals, valid_set)):
                raise ValueError(
                    f"Bipolar binary vector must contain only -1 or +1, "
                    f"got unique values: {unique_vals}"
                )
        else:
            valid_set = jnp.array([0, 1])
            if not jnp.all(jnp.isin(unique_vals, valid_set)):
                raise ValueError(
                    f"Non-bipolar binary vector must contain only 0 or 1, "
                    f"got unique values: {unique_vals}"
                )

        super().__init__(vec)

    def normalize(self) -> "BinaryHypervector":
        """No-op normalization for binary hypervectors.

        Binary hypervectors are already in their normalized form.

        Returns:
            A new BinaryHypervector with the same values.

        Example:
            >>> import jax.numpy as jnp
            >>> vec = jnp.array([1, -1, 1])
            >>> hv = BinaryHypervector(vec)
            >>> normalized = hv.normalize()
            >>> assert jnp.array_equal(normalized.vec, vec)
        """
        return BinaryHypervector(self._vec, bipolar=self._bipolar)

    @property
    def bipolar(self) -> bool:
        """Check if hypervector uses bipolar {-1, +1} encoding.

        Returns:
            True if bipolar, False if binary {0, 1}.
        """
        return self._bipolar

    def to_bipolar(self) -> "BinaryHypervector":
        """Convert to bipolar {-1, +1} representation.

        Returns:
            New BinaryHypervector in bipolar form.

        Example:
            >>> import jax.numpy as jnp
            >>> vec = jnp.array([0, 1, 0, 1])
            >>> hv = BinaryHypervector(vec, bipolar=False)
            >>> bipolar_hv = hv.to_bipolar()
            >>> assert jnp.array_equal(bipolar_hv.vec, jnp.array([-1, 1, -1, 1]))
        """
        if self._bipolar:
            return self
        # Convert {0, 1} to {-1, +1}: 2*x - 1
        bipolar_vec = 2 * self._vec - 1
        return BinaryHypervector(bipolar_vec, bipolar=True)

    def to_binary(self) -> "BinaryHypervector":
        """Convert to binary {0, 1} representation.

        Returns:
            New BinaryHypervector in binary form.

        Example:
            >>> import jax.numpy as jnp
            >>> vec = jnp.array([-1, 1, -1, 1])
            >>> hv = BinaryHypervector(vec, bipolar=True)
            >>> binary_hv = hv.to_binary()
            >>> assert jnp.array_equal(binary_hv.vec, jnp.array([0, 1, 0, 1]))
        """
        if not self._bipolar:
            return self
        # Convert {-1, +1} to {0, 1}: (x + 1) / 2
        binary_vec = (self._vec + 1) // 2
        return BinaryHypervector(binary_vec, bipolar=False)

Attributes

bipolar property

Check if hypervector uses bipolar {-1, +1} encoding.

Returns:

Type Description
bool

True if bipolar, False if binary {0, 1}.

Functions

__init__(vec, bipolar=True)

Initialize binary hypervector.

Parameters:

Name Type Description Default
vec ndarray

JAX array with binary values.

 required
bipolar bool

If True, values should be {-1, +1}. If False, values should be {0, 1}.

 True

Raises:

Type Description
ValueError

If vec contains invalid values for the chosen mode.
Source code in vsax/representations/binary_hv.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def __init__(self, vec: jnp.ndarray, bipolar: bool = True) -> None:
    """Initialize binary hypervector.

    Args:
        vec: JAX array with binary values.
        bipolar: If True, values should be {-1, +1}.
                If False, values should be {0, 1}.

    Raises:
        ValueError: If vec contains invalid values for the chosen mode.
    """
    self._bipolar = bipolar

    # Validate binary values
    unique_vals = jnp.unique(vec)

    if bipolar:
        valid_set = jnp.array([-1, 1])
        if not jnp.all(jnp.isin(unique_vals, valid_set)):
            raise ValueError(
                f"Bipolar binary vector must contain only -1 or +1, "
                f"got unique values: {unique_vals}"
            )
    else:
        valid_set = jnp.array([0, 1])
        if not jnp.all(jnp.isin(unique_vals, valid_set)):
            raise ValueError(
                f"Non-bipolar binary vector must contain only 0 or 1, "
                f"got unique values: {unique_vals}"
            )

    super().__init__(vec)

normalize()

No-op normalization for binary hypervectors.

Binary hypervectors are already in their normalized form.

Returns:

Type Description
BinaryHypervector

A new BinaryHypervector with the same values.
Example

import jax.numpy as jnp vec = jnp.array([1, -1, 1]) hv = BinaryHypervector(vec) normalized = hv.normalize() assert jnp.array_equal(normalized.vec, vec)

Source code in vsax/representations/binary_hv.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def normalize(self) -> "BinaryHypervector":
    """No-op normalization for binary hypervectors.

    Binary hypervectors are already in their normalized form.

    Returns:
        A new BinaryHypervector with the same values.

    Example:
        >>> import jax.numpy as jnp
        >>> vec = jnp.array([1, -1, 1])
        >>> hv = BinaryHypervector(vec)
        >>> normalized = hv.normalize()
        >>> assert jnp.array_equal(normalized.vec, vec)
    """
    return BinaryHypervector(self._vec, bipolar=self._bipolar)

to_bipolar()

Convert to bipolar {-1, +1} representation.

Returns:

Type Description
BinaryHypervector

New BinaryHypervector in bipolar form.
Example

import jax.numpy as jnp vec = jnp.array([0, 1, 0, 1]) hv = BinaryHypervector(vec, bipolar=False) bipolar_hv = hv.to_bipolar() assert jnp.array_equal(bipolar_hv.vec, jnp.array([-1, 1, -1, 1]))

Source code in vsax/representations/binary_hv.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def to_bipolar(self) -> "BinaryHypervector":
    """Convert to bipolar {-1, +1} representation.

    Returns:
        New BinaryHypervector in bipolar form.

    Example:
        >>> import jax.numpy as jnp
        >>> vec = jnp.array([0, 1, 0, 1])
        >>> hv = BinaryHypervector(vec, bipolar=False)
        >>> bipolar_hv = hv.to_bipolar()
        >>> assert jnp.array_equal(bipolar_hv.vec, jnp.array([-1, 1, -1, 1]))
    """
    if self._bipolar:
        return self
    # Convert {0, 1} to {-1, +1}: 2*x - 1
    bipolar_vec = 2 * self._vec - 1
    return BinaryHypervector(bipolar_vec, bipolar=True)

to_binary()

Convert to binary {0, 1} representation.

Returns:

Type Description
BinaryHypervector

New BinaryHypervector in binary form.
Example

import jax.numpy as jnp vec = jnp.array([-1, 1, -1, 1]) hv = BinaryHypervector(vec, bipolar=True) binary_hv = hv.to_binary() assert jnp.array_equal(binary_hv.vec, jnp.array([0, 1, 0, 1]))

Source code in vsax/representations/binary_hv.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def to_binary(self) -> "BinaryHypervector":
    """Convert to binary {0, 1} representation.

    Returns:
        New BinaryHypervector in binary form.

    Example:
        >>> import jax.numpy as jnp
        >>> vec = jnp.array([-1, 1, -1, 1])
        >>> hv = BinaryHypervector(vec, bipolar=True)
        >>> binary_hv = hv.to_binary()
        >>> assert jnp.array_equal(binary_hv.vec, jnp.array([0, 1, 0, 1]))
    """
    if not self._bipolar:
        return self
    # Convert {-1, +1} to {0, 1}: (x + 1) / 2
    binary_vec = (self._vec + 1) // 2
    return BinaryHypervector(binary_vec, bipolar=False)