pyhdc: Top-Level Module

Version and availability

pyhdc.__version__: str: Current version string, e.g. "2.2.0".

pyhdc.__author__: str: Primary author identifier, "GNPower".

pyhdc.TORCH_AVAILABLE: bool

True if import torch succeeded at PyHDC import time. False if PyTorch is not installed.

import pyhdc
if pyhdc.TORCH_AVAILABLE:
    enc = pyhdc.MAP_C(backend="torch", device="cuda")

Convenience functions

These functions are thin wrappers that delegate to the first hypervector’s encoding. They are provided for concise one-off calls.

pyhdc.generate(encoding, size, use_generator=None)

Generate one or more hypervectors using encoding.

Parameters:

encoding – An instantiated Encoding object.
size – an int for a single vector of that dimension, or a dimension-first tuple (D, *batch) for a batch. Axis 0 is always the hypervector dimension D, the trailing axes are the batch. (D, N) returns (D, N) (N columns, each a hypervector); (D, N, M) returns (D, N, M) (N * M hypervectors). A non-int / non-tuple size raises ValueError. (The Encoding.generate() method also accepts None to default to the encoding dimension. This module-level wrapper requires size.)
use_generator – Override the encoding’s generator setting. True forces the custom generator, False forces NumPy’s default.

Returns:

A Hypervector.

Reproducibility. Under a fixed seed and a given batch shape, batched generation reproduces itself. With the i.i.d. element generators the whole (D, *batch) array is drawn in one vectorized call, so the result is not value-identical to generating the N vectors one at a time. Ordered generators (LCG, LFSR, and the rest), any custom HDCGenerator, and SparseSegmented use a per-vector loop which does match N successive generate(enc, size=D) calls. See How to Make Experiments Reproducible.

enc = pyhdc.MAP_C(dimension=10_000)
hv  = pyhdc.generate(enc, size=10_000)                 # (10000,)
batch = pyhdc.generate(enc, size=(10_000, 100))        # (10000, 100)
tensor = pyhdc.generate(enc, size=(10_000, 8, 4))      # (10000, 8, 4)

pyhdc.zeros(encoding, size=None)

Return a zero-valued hypervector (or batch) for encoding.

Parameters:

encoding – An instantiated Encoding object.
size – Same as for generate().

Returns:

A Hypervector filled with zeros.

zero = pyhdc.zeros(enc)

pyhdc.bundle(*hypervectors)

Bundle two or more hypervectors using the encoding of the first argument.

Parameters:: hypervectors – Two or more Hypervector objects produced by the same encoding.
Returns:: A Hypervector.

result = pyhdc.bundle(hv1, hv2, hv3)

pyhdc.bind(*hypervectors)

Bind two or more hypervectors using the encoding of the first argument.

Parameters:: hypervectors – Two or more Hypervector objects.
Returns:: A Hypervector.

result = pyhdc.bind(key, value)

pyhdc.unbind(*hypervectors)

Unbind hypervectors using the encoding of the first argument, the inverse of bind().

Parameters:: hypervectors – Two or more Hypervector objects.
Returns:: A Hypervector.

value = pyhdc.unbind(bound, key)

pyhdc.permute(hypervector, shift=1)

Cyclic-shift permutation along axis 0 (the dimension). A negative shift is the exact inverse of the positive shift. permute is defined for every encoding.

Parameters:

hypervector – A Hypervector (vector or batch).
shift – Integer number of positions to roll along axis 0. Default 1.

Returns:

A Hypervector.

shifted = pyhdc.permute(hv, shift=3)
restored = pyhdc.permute(shifted, shift=-3)   # == hv

pyhdc.inverse(hypervector)

Return the binding inverse of hypervector. Raises NotImplementedError for encodings that do not define one (MAP_C, VTB, MBAT, and the BSDC family).

Parameters:: hypervector – A Hypervector.
Returns:: A Hypervector.

inv = pyhdc.inverse(hv)

pyhdc.negative(hypervector)

