Exceptions
==========

.. currentmodule:: pyhdc

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

Exception hierarchy
--------------------

.. code-block:: text

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

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

HDCException
------------

.. autoexception:: HDCException

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

.. code-block:: python

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

DimensionsNotMatchingError
---------------------------

.. autoexception:: 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``.

.. code-block:: python

   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
-----------------------

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

.. autoexception:: 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
:doc:`encodings` and choose a compatible generator family.

.. code-block:: python

   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
-------------

.. autoexception:: RecoveryError

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

RecoveryNotConvergedError
--------------------------

.. autoexception:: RecoveryNotConvergedError

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

RecoveryNotSupportedError
--------------------------

.. autoexception:: 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``:

.. code-block:: python

   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``:

.. code-block:: python

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