pyhdc: Top-Level Module

Version and availability

pyhdc.__version__: str

Current version string, e.g. "2.1.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

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.

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.