Components Module

The pyhdc.components module contains the low-level building blocks used internally by all encodings. Most users do not need to import these directly; they are assembled automatically by the encoding classes via EncodingSpec.

Use the components module when:

Writing a custom encoding subclass
Applying a specific operation outside an encoding context
Using remap_to_unit for post-processing

pyhdc.components.similarity

pyhdc.components.similarity.CosineSimilarity(*hypervectors: ndarray | torch.Tensor)[source]

CosineSimilarity Cosine Similarity of hypervectors

cos(theta) = ( A dot B ) / ( norm(A) * norm(B) )

Hypervectors are dimension-first (D, N) (each column is a hypervector). Supports three calling conventions:

(a, b) where a and b are 1D: returns a scalar in [-1, 1] (a, b) where a and b are (D, N): returns a 1D array of per-column scores (arr,) where arr is (D, N): returns a 1D array of sim(col_0, col_i)

for i in 1..N-1

Parameters:: *hypervectors – Two 1D/2D hypervectors, or a single (D, N) array
Returns:: Scalar similarity, or 1D array of similarities

Cosine similarity between two vectors or batches.

Returns:: float, ndarray, or Tensor in [-1, 1]. Operates column-wise over axis 0 of a (D, N) batch. See the batched calling conventions.

pyhdc.components.similarity.HammingDistance(*hypervectors: ndarray | torch.Tensor)[source]

HammingDistance Hamming Distance of hypervectors

Counts the number of elements where A[i] != B[i], normalized to the hypervector dimension and mapped to [-1, 1] where 1 is identical, -1 is completely different, and 0 is half-matching.

Hypervectors are dimension-first (D, N) (each column is a hypervector). Supports three calling conventions:

(a, b) where a and b are 1D: returns a scalar in [-1, 1] (a, b) where a and b are (D, N): returns a 1D array of per-column scores (arr,) where arr is (D, N): returns a 1D array of sim(col_0, col_i)

for i in 1..N-1

Parameters:: *hypervectors – Two 1D/2D hypervectors, or a single (D, N) array
Returns:: Scalar similarity, or 1D array of similarities

Normalised Hamming distance, mapped to [-1, 1].

Appropriate for dense binary vectors (BSC encoding).

Returns:: Value in [-1, 1]. (Was [0, 1] in v1.0.x.)

pyhdc.components.similarity.Overlap(*hypervectors: ndarray | torch.Tensor)[source]

Overlap similarity for sparse binary vectors, normalized by nonzeros in B.

Counts the elements where both A[i] and B[i] are 1, normalized to the number of nonzero elements in the reference (second) hypervector B and mapped to [-1, 1] where 1 is identical, -1 is no overlap, and 0 is 50% overlap. Normalizing against B means the best results come from passing the bundled hypervector as A and the reference as B.

Hypervectors are dimension-first (D, N) (each column is a hypervector). Supports three calling conventions:

(a, b) where a and b are 1D: returns a scalar in [-1, 1] (a, b) where a and b are (D, N): returns a 1D array of per-column scores (arr,) where arr is (D, N): returns a 1D array of sim(col_0, col_i)

for i in 1..N-1, normalized by each col_i

Parameters:: *hypervectors – Two 1D/2D hypervectors, or a single (D, N) array
Returns:: Scalar similarity, or 1D array of similarities

Normalised overlap (set intersection), mapped to [-1, 1].

Appropriate for sparse binary vectors (BSDC family).

Returns:: Value in [-1, 1]. (Was [0, 1] in v1.0.x.)

pyhdc.components.similarity.AngleDistance(*hypervectors: ndarray | torch.Tensor)[source]

AngleDistance Angle Distance of phase hypervectors

Calculates the average angular distance of two complex hypervectors of unit length, normalized to the hypervector dimension so it is in [-1, 1].

Hypervectors are dimension-first (D, N) (each column is a hypervector). Supports three calling conventions:

