wifi-densepose/v2/crates/ruv-neural/ruv-neural-embed

ruv-neural-embed

Graph embedding generation for brain connectivity states using RuVector format.

Overview

ruv-neural-embed converts brain connectivity graphs into fixed-dimensional vector representations suitable for downstream classification, clustering, and temporal analysis. It provides multiple embedding methods and supports export to the RuVector .rvf binary format for interoperability with the broader RuVector ecosystem.

Features

• Spectral embedding (spectral_embed): Laplacian eigenvector-based positional encoding from the graph's normalized Laplacian
• Topology embedding (topology_embed): Hand-crafted topological feature vectors derived from graph-theoretic metrics
• Node2Vec (node2vec): Random-walk co-occurrence embeddings using configurable walk length, return parameter (p), and in-out parameter (q)
• Combined embedding (combined): Weighted concatenation of multiple embedding methods into a single vector
• Temporal embedding (temporal): Sliding-window context-enriched embeddings that capture graph dynamics over time
• Distance metrics (distance): Embedding distance and similarity computations
• RVF export (rvf_export): Serialization of embeddings and trajectories to the RuVector .rvf binary format
• Helper utilities: default_metadata for quick EmbeddingMetadata construction

Usage

use ruv_neural_embed::{
    NeuralEmbedding, EmbeddingMetadata, EmbeddingTrajectory,
    default_metadata,
};
use ruv_neural_core::brain::Atlas;

// Create an embedding with metadata
let meta = default_metadata("spectral", Atlas::Schaefer100);
let emb = NeuralEmbedding::new(vec![0.1, 0.5, -0.3, 0.8], 1000.0, meta).unwrap();
assert_eq!(emb.dimension, 4);

// Compute similarity between embeddings
let other = NeuralEmbedding::new(
    vec![0.2, 0.4, -0.2, 0.9],
    1001.0,
    default_metadata("spectral", Atlas::Schaefer100),
).unwrap();
let similarity = emb.cosine_similarity(&other).unwrap();
let distance = emb.euclidean_distance(&other).unwrap();

// Build a trajectory from a sequence of embeddings
let trajectory = EmbeddingTrajectory {
    embeddings: vec![emb, other],
    timestamps: vec![1000.0, 1001.0],
};
assert_eq!(trajectory.len(), 2);

API Reference

Module	Key Types / Functions
spectral_embed	Spectral positional encoding from graph Laplacian
topology_embed	Topological feature vector extraction
node2vec	Random-walk based node embeddings
combined	Weighted multi-method embedding concatenation
temporal	Sliding-window temporal context embeddings
distance	Distance and similarity computations
rvf_export	RVF binary format serialization

Feature Flags

Feature	Default	Description
std	Yes	Standard library support
wasm	No	WASM-compatible implementations
rvf	No	RuVector RVF format export support

Integration

Depends on ruv-neural-core for NeuralEmbedding, BrainGraph, and EmbeddingGenerator trait. Receives graphs from ruv-neural-graph or ruv-neural-mincut. Produced embeddings are stored by ruv-neural-memory and classified by ruv-neural-decoder.

License

MIT OR Apache-2.0