Struct Resonator 

pub struct Resonator {
    pub codebook: Vec<SparseVec>,
    pub max_iterations: usize,
    pub convergence_threshold: f64,
}

Resonator network for pattern completion and factorization

Fields

codebook: Vec<SparseVec>

Codebook of clean reference patterns

max_iterations: usize

Maximum iterations for convergence

convergence_threshold: f64

Convergence threshold for early stopping

Implementations

impl Resonator

pub fn new() -> Resonator

Create a new resonator with default parameters

Examples

use embeddenator_retrieval::resonator::Resonator;

let resonator = Resonator::new();
assert_eq!(resonator.max_iterations, 10);
assert_eq!(resonator.convergence_threshold, 0.001);

pub fn with_params( codebook: Vec<SparseVec>, max_iterations: usize, convergence_threshold: f64, ) -> Resonator

Create resonator with custom parameters

Arguments

• codebook - Vector of clean reference patterns
• max_iterations - Maximum refinement iterations
• convergence_threshold - Early stopping threshold

Examples

use embeddenator_retrieval::resonator::Resonator;
use embeddenator_vsa::SparseVec;

let codebook = vec![SparseVec::from_data(b"pattern1"), SparseVec::from_data(b"pattern2")];
let resonator = Resonator::with_params(codebook, 20, 0.0001);
assert_eq!(resonator.max_iterations, 20);

pub fn project(&self, noisy: &SparseVec) -> SparseVec

Project a noisy vector onto the nearest codebook entry

Computes cosine similarity against all codebook entries and returns the entry with highest similarity. Used for pattern completion and noise reduction.

Arguments

• noisy - Input vector to project (may be noisy or partial)

Returns

The codebook entry with highest similarity to the input

Examples

use embeddenator_retrieval::resonator::Resonator;
use embeddenator_vsa::SparseVec;

let clean = SparseVec::from_data(b"hello");
let codebook = vec![clean.clone(), SparseVec::from_data(b"world")];
let resonator = Resonator::with_params(codebook, 10, 0.001);

// Clean input should project to itself
let projected = resonator.project(&clean);
assert!(clean.cosine(&projected) > 0.9);

pub fn factorize( &self, compound: &SparseVec, num_factors: usize, ) -> FactorizeResult

Factorize a compound vector into constituent factors using iterative refinement

Uses the resonator network to decompose a bundled vector into its original components through iterative projection and unbinding operations.

Arguments

• compound - The bundled vector to factorize
• num_factors - Number of factors to extract

Returns

FactorizeResult containing the extracted factors, iterations performed, and convergence delta

Examples

use embeddenator_retrieval::resonator::Resonator;
use embeddenator_vsa::SparseVec;

let factor1 = SparseVec::from_data(b"hello");
let factor2 = SparseVec::from_data(b"world");
let compound = factor1.bundle(&factor2);

let codebook = vec![factor1.clone(), factor2.clone()];
let resonator = Resonator::with_params(codebook, 10, 0.001);

let result = resonator.factorize(&compound, 2);
assert_eq!(result.factors.len(), 2);
assert!(result.iterations <= 10);

pub fn recover_data( &self, encoded: &SparseVec, config: &ReversibleVSAConfig, path: Option<&str>, expected_size: usize, ) -> Vec<u8>

Recover data from an encoded sparse vector using resonator-enhanced decoding

Uses the codebook to enhance pattern completion during the decoding process, enabling recovery from noisy or partially corrupted encodings.

Arguments

• encoded - The encoded sparse vector to decode
• config - Configuration used for encoding
• path - Path string used for encoding
• expected_size - Expected size of the decoded data

Returns

Recovered data bytes (may need correction layer for 100% fidelity)

Examples

use embeddenator_retrieval::resonator::Resonator;
use embeddenator_vsa::{SparseVec, ReversibleVSAConfig};

let data = b"hello world";
let config = ReversibleVSAConfig::default();
let encoded = SparseVec::encode_data(data, &config, None);

let resonator = Resonator::new();
let recovered = resonator.recover_data(&encoded, &config, None, data.len());

// Note: For 100% fidelity, use CorrectionStore with EmbrFS

pub fn recover_chunks( &self, available_chunks: &HashMap<usize, Vec<u8>>, missing_chunk_ids: &[usize], config: &ReversibleVSAConfig, ) -> HashMap<usize, Vec<u8>>

Recover missing chunks using pattern completion

Attempts to reconstruct missing or corrupted data chunks by leveraging the resonator’s codebook for pattern completion.

Arguments

• available_chunks - Map of chunk_id to available chunk data
• missing_chunk_ids - List of chunk IDs that need recovery
• config - VSA configuration for encoding/decoding

Returns

Map of recovered chunk_id to recovered data

Examples

use embeddenator_retrieval::resonator::Resonator;
use embeddenator_vsa::ReversibleVSAConfig;
use std::collections::HashMap;

let resonator = Resonator::new();
let config = ReversibleVSAConfig::default();
let mut available_chunks = HashMap::new();
// available_chunks.insert(0, chunk_data);

let missing_ids = vec![1, 2];
let recovered = resonator.recover_chunks(&available_chunks, &missing_ids, &config);

pub fn sign_threshold(&self, similarities: &[f64], threshold: f64) -> Vec<i8>

Apply ternary sign thresholding to enhance sparsity preservation

Converts similarity scores to ternary values (-1, 0, +1) using a threshold, preserving the sparse ternary nature of VSA vectors while reducing noise.

Arguments

• similarities - Vector of similarity scores to threshold
• threshold - Minimum absolute similarity to retain (default: 0.1)

Returns

Vector of ternary values: -1, 0, or +1

Examples

use embeddenator_retrieval::resonator::Resonator;

let resonator = Resonator::new();
let similarities = vec![0.8, -0.3, 0.05, -0.9];
let ternary = resonator.sign_threshold(&similarities, 0.1);

assert_eq!(ternary, vec![1, -1, 0, -1]);

Trait Implementations

impl Clone for Resonator

fn clone(&self) -> Resonator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Resonator

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Resonator

fn default() -> Resonator

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Resonator

fn deserialize<__D>( __deserializer: __D, ) -> Result<Resonator, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Resonator

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.