Encoding Base Class

Constructor parameters

All encoding classes share this constructor signature:

Encoding(
    dimension=10_000,
    backend=None,
    device=None,
    dtype=None,
    mask=None,
    generator=None,
    similarity_remap=None,
)

Parameter	Type	Default	Description
`dimension`	`int`	`10_000`	Number of elements per hypervector.
`backend`	`str` or `None`	`None`	`"numpy"` or `"torch"`. `None` inherits the global default (see `prefer_torch()` / `prefer_numpy()`), which is `"numpy"` unless changed.
`device`	`str` or `None`	`None`	PyTorch device string (`"cpu"`, `"cuda"`, `"cuda:1"`, …). Only meaningful when `backend="torch"`.
`dtype`	dtype or `None`	`None`	Override the encoding’s default data type. If `None`, uses the type specified by `EncodingSpec.dtype`.
`mask`	`int` or `None`	`None`	Bit mask for `MAP_I_Bits` must have the form `2**k - 1` and sets the signed bit width `k`. `MAP_I_Bits` also accepts a separate `bit_width` argument that overrides `mask`. Ignored by all other encodings.
`generator`	`HDCGenerator` or `None`	`None`	Custom random generator. If `None`, uses a `DefaultGenerator` backed by NumPy.
`similarity_remap`	`callable` or `None`	`None`	Function applied to every similarity result. E.g., `remap_to_unit()` to map [-1,1] → [0,1].

Properties

property Encoding.dimension: int: Number of elements per hypervector.

property Encoding.backend: str: "numpy" or "torch".

property Encoding.device: str or None: PyTorch device string, or None for the NumPy backend.

Methods

Encoding.generate(size=None, backend=None, device=None, use_generator=None)

Generate one or more hypervectors.

Parameters:

size – None -> single (D,) vector; int -> a single vector of that dimension; tuple (D, N) -> a dimension-first batch of N vectors (each column a hypervector).
backend – Override the encoding’s default backend for this call.
device – Override the encoding’s default device for this call.
use_generator – True forces the custom generator; False forces NumPy’s default; None uses the encoding’s setting.

Returns:

Hypervector

Encoding.zeros(size=None, backend=None, device=None)

Return a zero-valued hypervector or batch.

Returns:: Hypervector

Encoding.from_array(array, backend=None)

Wrap an existing NumPy array or PyTorch tensor as a Hypervector.

Parameters:

array – ndarray or Tensor with last dimension equal to self.dimension.
backend – Override backend detection.

Returns:

Hypervector

Raises:

DimensionsNotMatchingError – If the array’s last dimension ≠ self.dimension.

Encoding.similarity(hvA, hvB=None)

Compute similarity. Accepts Hypervector objects, raw arrays, or lists. If hvB is omitted, hvA must be a (D, N) batch and column 0 is compared against each remaining column. See batched calling conventions.

Parameters:: mode – "pairwise" (default) or "cross". With "cross", a (D, P) batch and a (D, M) batch give the full (P, M) cross-similarity matrix.
Returns:: float, ndarray, Tensor, or list depending on inputs.

Encoding.bundle(*hypervectors, axis=None, batch_dim=None)

Bundle hypervectors. A batched (D, *batch) input is reduced automatically. axis= selects which batch axis to collapse (an int or a tuple of ints, defaulting to the last). Axis 0 is the hypervector dimension and cannot be reduced.

Parameters:

hypervectors – Positional Hypervector arguments, a batched array, or a list of lists for grouped bundling.
axis – Batch axis (or tuple of axes) to reduce.
batch_dim – Deprecated as of 2.1.0; emits DeprecationWarning and will be removed. Pass a batched array or use axis=.

Returns:

Hypervector or list[Hypervector]

Encoding.bind(*hypervectors, batch_dim=None)

Bind hypervectors. Batched inputs are handled automatically. The element-wise binders broadcast, and every other binder is applied per column, returning one batched result.

Parameters:: batch_dim – Deprecated as of 2.1.0, emits DeprecationWarning and will be removed in a future release. Pass a batched array instead.
Returns:: Hypervector

Encoding.unbind(*hypervectors, batch_dim=None)

Unbind to recover a component. Batched inputs are handled automatically, the same way as bind().

Parameters:: batch_dim – Deprecated as of 2.1.0; emits DeprecationWarning and will be removed in a future release. Pass a batched array instead.
Raises:: NotImplementedError – For encodings that do not support unbinding.
Returns:: Hypervector

Encoding.thin(hypervector)

Apply the encoding’s thinning operation.

Returns:: Hypervector or list[Hypervector]

Encoding.set_generator(generator)

Replace the encoding’s generator.

Parameters:: generator – A HDCGenerator instance.

Encoding.get_generator()

Return the current generator.

Returns:: HDCGenerator

Abstract method (for subclassers)

Encoding._get_encoding_spec()

Return an EncodingSpec that wires together the component functions for this encoding.

Returns:: EncodingSpec

EncodingSpec dataclass

class pyhdc.EncodingSpec

Specification dataclass that links an encoding to its component functions.

Field	Description
`dtype`	NumPy data type for elements (e.g., `np.float32`, `np.int8`)
`element_generator`	Callable producing random element values given `(size, dtype)`
`similarity_fn`	Callable implementing the similarity metric
`bundling_fn`	Callable implementing bundling
`thinning_fn`	Callable implementing thinning (or `NoThin` if not applicable)
`binding_fn`	Callable implementing binding
`unbinding_fn`	Callable implementing unbinding
`mask`	Optional integer bit mask (used by `MAP_I_Bits`)
`generator_output_type`	`"bits"`, `"words"`, or `"floats"`: the output type this encoding requires from a custom generator
`permute_fn`	Callable for cyclic-shift permutation. `None` falls back to the shared `CyclicShift` so every encoding supports `permute`
`inverse_fn`	Callable for the binding inverse. Defaults to `RaiseNotImplementedError`
`normalize_fn`	Callable normalizing to the encoding’s entry domain. Defaults to `RaiseNotImplementedError`
`negative_fn`	Callable for the additive (bundling) inverse. Defaults to `RaiseNotImplementedError`

BackendManager

class pyhdc.BackendManager

Static utility for backend detection and conversion.

static get_backend(array): Return "numpy" or "torch" for the given array.

static to_numpy(array): Convert to numpy.ndarray. Detaches from autograd if needed.

static to_torch(array, device=None): Convert to torch.Tensor on the specified device.

static get_device(array): Return the device string of a tensor, or None for NumPy arrays.