(a, b) where a and b are 1D: returns a scalar in [-1, 1] (a, b) where a and b are (D, N): returns a 1D array of per-column scores (arr,) where arr is (D, N): returns a 1D array of sim(col_0, col_i)

for i in 1..N-1

Parameters:: *hypervectors – Two 1D/2D hypervectors, or a single (D, N) array
Returns:: Scalar similarity, or 1D array of similarities

Cosine of element-wise angle differences.

Appropriate for phase/angle encodings (FHRR).

Returns:: Value in [-1, 1].

pyhdc.components.similarity.remap_to_unit(sim: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Remap similarity from [-1, 1] to [0, 1].

Maps the standard [-1, 1] similarity range to [0, 1], where 0.5 is orthogonal, 1.0 is identical, and 0.0 is completely opposite. Works on scalars, numpy arrays, and torch tensors.

Pass to an encoding via the similarity_remap parameter:

enc = BSC(dimension=10_000, similarity_remap=remap_to_unit)

Parameters:: sim – Similarity value(s) in [-1, 1]
Returns:: Remapped value(s) in [0, 1]

Map a similarity value from [-1, 1] to [0, 1]: (sim + 1) / 2.

Parameters:: sim – Scalar, ndarray, or Tensor.
Returns:: Same type as input, values in [0, 1].

pyhdc.components.binding

pyhdc.components.binding.ElementMultiplication(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Element-wise multiplication binding.

Binds hypervectors by multiplying corresponding elements. Commonly used with MAP encodings (bipolar values).

Parameters:: *hypervectors – Variable number of hypervectors to bind, or single 2D batch
Returns:: Bound hypervector

Example

>>> v1 = np.array([1, -1, 1, -1])
>>> v2 = np.array([1, 1, -1, -1])
>>> result = ElementMultiplication(v1, v2)
>>> # result: [1, -1, -1, 1]

Element-wise product of bipolar vectors. Self-inverse. Used by MAP family.

pyhdc.components.binding.CircularConvolution(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Circular convolution binding.

Binds hypervectors using circular convolution in the frequency domain. Used in Holographic Reduced Representations (HRR).

Parameters:: *hypervectors – Variable number of hypervectors to bind, or single 2D batch
Returns:: Bound hypervector

Note

Binding is performed iteratively for more than 2 vectors: bind(A, B, C) = bind(bind(A, B), C)

Circular convolution via FFT. Used by HRR family for binding.

pyhdc.components.binding.CircularCorrelation(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Circular correlation (unbinding operation for circular convolution).

Unbinds hypervectors by performing circular correlation, which is the approximate inverse of circular convolution.

Parameters:: *hypervectors – Variable number of hypervectors, or single 2D batch
Returns:: Unbound hypervector

Note

For unbinding bind(A, B) with B, compute: correlate(bind(A, B), B) â‰ˆ A

Circular correlation via FFT. Used by HRR family for unbinding.

pyhdc.components.binding.ExclusiveOr(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

XOR binding for binary hypervectors.

Binds binary hypervectors using exclusive OR. Used with Binary Spatter Codes (BSC) and other binary encodings. XOR is its own inverse.

Parameters:: *hypervectors – Variable number of binary hypervectors, or single 2D batch
Returns:: Bound binary hypervector

Example

>>> v1 = np.array([1, 0, 1, 0])
>>> v2 = np.array([1, 1, 0, 0])
>>> result = ExclusiveOr(v1, v2)
>>> # result: [0, 1, 1, 0]

Element-wise XOR. Exactly self-inverse. Used by BSC.

pyhdc.components.binding.Shifting(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Binding by circular shifting.

Binds sparse binary hypervectors by rotating positions based on a hash of the previous vector. Used with Binary Sparse Distributed Codes (BSDC).

Parameters:: *hypervectors – Variable number of sparse binary hypervectors, or single 2D batch
Returns:: Bound hypervector

Circular shift by one position. Used by BSDC_S, BSDC_THIN for binding.

pyhdc.components.binding.InverseShifting(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Unbinding operation for shift-based binding.

Reverses the circular shifts applied during binding.

Parameters:: *hypervectors – Variable number of hypervectors, or single 2D batch
Returns:: Unbound hypervector

Circular shift in the reverse direction. Used for unbinding in BSDC_S.

pyhdc.components.binding.SegmentShifting(*hypervectors: ndarray | torch.Tensor, probability: float | None = None) → ndarray | torch.Tensor[source]

Segment-based circular shifting for binding.

Divides hypervectors into segments and applies different rotations to each segment based on the content of previous vectors.

Parameters:

*hypervectors – Variable number of sparse binary hypervectors, or single 2D batch
probability – Probability parameter controlling number of segments

Returns:

Bound hypervector

Per-segment circular shift. Used by BSDC_SEG for binding.

pyhdc.components.binding.InverseSegmentShifting(*hypervectors: ndarray | torch.Tensor, probability: float | None = None) → ndarray | torch.Tensor[source]

Unbinding operation for segment-based shifting.

Parameters:

*hypervectors – Variable number of hypervectors, or single 2D batch
probability – Probability parameter (must match binding)

Returns:

Unbound hypervector

Per-segment inverse shift. Used by BSDC_SEG for unbinding.

pyhdc.components.binding.AdditiveContextDependentThinning(*hypervectors: ndarray | torch.Tensor, probability: float | None = None, seed: int | None = None) → ndarray | torch.Tensor[source]

Context-dependent thinning for sparse hypervectors.

Binds sparse vectors while controlling density through selective thinning based on context. Used with BSDC encodings.

Parameters:

*hypervectors – Variable number of sparse binary hypervectors, or single 2D batch
probability – Probability parameter for thinning
seed – Random seed for reproducibility

Returns:

Bound and thinned hypervector

Note

This requires the Disjunction operation from bundling module

CDT binding. Not invertible. Used by BSDC_CDT.

pyhdc.components.binding.VectorDerivedTransformation(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Vector-Derived Transformation Binding.

Binds vectors using the equation: B_v(y, x) = V_y * x where V_y is a matrix derived from vector y.

For multiple vectors [x1, x2, x3, …, xn]: B_v(x1, x2, x3, …, xn) = V_xn * V_x(n-1) * … * V_x2 * x1

Parameters:: *hypervectors – Variable number of hypervectors to bind, or single 2D batch
Returns:: Bound hypervector

Note

Requires hypervector dimension to be a perfect fourth power (d = k^4)

Matrix derived from key vector, applied to value. Used by VTB for binding.

pyhdc.components.binding.TransposeVectorDerivedTransformation(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Pseudo-inverse for Vector-Derived Transformation (unbinding).

Unbinds vectors using: B+_v(y, x) = V_y^T * x where V_y^T is the transpose of the V_y matrix.

Parameters:: *hypervectors – Variable number of hypervectors, or single 2D batch
Returns:: Unbound hypervector

Transpose of VDT matrix. Used by VTB for unbinding.

Matrix-based binding using random orthogonal matrices.

Binds hypervectors by transforming them with random matrices. Returns both the bound result and the matrices for later unbinding.

Parameters:

*hypervectors – Variable number of hypervectors to bind, or single 2D batch
matrices – Optional pre-generated matrices. If None, generates new ones.
seed – Random seed for reproducible matrix generation

Returns:

Tuple of (bound hypervector, list of matrices)

Note

Requires N-1 matrices to bind N hypervectors

Random matrix multiplication. Used by MBAT for binding. Returns (result, matrices); matrices must be saved for unbinding.

pyhdc.components.binding.InverseMatrixMultiplication(*hypervectors: ndarray | torch.Tensor, matrices: List[ndarray | torch.Tensor]) → ndarray | torch.Tensor[source]

Unbinding operation for matrix-based binding.

Recovers the original hypervector using the stored matrices.

Parameters:

*hypervectors – Variable number of hypervectors (bound result + unbinding keys)
matrices – List of matrices used during binding

Returns:

Unbound hypervector

Matrix inverse multiplication. Used by MBAT for unbinding.

pyhdc.components.binding.ElementAngleAddition(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Binding by adding phase angles.

Used with Fourier Holographic Reduced Representations (FHRR) where hypervector elements represent phase angles.

Parameters:: *hypervectors – Variable number of phase hypervectors, or single 2D batch
Returns:: Bound hypervector with phases in [0, 2Ï€)

Element-wise modular angle addition. Used by FHRR for binding.

pyhdc.components.binding.ElementAngleSubtraction(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Unbinding by subtracting phase angles.

Inverse operation for ElementAngleAddition.

Parameters:: *hypervectors – Variable number of phase hypervectors, or single 2D batch
Returns:: Unbound hypervector with phases in [0, 2Ï€)

Element-wise modular angle subtraction. Used by FHRR for unbinding.

pyhdc.components.bundling

pyhdc.components.bundling.ElementAddition(*hypervectors: ndarray | torch.Tensor, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Element-wise addition bundling.

Bundles hypervectors by summing corresponding elements. The simplest bundling operation that preserves information from all inputs.

When random_choice_range is set, coordinates whose |sum| falls within rho * sqrt(N) are replaced by independent fair draws from {-1, +1} (band randomization for MAP_I bipolar integer encoding). Defaulting random_choice_range to 0.0 limits this to exact zero-sums only.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
random_choice_range – Optional float (rho). Coordinates with |sum| <= rho * sqrt(N) are randomly assigned. Defaults to 0.0 (zero-ties only).

Returns:

Tuple of (bundled hypervector, metadata dict). Metadata contains “random_zone_count”.

Example

>>> v1 = np.array([1, -1, 1, -1])
>>> v2 = np.array([1, 1, -1, -1])
>>> result, _ = ElementAddition(v1, v2)
>>> # result: [2, 0, 0, -2]

Element-wise sum; no normalisation.

pyhdc.components.bundling.ElementAdditionCut(*hypervectors: ndarray | torch.Tensor, min_val: float = -1.0, max_val: float = 1.0, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Element-wise addition with clipping.

Bundles hypervectors by summing elements and clipping the result to [min_val, max_val] range. Prevents unbounded growth in element values.

When random_choice_range is set, coordinates whose |sum| falls within rho * sqrt(N) * element_std (where element_std = 1/sqrt(3) for Uniform[-1,1]) are replaced by independent fair draws from Uniform[min_val, max_val] (band randomization for MAP_C continuous encoding). Defaulting random_choice_range to 0.0 limits this to exact zero-sums only.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
min_val – Minimum element value after bundling
max_val – Maximum element value after bundling
random_choice_range – Optional float (rho). Coordinates with |sum| <= rho * sqrt(N/3) are randomly assigned. Defaults to 0.0 (zero-ties only).

Returns:

Tuple of (bundled and clipped hypervector, metadata dict). Metadata contains “random_zone_count”.

Element-wise sum then clip to [-1, 1]. Used by MAP_C.

pyhdc.components.bundling.ElementAdditionBits(*hypervectors: ndarray | torch.Tensor, min_val: int = -1, max_val: int = 1) → ndarray | torch.Tensor[source]

Element-wise addition with per-step clipping (bit-limited).

Bundles hypervectors by iteratively adding and clipping after each addition. Useful for fixed-point or integer arithmetic where overflow must be prevented.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
min_val – Minimum element value (clipped after each addition)
max_val – Maximum element value (clipped after each addition)

Returns:

Bundled hypervector with per-step clipping

Element-wise sum with integer bit-width clipping. Used by MAP_I_Bits, MAP_B.

pyhdc.components.bundling.ElementAdditionBinaryThreshold(*hypervectors: ndarray | torch.Tensor, min_val: float = 0.0, max_val: float = 1.0, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Element-wise addition with binary thresholding.

Bundles binary hypervectors by majority voting. Elements that appear in more than half of the input vectors are set to max_val, others to min_val.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
min_val – Value for elements below threshold
max_val – Value for elements at or above threshold
random_choice_range – Optional float [0.0, 1.0] specifying the fraction of total vectors that defines the random choice zone around the threshold. Elements with sums outside this range are deterministically assigned, while elements within the range are randomly assigned.

Returns:

Tuple of (bundled binary hypervector, metadata dict) Metadata contains:

”random_zone_count”: number of elements in random choice zone

Note: “operation” key is added by encoding wrapper, not this function.

Example

>>> v1 = np.array([1, 0, 1, 0])
>>> v2 = np.array([1, 1, 0, 0])
>>> v3 = np.array([1, 0, 0, 1])
>>> result, metadata = ElementAdditionBinaryThreshold(v1, v2, v3)
>>> # result: [1, 0, 0, 0] (1 appears in 3/3, 2/3, 1/3, 1/3 positions)

Majority-vote threshold. Used by BSC.

pyhdc.components.bundling.ElementAdditionBipolarThreshold(*hypervectors: ndarray | torch.Tensor, min_val: float = -1.0, max_val: float = 1.0, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Element-wise addition with bipolar thresholding.

Bundles bipolar hypervectors {-1, +1} by thresholding at zero. Positive sums become max_val, negative sums become min_val.

Coordinates whose |sum| falls within random_choice_range * sqrt(N) of zero (the band) are replaced by independent fair draws from {min_val, max_val}. Defaulting random_choice_range to 0.0 limits this to exact ties only, preserving the standard majority-vote behavior.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
min_val – Value for elements with negative sum
max_val – Value for elements with non-negative sum
random_choice_range – Optional float (rho). Coordinates with |sum| <= rho * sqrt(N) are randomly assigned. Defaults to 0.0 (ties only).

Returns:

Tuple of (bundled bipolar hypervector, metadata dict). Metadata contains “random_zone_count”.

Sum then sign function. Result in {-1, +1}.

pyhdc.components.bundling.ElementAdditionNormalized(*hypervectors: ndarray | torch.Tensor, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Element-wise addition with normalization to unit length.

Bundles hypervectors by summing elements and normalizing the result to have magnitude 1. Used in HRR and related encodings.

HRR elements are N(0, 1/D) per Schlegel et al. (2022), so the pre-aggregate T_k = sum of N iid N(0, 1/D) values has std sqrt(N/D). When random_choice_range (rho) is set, coordinates whose |T_k| <= rho * sqrt(N/D) are replaced by independent N(0, 1/D) draws before normalization (band randomization). This keeps fresh draws at the same scale as individual input elements, consistent with the GU/GB theory.

Parameters:

*hypervectors – Variable number of hypervectors to bundle, or single 2D batch
random_choice_range – Optional float (rho). Coordinates with |sum| <= rho * sqrt(N/D) are randomly replaced. Defaults to 0.0.

Returns:

Tuple of (bundled and normalized hypervector, metadata dict). Metadata contains “random_zone_count”.

Note

Result will have ||result|| = 1

Sum then L2 normalise. Used by HRR, VTB, MBAT.

pyhdc.components.bundling.ElementAdditionConstantNormalized(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Element-wise addition with approximate constant normalization.

Bundles hypervectors by summing elements and dividing by sqrt(M) where M is the number of vectors bundled. Provides approximate unit length without computing the full norm (faster).

Parameters:: *hypervectors – Variable number of hypervectors to bundle, or single 2D batch
Returns:: Bundled and approximately normalized hypervector

Note

Result will have ||result|| â‰ˆ 1 (approximate)

Sum then divide by √M. Used by HRR_ConstNorm.

pyhdc.components.bundling.AnglesOfElementAddition(*hypervectors: ndarray | torch.Tensor, random_choice_range: float | None = None) → Tuple[ndarray | torch.Tensor, Dict[str, Any]][source]

Bundling by adding phase angles (for FHRR).

Bundles phase-encoded hypervectors by computing the mean angle. Converts angles to complex numbers, sums them, and extracts the resulting phase. Used with Fourier Holographic Reduced Representations.

When random_choice_range is set, coordinates whose phasor magnitude |sum| falls within rho * sqrt(N/2) are replaced by independent fair draws from Uniform[-pi, pi] (band randomization for FHRR). The Rayleigh sigma of the neutral phasor sum magnitude is sqrt(N/2). Defaulting random_choice_range to 0.0 limits this to near-zero magnitude sums only.

Parameters:

*hypervectors – Variable number of phase hypervectors, or single 2D batch
random_choice_range – Optional float (rho). Coordinates with phasor magnitude <= rho * sqrt(N/2) are randomly assigned. Defaults to 0.0.

Returns:

Tuple of (bundled phase hypervector, metadata dict). Metadata contains “random_zone_count”.

Note

Input values should be angles in radians. Output is also in radians.

Phasor resultant angle. Used by FHRR.

pyhdc.components.bundling.Disjunction(*hypervectors: ndarray | torch.Tensor) → ndarray | torch.Tensor[source]

Bitwise OR bundling for sparse binary vectors.

Bundles sparse binary hypervectors using bitwise OR. An element is 1 in the result if it is 1 in any input vector. Preserves sparsity better than addition for Binary Sparse Distributed Codes.

Parameters:: *hypervectors – Variable number of sparse binary hypervectors, or single 2D batch
Returns:: Bundled sparse binary hypervector

Example

>>> v1 = np.array([1, 0, 1, 0])
>>> v2 = np.array([0, 1, 0, 0])
>>> result = Disjunction(v1, v2)
>>> # result: [1, 1, 1, 0]

Bitwise OR. Used by BSDC family (without thinning).

pyhdc.components.bundling.DisjunctionThinned(*hypervectors: ndarray | torch.Tensor, density: float = 0.5) → ndarray | torch.Tensor[source]

Bitwise OR bundling with random thinning to maintain density.

Bundles sparse binary hypervectors using bitwise OR, then randomly zeros bits to keep the fraction of 1-bits at most density.

Parameters:

*hypervectors – Variable number of sparse binary hypervectors, or single 2D batch
density – Maximum output density (fraction of 1-bits), defaults to 0.5

Returns:

Bundled and thinned sparse binary hypervector

Example

>>> v1 = np.array([1, 0, 1, 0])
>>> v2 = np.array([0, 1, 1, 0])
>>> result = DisjunctionThinned(v1, v2, density=0.25)
>>> # result has at most 1 nonzero element (25% of 4)

Bitwise OR then random thinning to maintain target density. Used by BSDC_THIN.

Parameters:: target_density – Target density after thinning (float, 0 < d < 1).

pyhdc.components.elements

Element generators control how individual hypervector values are drawn. Each function has signature (size, dtype) -> ndarray.

pyhdc.components.elements.UniformBipolar(dimensions: int, dtype: type = <class 'numpy.float32'>) → ndarray[source]

UniformBipolar X∈R, X_i ~ U(-1,1)

Uniform distribution of real numbers between -1 and 1

Parameters:: dimensions (int) – number of dimensions in the vector
Returns:: hypervector
Return type:: np.ndarray

Uniform random from {-1, +1}.

pyhdc.components.elements.UniformAngles(dimensions: int, dtype: type = <class 'numpy.float32'>) → ndarray[source]

UniformAngles θ∈R, θ_i ~ U(-pi, pi)

Uniformly distributed angles from -pi to pi. Useful for a complex hypervector representation X∈C, X_i = e^(i*θ). In this case, the complex vector is assumed to be on the unit circle (length one) so we only need to store the real angle, θ, and the hypervector X can be computed as needed from the hypervector θ.

Parameters:: dimensions (int) – number of dimensions in the vector
Returns:: hypervector
Return type:: np.ndarray

Uniform random in [0, 2π].

pyhdc.components.elements.NormalReal(dimensions: int, dtype: type = <class 'numpy.float32'>) → ndarray[source]

NormalReal X∈R, X_i ~ N(0, 1/d)

Normal distribution of real numbers with mean 0 and variance 1/d, where d is the dimension of the hypervector

Parameters:: dimensions (int) – number of dimensions in the vector
Returns:: hypervector
Return type:: np.ndarray

Standard normal N(0, 1).

pyhdc.components.elements.BernoulliBinary(dimensions: int, dtype: type = <class 'numpy.int32'>) → ndarray[source]

BernoulliBinary X∈{0,1}, X_i ~ B(0.5)

Bernoulli distribution of binary numbers, either 0 or 1

Parameters:: dimensions (int) – number of dimensions in the vector
Returns:: hypervector
Return type:: np.ndarray

Bernoulli(p=0.5) → {0, 1}.

pyhdc.components.elements.BernoulliBiploar(dimensions: int, dtype: type = <class 'numpy.int32'>) → ndarray[source]

BernoulliBiploar X∈Z, X_i ~ B(0.5)*2 - 1

Bernoulli distribution of bipolar numbers, either -1 or 1

Parameters:: dimensions (int) – number of dimensions in the vector
Returns:: hypervector
Return type:: np.ndarray

Bernoulli(p=0.5) → {-1, +1}.

pyhdc.components.elements.BernoulliSparse(dimensions: int, dtype: type = <class 'numpy.int32'>, probability: float = None) → ndarray[source]

BernoulliSparse X∈{0,1}, X_i ~ B(p << 1)

Bernoulli distribution of binary numbers, either 0 or 1 with variable probability. If undefined probability is given as p = 1/sqrt(dimensions), which creates a sparsely populated array

Parameters:

dimensions (int) – number of dimensions in the vector
probability (float, optional) – probability of the Bernoulli distribution, defaults to 1/sqrt(d)

Returns:

hypervector

Return type:

np.ndarray

k-sparse binary: exactly k elements are 1, rest 0.

Parameters:: k – Number of 1s. Default: determined by the encoding.

pyhdc.components.elements.SparseSegmented(dimensions: int, dtype: type = <class 'numpy.int32'>, probability: float = None) → ndarray[source]

SparseSegmented X∈{0,1}, X_i ~ B(p << 1)

Sparsely segmented binary numbers, either 0 or 1 with variable probability. If undefined probability is given as p = 1/sqrt(dimensions). Hypervector is split into s, dimensions * probability, segments. Each segment populated with exactly 1 non-zero element uniformly distributed throughout the segment.

NOTE: Since s = dimensions * probability is not garunteed to evenly divide into the hypervector dimensions, the segment, s, is rounded up and the final hypervector trimmed. This means the non-zero value in the last segment may be trimmed and not be present in the final hypervector.

Parameters:

dimensions (int) – number of dimensions in the vector
probability (float, optional) – probability of the Bernoulli distribution, defaults to 1/sqrt(d)

Returns:

hypervector

Return type:

np.ndarray

Segment-wise sparse binary: k ones per segment.

Parameters:

segment_size – Number of elements per segment.
k – Number of 1s per segment.

pyhdc.components.thinning

pyhdc.components.thinning.NoThin(hypervector: ndarray) → ndarray[source]: No-op thinning function. Returns the input unchanged. Used by all encodings that do not perform thinning.