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

exception pyhdc.HDCException[source]

Bases: Exception

Base exception for HDC library.

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

exception pyhdc.DimensionsNotMatchingError(dim1: int, dim2: int, operation: str = 'operation')[source]

Bases: HDCException

Raised when hypervector dimensions don’t match for an operation.

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

exception pyhdc.DtypesNotMatchingError(dtype1, dtype2, operation: str = 'operation')[source]

Bases: HDCException

Raised when hypervector data types don’t match for an operation.

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

exception pyhdc.GeneratorNotSupportedError[source]

Bases: HDCException

Raised when a generator doesn’t support required operations.

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

exception pyhdc.RecoveryError[source]

Bases: HDCException

Base exception for recovery-related errors.

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

RecoveryNotConvergedError

exception pyhdc.RecoveryNotConvergedError(iterations: int, max_iterations: int)[source]

Bases: RecoveryError

Raised when recovery algorithm doesn’t converge.

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

RecoveryNotSupportedError

exception pyhdc.RecoveryNotSupportedError[source]

Bases: RecoveryError

Raised when recovery is not supported for an encoding.

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: ..."