Encoding Classes

All 15 encoding classes inherit from Encoding and share the same constructor signature and method set. See Encoding Base Class for the common interface.

This page documents the encoding-specific parameters and characteristics.

MAP family

class pyhdc.MAP_C(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Multiply-Add-Permute encoding with continuous values.

Uses bipolar values with element-wise multiplication for binding and cosine similarity for comparison.

Parameters:: random_choice_range – Optional float (rho). When set, coordinates whose |pre-aggregate sum| <= rho * sqrt(N/3) are replaced by independent Uniform[-1,1] draws during bundling (band randomization).

Element type: float in [-1, 1], default dtype float32

Extra parameters (in addition to Encoding base parameters):

random_choice_range: float or None (rho): controls band randomization during bundling. Coordinates whose pre-aggregate |sum| falls within the band are replaced by independent Uniform[-1, 1] draws. Reduces systematic bias. Default: None (no band randomization).

Binding: ElementMultiplication (element-wise product, self-inverse)

Bundling: ElementAdditionCut (element-wise sum then clip to [-1, 1])

Similarity: CosineSimilarity → [-1, 1]

Unbind: Yes

Generator output type required: "floats"

class pyhdc.MAP_I(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Multiply-Add-Permute encoding with integer values.

Uses bipolar integer values with element-wise multiplication for binding and cosine similarity for comparison.

Parameters:: random_choice_range – Optional float (rho). When set, coordinates whose |pre-aggregate sum| <= rho * sqrt(N) are replaced by independent {-1, +1} draws during bundling (band randomization).

Element type: int {-1, +1}, default dtype int32

Extra parameters: random_choice_range (same as MAP_C)

Binding: ElementMultiplication

Bundling: ElementAdditionCut

Similarity: CosineSimilarity

Unbind: Yes

Generator output type required: "bits"

class pyhdc.MAP_I_Bits(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int = 4294967295, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Multiply-Add-Permute encoding with bit-limited integer values.

Similar to MAP_I but with configurable bit limits via mask parameter.

Element type: custom-width integer, default dtype int32

Extra parameters:

mask: int: bitmask that defines the integer width. For example, mask=0xFF gives 8-bit integers.

Binding: ElementMultiplication

Bundling: ElementAdditionBits (element-wise sum, then a single saturating clip to the integer range)

Similarity: CosineSimilarity

Unbind: Yes

Generator output type required: "words"

class pyhdc.MAP_B(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Multiply-Add-Permute with bipolar thresholding.

Uses bipolar values with thresholding during bundling.

Parameters:: random_choice_range – Optional float (rho). When set, coordinates whose |bipolar sum| <= rho * sqrt(N) are replaced by independent {-1, +1} draws during bundling (band randomization).

Element type: bipolar {-1, +1}, default dtype int8

Extra parameters: random_choice_range

Binding: ElementMultiplication

Bundling: ElementAdditionBipolarThreshold (element-wise sum, then sign to {-1, +1})

Similarity: CosineSimilarity

Unbind: Yes

Generator output type required: "bits"

HRR family

class pyhdc.HRR(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Holographic Reduced Representation.

Uses circular convolution for binding and normalized bundling.

Parameters:: random_choice_range – Optional float (rho). When set, coordinates whose |pre-norm sum| <= rho * sqrt(N) are replaced by independent N(0,1) draws before normalization (band randomization).

Element type: normal float, default dtype float32

Extra parameters: random_choice_range

Binding: CircularConvolution (via FFT)

Bundling: ElementAdditionNormalized (sum then L2 normalise)

Similarity: CosineSimilarity

Unbind: Yes (via CircularCorrelation)

Generator output type required: "floats"

class pyhdc.HRR_NoNorm(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

HRR without normalized bundling.

Like HRR but bundling does not normalise the result. Vector magnitude grows with the number of bundled items.

class pyhdc.HRR_ConstNorm(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

HRR with constant normalization for bundling.

Like HRR but bundling divides by \(\sqrt{M}\) rather than the L2 norm. Maintains constant expected magnitude.

class pyhdc.FHRR(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Fourier Holographic Reduced Representation.

Uses angular/phase representations with angle-based operations.

Parameters:: random_choice_range – Optional float (rho). When set, coordinates whose phasor magnitude <= rho * sqrt(N/2) are replaced by independent Uniform[-pi, pi] draws (band randomization).

Element type: angles in [-π, π), default dtype float32

Extra parameters: random_choice_range

Binding: ElementAngleAddition (modular angle addition)

Bundling: AnglesOfElementAddition (phasor resultant angle)

Similarity: AngleDistance → [-1, 1]

Unbind: Yes (ElementAngleSubtraction)

Generator output type required: "floats"

Matrix family

class pyhdc.VTB(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Vector-derived Transformation Binding.

Uses vector-derived transformations for binding operations.

Element type: normal float, default dtype float32

Binding: VectorDerivedTransformation (matrix derived from the key vector)

Bundling: ElementAdditionNormalized

Similarity: CosineSimilarity

Unbind: Yes (transpose of the transformation matrix)

Generator output type required: "floats"

class pyhdc.MBAT(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Matrix Binding of Additive Terms.

Uses matrix multiplication for binding operations.

Element type: normal float, default dtype float32

Binding: MatrixMultiplication (random matrix)

Bundling: ElementAdditionNormalized

Similarity: CosineSimilarity

Unbind: Yes; requires get_metadata()["matrices"] from the bound result.

Note

MBAT stores the random binding matrices in the result’s metadata. You must preserve bound_hv.get_metadata() to perform unbinding later.

Generator output type required: "floats"

Binary family

class pyhdc.BSC(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, random_choice_range: float | None = None)[source]

Bases: Encoding

Binary Spatter Code.

Uses binary values with XOR binding and Hamming distance similarity.

Element type: binary {0, 1}, default dtype int8

Extra parameters: random_choice_range

Binding: ExclusiveOr (XOR; exactly self-inverse)

Bundling: ElementAdditionBinaryThreshold (majority vote)

Similarity: HammingDistance → [-1, 1]

Unbind: Yes (exact, not approximate)

Generator output type required: "bits"

Sparse binary family (BSDC)

All BSDC variants use sparse binary vectors (density ≈ 1–5%), bitwise OR for bundling, and Overlap similarity.

class pyhdc.BSDC_CDT(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Binary Sparse Distributed Code with Context-Dependent Thinning.

Uses sparse binary representations with context-dependent thinning.

Binding: AdditiveContextDependentThinning

Bundling: Disjunction (OR; density grows without thinning)

Similarity: Overlap → [-1, 1]

Unbind: No; unbind() raises NotImplementedError

class pyhdc.BSDC_S(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Binary Sparse Distributed Code with Shifting.

Uses sparse binary representations with circular shifting for binding.

Binding: Shifting (circular shift by one position per bind step)

Bundling: Disjunction (OR; density grows)

Similarity: Overlap → [-1, 1]

Unbind: Yes (inverse circular shift)

class pyhdc.BSDC_SEG(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None)[source]

Bases: Encoding

Binary Sparse Distributed Code with Segment Shifting.

Uses sparse segmented representations with segment-wise shifting.

Like BSDC_S but the circular shift is applied independently to each segment of the vector.

class pyhdc.BSDC_THIN(dimension: int = 10000, backend: Literal['numpy', 'torch'] | None = None, device: str | torch.device | None = None, dtype: Any | None = None, mask: int | None = None, generator: HDCGenerator | None = None, similarity_remap: Callable | None = None, density: float = 0.5)[source]

Bases: Encoding

Binary Sparse Distributed Code with post-bundling thinning (BSDC-THIN).

After bundling via bitwise OR, randomly zeros bits to keep the fraction of 1-bits at most density. This controls density growth from repeated bundling.

Parameters:: density – Maximum output density after bundling, defaults to 0.5

Added in v1.1.0

Binding: Shifting (same as BSDC_S)

Bundling: DisjunctionThinned (OR then random thinning to maintain density)

Similarity: Overlap → [-1, 1]

Unbind: Yes (inverse circular shift)

The recommended sparse binary default when you need stable density over many bundle operations.