Return the bundling (additive) inverse of hypervector, element-wise negation. Raises NotImplementedError for encodings that do not define one (FHRR, BSC, and the BSDC family).

Parameters:: hypervector – A Hypervector.
Returns:: A Hypervector.

neg = pyhdc.negative(hv)

pyhdc.normalize(hypervector)

Return the canonical form of hypervector for its encoding (sign for MAP, unit L2 length for HRR/VTB/MBAT, wrapped phase for FHRR). Raises NotImplementedError for encodings that do not define one (BSC and the BSDC family).

Parameters:: hypervector – A Hypervector.
Returns:: A Hypervector.

canon = pyhdc.normalize(hv)

pyhdc.stack(hypervectors)

Combine hypervectors and/or batches into one dimension-first (D, N) batch by concatenating along the batch axis. A 1-D (D,) vector is treated as a single column (D, 1). Backend-agnostic (NumPy or PyTorch).

Parameters:: hypervectors – A list of Hypervector objects (vectors or (D, N) batches) sharing a backend.
Returns:: A single Hypervector of shape (D, total_columns).

proto    = enc.generate()                    # (10000,)
codebook = enc.generate(size=(10_000, 50))   # (10000, 50)
combined = pyhdc.stack([proto, codebook])    # (10000, 51); proto is column 0

pyhdc.similarity(a, b=None, *, axis=None, mode='pairwise')

Compute similarity between hypervectors, delegating to the encoding of a. Pairwise by default. With mode="cross" and a a (D, P) batch and b a (D, M) batch, returns the full (P, M) cross-similarity matrix.

Parameters:

a – A Hypervector (vector or batch).
b – A second Hypervector. If omitted (pairwise only), a must be a (D, N) batch and column 0 is compared against the rest.
axis – For a single (D, N, M, ...) batch, the batch axis to split on.
mode – "pairwise" (default) or "cross".

Returns:

float, ndarray, or Tensor.

A = enc.generate(size=(10_000, 5))
B = enc.generate(size=(10_000, 8))
M = pyhdc.similarity(A, B, mode="cross")   # (5, 8) matrix

Global backend and device defaults

Set a process-wide default backend/device; encodings created without an explicit backend / device argument inherit it.

pyhdc.prefer_torch(device=None): Make PyTorch the default backend (optionally pinning device). Raises ImportError if PyTorch is not installed.

pyhdc.prefer_cuda(index=None): Make PyTorch on CUDA the default ("cuda" or "cuda:{index}"). Raises if PyTorch or CUDA is unavailable.

pyhdc.prefer_numpy(): Reset the default backend to NumPy.

pyhdc.prefer_cpu(): Pin the default device to CPU (relevant when the backend is PyTorch).

pyhdc.get_default_backend(): Return the current default backend, "numpy" or "torch".

pyhdc.get_default_device()

Return the current default device string, or None.

pyhdc.prefer_torch()                  # or pyhdc.prefer_cuda()
enc = pyhdc.MAP_C(dimension=10_000)   # inherits the torch backend
pyhdc.prefer_numpy()                  # reset to numpy

Encoding classes

All encoding classes are imported at the top level:

MAP_C
MAP_I
MAP_I_Bits
MAP_B
HRR

HRR_NoNorm
HRR_ConstNorm
FHRR
VTB
MBAT

BSC
BSDC_CDT
BSDC_S
BSDC_SEG
BSDC_THIN

See Encoding Classes for full documentation of each class.

Data encoders

The Encoder base class and the ten data encoders (Empty, Identity, Random, Level, Thermometer, Circular, Projection, Sinusoid, Density, FractionalPower) are imported at the top level. See Data Encoders.

Exception classes

All exception classes are imported at the top level:

HDCException
DimensionsNotMatchingError
DtypesNotMatchingError
GeneratorNotSupportedError
RecoveryError
RecoveryNotConvergedError
RecoveryNotSupportedError

See Exceptions for details.

Generator base classes

HDCGenerator: abstract base for all generators
DefaultGenerator: NumPy-backed default

See Generation Module for the full family listing.