Exceptions

PyHDC defines a hierarchy of exceptions under HDCException. All of them can be caught with a single except pyhdc.HDCException clause.

Exception hierarchy

Exception
└── HDCException
    ├── DimensionsNotMatchingError
    ├── DtypesNotMatchingError
    ├── GeneratorNotSupportedError
    └── RecoveryError
        ├── RecoveryNotConvergedError
        └── RecoveryNotSupportedError

Note: ValueError and NotImplementedError (Python built-ins) are also raised in some situations: see below.

HDCException

Base class for all PyHDC-specific errors. Catch this to handle any PyHDC error without distinguishing the subtype:

try:
    result = enc.bundle(hv1, hv2)
except pyhdc.HDCException as e:
    print(f"HDC error: {type(e).__name__}: {e}")

DimensionsNotMatchingError

Raised when: two hypervectors involved in an operation (bind, bundle, similarity, unbind) have different dimension values.

How to fix: ensure all hypervectors in an operation were generated by encodings with the same dimension.

a = pyhdc.MAP_C(dimension=10_000).generate()
b = pyhdc.MAP_C(dimension=5_000).generate()

try:
    a.bind(b)
except pyhdc.DimensionsNotMatchingError as e:
    print(e)   # "Dimensions do not match: 10000 != 5000"

DtypesNotMatchingError

Raised when: two hypervectors involved in an operation have incompatible data types.

How to fix: use encodings with compatible dtypes, or wrap raw arrays with enc.from_array() to ensure consistent dtype.

GeneratorNotSupportedError

Raised when: a custom generator is paired with an encoding that requires a different output type (bits, words, or floats).

For example, an LFSR generator (output: bits) cannot be used with MAP_C (requires: floats).

How to fix: check the encoding’s generator_output_type in Encoding Classes and choose a compatible generator family.

from pyhdc.generation import CommonLFSRGenerators

gen = CommonLFSRGenerators.fibonacci_16(seed=1)

try:
    enc = pyhdc.MAP_C(dimension=10_000, generator=gen)
    enc.generate()   # raises here
except pyhdc.GeneratorNotSupportedError:
    # Fall back to a compatible generator
    from pyhdc.generation import CommonPCGGenerators
    gen = CommonPCGGenerators.pcg32(seed=1)
    enc = pyhdc.MAP_C(dimension=10_000, generator=gen)

RecoveryError

Base class for errors from the recovery module (not yet public). You will not encounter these in normal usage.

RecoveryNotConvergedError

Raised when an iterative recovery algorithm does not converge within the maximum number of iterations.

RecoveryNotSupportedError

Raised when recovery is attempted on an encoding that does not support it.

Non-HDCException errors

NotImplementedError

Calling .unbind() on an encoding that does not support it (currently only BSDC_CDT) raises Python’s built-in NotImplementedError:

enc = pyhdc.BSDC_CDT(dimension=10_000)
bound = enc.generate().bind(enc.generate())
try:
    bound.unbind(enc.generate())
except NotImplementedError:
    print("BSDC_CDT does not support unbinding")

ValueError

Backend mismatch: mixing NumPy and PyTorch hypervectors in the same operation: raises Python’s ValueError:

hv_np    = pyhdc.MAP_C(dimension=10_000).generate()
hv_torch = pyhdc.MAP_C(dimension=10_000, backend="torch").generate()
try:
    hv_np.similarity(hv_torch)
except ValueError as e:
    print(e)   # "backend mismatch: ..."