eryon_rt/frag/impls/

impl_fragment.rs

/*
    Appellation: fragment <module>
    Contrib: @FL03
*/
use crate::actors::prelude::{Driver, OperatorKind, TriadDriver, VNode};
use crate::frag::FragTonnetz;
use crate::types::{NodeCapabilities, NodeMessage};
use rshyper::{EdgeId, VertexId};
use rstmt::nrt::{LPR, Triad};
use rstmt::{Aspn as Note, PitchMod};
use std::collections::{HashMap, HashSet};

impl<D> FragTonnetz<D>
where
    D: Driver<Triad>,
{
    /// Add a triad to the graph and create a VNode for it
    pub fn add_triad(&mut self, triad: Triad) -> crate::Result<EdgeId> {
        // Create vertices for each note if they don't exist
        let mut vertex_ids = Vec::with_capacity(3);

        for note_class in triad.notes() {
            // Check if a vertex with this pitch class already exists
            if let Some(id) = self.find_vertex_by_pitch(note_class) {
                vertex_ids.push(id);
            } else {
                // Create new vertex
                let note = Note::new(note_class, triad.octave());
                let vertex_id = self.add_note(note)?;
                vertex_ids.push(vertex_id);
            }
        }

        // Create the hyperedge representing the triad
        let edge_id = self.add_edge(vertex_ids)?;

        // Create plant and VNode for this triad
        let plant = D::from_headspace(triad);
        let vnode = VNode::from_driver(plant);

        // Add to partitions
        self.partitions_mut().insert(edge_id, vnode);

        Ok(edge_id)
    }
    // Incremental transformation computation
    pub fn add_transformation(&mut self, edge_id: EdgeId) -> crate::Result<()> {
        if let Some(source_node) = self.get_vnode(&edge_id) {
            let source_triad = *source_node.driver().headspace();
            let mut edge_transformations = HashMap::new();

            // Try all possible transformations
            for transform in [LPR::Leading, LPR::Parallel, LPR::Relative] {
                let target_triad = source_triad.transform(transform);
                // Check if the transformed triad exists
                if let Some(target_edge) = self.find_edge_by_notes(target_triad.notes()) {
                    edge_transformations.insert(transform, target_edge);
                }
            }

            // Store transformations
            if !edge_transformations.is_empty() {
                self.transformations.insert(edge_id, edge_transformations);
            }

            // Check for incoming transformations from other nodes
            for (&other_edge, other_node) in &self.partitions {
                if other_edge == edge_id {
                    continue;
                }

                let other_triad = *other_node.driver().headspace();

                for transform in LPR::iter() {
                    let transformed = other_triad.transform(transform);
                    if transformed.notes() == source_triad.notes() {
                        // Add incoming transformation
                        self.transformations
                            .entry(other_edge)
                            .or_default()
                            .insert(transform, edge_id);
                    }
                }
            }

            Ok(())
        } else {
            Err(crate::RuntimeError::NodeNotFound)
        }
    }
    /// Balance resources across nodes
    pub fn balance_resources(&mut self) -> crate::Result<()> {
        // TODO: Implement resource balancing
        // currently just a placeholder
        // true implementation would consider resource usage to make the necessary adjustments

        // For now, just optimize memory on all nodes
        for node in self.partitions_mut().values_mut() {
            node.optimize_memory(1000)?;
        }

        Ok(())
    }
    // Standard version of batch transform without requiring rayon
    pub fn batch_transform_sequential(
        &mut self,
        operations: Vec<(EdgeId, Vec<LPR>)>,
    ) -> crate::Result<()>
    where
        D: TriadDriver,
    {
        for (edge_id, transforms) in operations {
            let node = self.get_vnode_mut(&edge_id).expect("Node not found");
            node.transform_batch(&transforms)?;
        }
        Ok(())
    }
    /// Calculate capabilities of all nodes
    pub fn calculate_node_capabilities(&self) -> HashMap<EdgeId, NodeCapabilities> {
        self.partitions
            .iter()
            .map(|(&id, node)| {
                (
                    id,
                    NodeCapabilities {
                        memory_usage: node.store().size(),
                        compute_capability: if node.has_surface_network() { 10 } else { 5 },
                        learning_capability: node.has_surface_network(),
                        feature_count: node.total_features(),
                    },
                )
            })
            .collect()
    }
    /// Calculate the resource utilization of this fragment
    pub fn calculate_resource_usage(&self) -> (usize, usize) {
        // Memory usage: total number of features across all nodes
        let memory_usage = self
            .partitions()
            .values()
            .map(|node| node.total_features())
            .sum();

        // Compute usage: complexity based on number of nodes and edges
        let compute_usage = self.total_partitions() * 10 + self.total_edges();

        (memory_usage, compute_usage)
    }
    /// Collect proposed transformations from agent nodes
    pub fn collect_proposed_transformations(&self) -> Vec<(EdgeId, LPR)> {
        let mut proposals = Vec::new();

        for (&edge_id, node) in self.partitions() {
            if let OperatorKind::Agent = node.kind() {
                if let Some(transform) = node.propose_transformation() {
                    proposals.push((edge_id, transform));
                }
            }
        }

        proposals
    }
    /// Compute and store all possible transformations between triads in the fragment
    pub fn compute_transformations(&mut self) {
        // Clear existing transformations
        self.transformations_mut().clear();

        // For each pair of nodes, check if there's a transformation between them
        let edges: Vec<EdgeId> = self.partitions().keys().cloned().collect();

        for &source_edge in &edges {
            let mut edge_transformations = HashMap::new();

            if let Some(source_node) = self.get_vnode(&source_edge) {
                let source_triad = *source_node.driver().headspace();

                // Try all possible transformations
                for transform in [LPR::Leading, LPR::Parallel, LPR::Relative] {
                    let target_triad = source_triad.transform(transform);

                    // Check if the transformed triad exists in our fragment
                    if let Some(target_edge) = self.find_edge_by_notes(target_triad.notes()) {
                        edge_transformations.insert(transform, target_edge);
                    }
                }
            }

            // Store transformations for this edge
            if !edge_transformations.is_empty() {
                self.transformations
                    .insert(source_edge, edge_transformations);
            }
        }
    }
    /// Coordinate learning between nodes with similar contexts
    pub fn coordinate_learning(&mut self) -> crate::Result<()> {
        // Early exit for small fragments
        if self.partitions().len() <= 1 {
            return Ok(());
        }

        // 1. Identify nodes with knowledge (have surface networks)
        // Use filter_map to avoid the separate collect and iteration
        let knowledge_nodes: Vec<EdgeId> = self
            .partitions
            .iter()
            .filter_map(|(&id, node)| {
                if node.has_surface_network() && node.total_features() > 0 {
                    Some(id)
                } else {
                    None
                }
            })
            .collect();

        if knowledge_nodes.len() <= 1 {
            return Ok(());
        }

        // 2. Simple node distribution - only process a fixed number of transfers
        // This avoids quadratic behavior by capping the total operations
        let total_transfers = core::cmp::min(50, knowledge_nodes.len() * 3);
        let mut transfers_done = 0;

        // Iterate through source nodes
        for source_id in &knowledge_nodes {
            if transfers_done >= total_transfers {
                break;
            }

            // Extract patterns once per source (key optimization)
            let patterns = match self
                .get_vnode(source_id)
                .and_then(|node| node.extract_knowledge_patterns().ok())
            {
                Some(p) if !p.is_empty() => p,
                _ => continue,
            };

            // Share with just a few target nodes (limit fan-out)
            let max_targets = std::cmp::min(3, knowledge_nodes.len() - 1);
            let mut targets_for_this_source = 0;

            // Share knowledge with targets
            for target_id in &knowledge_nodes {
                if source_id == target_id || targets_for_this_source >= max_targets {
                    continue;
                }

                // Apply the transfer
                if let Some(target) = self.get_vnode_mut(target_id) {
                    if let Ok(_) = target.integrate_external_knowledge(&patterns, source_id) {
                        targets_for_this_source += 1;
                        transfers_done += 1;
                    }
                }

                if transfers_done >= total_transfers {
                    break;
                }
            }
        }

        // 3. Record simple event - don't iterate all nodes again
        if transfers_done > 0 {
            // Just mark event on the first few nodes as an optimization
            for (_, node) in self.partitions.iter_mut().take(5) {
                node.store_mut()
                    .record_event("knowledge_coordination", Some(vec![knowledge_nodes.len()]));
            }
        }

        Ok(())
    }
    /// Create a new node with the specified triad
    pub fn create_node(&mut self, triad: Triad) -> crate::Result<EdgeId> {
        // Check if this triad already exists
        if let Some(edge_id) = self.find_edge_by_notes(triad.notes()) {
            return Ok(edge_id); // Return existing edge ID
        }

        // Create new node
        self.add_triad(triad)
    }
    /// Execute a transformation path
    pub fn execute_transformation_path(&mut self, path: &[(EdgeId, LPR)]) -> crate::Result<()>
    where
        D: TriadDriver,
    {
        for &(node_id, transform) in path {
            self.send_command(node_id, transform)?;
        }
        Ok(())
    }
    /// Find an edge by triad notes
    pub fn find_edge_by_notes(&self, notes: [usize; 3]) -> Option<EdgeId> {
        self.partitions.iter().find_map(|(&edge_id, vnode)| {
            if vnode.get_notes() == notes {
                Some(edge_id)
            } else {
                None
            }
        })
    }
    /// Find a VNode by its ID
    pub fn get_vnode(&self, id: &EdgeId) -> Option<&VNode<D>> {
        self.partitions().get(id)
    }
    /// Find a VNode by its ID (mutable)
    pub fn get_vnode_mut(&mut self, id: &EdgeId) -> Option<&mut VNode<D>> {
        self.partitions_mut().get_mut(id)
    }
    /// Find a node by its name
    pub fn find_node_by_name(&self, name: &str) -> Option<&VNode<D>> {
        self.partitions()
            .values()
            .find(|node| node.store().get_property("name").is_some_and(|n| n == name))
    }
    /// Find optimal node for offloading work
    pub fn find_optimal_node_for(&self, work_type: &str) -> Option<EdgeId> {
        let capabilities = self.calculate_node_capabilities();

        match work_type {
            "learning" => capabilities
                .iter()
                .filter(|(_, cap)| cap.learning_capability)
                .min_by_key(|(_, cap)| cap.memory_usage)
                .map(|(&id, _)| id),

            "pattern_recognition" => capabilities
                .iter()
                .max_by_key(|(_, cap)| cap.feature_count)
                .map(|(&id, _)| id),

            "transformation" => capabilities
                .iter()
                .min_by_key(|(_, cap)| cap.memory_usage)
                .map(|(&id, _)| id),

            _ => None,
        }
    }
    /// Find related nodes - nodes that share patterns or transformations
    pub fn find_related_nodes(&self, node_id: EdgeId) -> Vec<EdgeId> {
        let mut related = HashSet::new();

        // Add nodes connected by transformations
        if let Some(transforms) = self.transformations().get(&node_id) {
            for &target_id in transforms.values() {
                related.insert(target_id);
            }
        }

        // Find nodes with inverse transformations pointing to this one
        for (&source, transforms) in self.transformations() {
            for &target in transforms.values() {
                if target == node_id {
                    related.insert(source);
                }
            }
        }

        // Convert to Vec and return
        related.into_iter().collect()
    }
    /// Get nodes with specific operator mode
    pub fn find_nodes_with_operator(&self, mode: OperatorKind) -> Vec<EdgeId> {
        self.partitions()
            .iter()
            .filter_map(
                |(&id, node)| {
                    if node.kind() == mode { Some(id) } else { None }
                },
            )
            .collect()
    }
    /// Find nodes containing a specific pitch class
    pub fn find_nodes_with_pitch(&self, pitch: usize) -> Vec<EdgeId> {
        self.partitions()
            .iter()
            .filter_map(|(&id, node)| {
                if node.get_notes().contains(&(pitch % 12)) {
                    Some(id)
                } else {
                    None
                }
            })
            .collect()
    }
    /// Find optimal transformation path between two nodes
    pub fn find_transformation_path(
        &self,
        source_id: EdgeId,
        target_id: EdgeId,
    ) -> Option<Vec<(EdgeId, LPR)>> {
        // Skip if either node doesn't exist
        if !self.partitions.contains_key(&source_id) || !self.partitions.contains_key(&target_id) {
            return None;
        }

        // BFS search for shortest path
        use std::collections::VecDeque;

        let mut queue = VecDeque::new();
        let mut visited = HashSet::new();
        let mut came_from: HashMap<EdgeId, (EdgeId, LPR)> = HashMap::new();

        queue.push_back(source_id);
        visited.insert(source_id);

        while let Some(current) = queue.pop_front() {
            if current == target_id {
                // Path found, reconstruct it
                let mut path = Vec::new();
                let mut node_id = current;

                while let Some(&(prev_id, transform)) = came_from.get(&node_id) {
                    path.push((prev_id, transform));
                    node_id = prev_id;
                }

                path.reverse();
                return Some(path);
            }

            // Check all transformations from current node
            if let Some(transforms) = self.transformations.get(&current) {
                for (&transform, &next) in transforms {
                    if !visited.contains(&next) {
                        visited.insert(next);
                        came_from.insert(next, (current, transform));
                        queue.push_back(next);
                    }
                }
            }
        }

        None // No path found
    }
    /// Find a vertex by its pitch class value
    pub fn find_vertex_by_pitch(&self, pitch: usize) -> Option<VertexId> {
        self.graph()
            .nodes()
            .iter()
            .find(|(_, node)| node.weight().class() == pitch.pmod())
            .map(|(id, _)| *id)
    }
    /// returns the task load associated with each "surface"
    pub fn get_all_edge_loads(&self) -> HashMap<EdgeId, f32> {
        self.partitions()
            .iter()
            .map(|(&id, node)| {
                // Normalize by feature count and surface complexity
                let feature_count = node.total_features() as f32;
                let has_surface = if node.has_surface_network() { 1.5 } else { 1.0 };
                let load = (feature_count / 1000.0 * has_surface).min(1.0);
                (id, load)
            })
            .collect()
    }
    /// returns all transformations for a given edge
    pub fn get_transformations(&self, index: &EdgeId) -> HashMap<LPR, EdgeId> {
        self.transformations()
            .get(index)
            .cloned()
            .unwrap_or_default()
    }
    /// Initialize with major and minor triads for all 12 pitch classes
    pub fn initialize_with_all_triads(&mut self) -> crate::Result<()> {
        // Add all major and minor triads
        for root in 0..12 {
            self.add_triad(Triad::major(root))?;
            self.add_triad(Triad::minor(root))?;
            self.add_triad(Triad::diminished(root))?;
            self.add_triad(Triad::augmented(root))?;
        }

        // Compute transformations between all triads
        self.compute_transformations();

        Ok(())
    }
    /// Get proportion of nodes in each operator mode
    pub fn mode_distribution(&self) -> HashMap<OperatorKind, f32> {
        use strum::IntoEnumIterator;
        let mut distribution = HashMap::new();

        for mode in OperatorKind::iter() {
            distribution.insert(mode, 0.0);
        }

        let total = self.partitions().len() as f32;
        if total == 0.0 {
            return distribution;
        }

        for node in self.partitions().values() {
            let mode = node.kind();
            *distribution.entry(mode).or_insert(0.0) += 1.0;
        }

        // Convert to percentages
        for count in distribution.values_mut() {
            *count /= total;
        }

        distribution
    }
    /// Optimize the fragment based on real-time performance metrics
    pub fn optimize_for_real_time(&mut self) -> crate::Result<()>
    where
        D: TriadDriver,
    {
        // 1. Balance operator distribution
        self.optimize_operator_distribution()?;

        // 2. Optimize memory usage
        self.balance_resources()?;

        // 3. Update transformation cache
        self.compute_transformations();

        // 4. Share patterns between nodes
        self.share_patterns()?;

        // 5. Coordinate learning
        self.coordinate_learning()?;

        Ok(())
    }
    /// Optimize memory usage across all nodes
    pub fn optimize_memory(&mut self, max_features: usize) -> crate::Result<()> {
        for node in self.partitions_mut().values_mut() {
            let _stats = node.optimize_memory(max_features)?;
        }
        Ok(())
    }
    /// Optimize operator distribution
    pub fn optimize_operator_distribution(&mut self) -> crate::Result<()> {
        // Count nodes by operator type
        let mut operator_counts = HashMap::new();

        for node in self.partitions().values() {
            let kind = node.kind();
            *operator_counts.entry(kind).or_insert(0) += 1;
        }

        // Calculate optimal distribution
        // For example, ensure we have at least one observer and one agent
        if !operator_counts.contains_key(&OperatorKind::Observer) {
            // Find a node to convert to observer
            if let Some((&id, _)) = self.partitions().iter().next() {
                self.set_node_operator(id, OperatorKind::Observer)?;
            }
        }

        if !operator_counts.contains_key(&OperatorKind::Agent) {
            // Find a node to convert to agent
            if let Some((&id, _)) = self.partitions().iter().nth(1) {
                self.set_node_operator(id, OperatorKind::Agent)?;
            }
        }

        Ok(())
    }
    /// Calculate optimal voice leading distance between two nodes
    pub fn optimal_voice_leading_distance(&self, src: &EdgeId, dest: &EdgeId) -> Option<usize> {
        let source_node = self.get_vnode(src)?;
        let target_node = self.get_vnode(dest)?;

        let source_notes = source_node.get_notes();
        let target_notes = target_node.get_notes();

        // This implementation considers all possible voice assignments to find minimal distance
        fn permutations<T: Copy>(arr: &[T]) -> Vec<Vec<T>> {
            if arr.len() <= 1 {
                return vec![arr.to_vec()];
            }

            let mut result = Vec::new();
            for (i, &item) in arr.iter().enumerate() {
                let mut sub_arr = arr.to_vec();
                sub_arr.remove(i);

                for mut perm in permutations(&sub_arr) {
                    perm.insert(0, item);
                    result.push(perm);
                }
            }

            result
        }

        // Calculate all possible voice assignments
        let target_perms = permutations(&target_notes);

        // Find minimal distance across all possible voice assignments
        target_perms
            .iter()
            .map(|perm| {
                source_notes
                    .iter()
                    .zip(perm)
                    .map(|(&s, &t)| {
                        let dist = ((t as isize - s as isize).abs()).pmod() as usize;
                        std::cmp::min(dist, 12 - dist)
                    })
                    .sum()
            })
            .min()
    }
    /// Process a node message
    pub fn process_message(&mut self, message: &NodeMessage) -> crate::Result<()>
    where
        D: TriadDriver,
    {
        match message {
            NodeMessage::TransformRequest {
                source,
                target,
                transform,
            } => {
                // Verify source node exists
                if !self.partitions.contains_key(source) {
                    return Err(crate::RuntimeError::NodeNotFound);
                }

                // Apply transformation to target node
                self.send_command(*target, *transform)
            }

            NodeMessage::StateSync { source, .. } => {
                // Handle state synchronization
                // Just verify the source node exists for now
                if !self.partitions.contains_key(source) {
                    return Err(crate::RuntimeError::NodeNotFound);
                }
                Ok(())
            }

            NodeMessage::PatternShare {
                source, pattern, ..
            } => {
                // Verify source node exists
                if !self.partitions.contains_key(source) {
                    return Err(crate::RuntimeError::NodeNotFound);
                }

                // Share pattern with all other nodes
                for (&id, node) in self.partitions_mut() {
                    if id != *source {
                        let _ = node.learn_transformation_sequence(pattern);
                    }
                }

                Ok(())
            }
        }
    }
    /// Process incoming stream and distribute to optimal nodes
    pub fn process_stream<I>(&mut self, stream: I) -> crate::Result<Vec<(EdgeId, Vec<LPR>)>>
    where
        I: Iterator<Item = (Triad, Vec<LPR>)>,
        D: TriadDriver,
    {
        let mut results = Vec::new();

        for (target_triad, transforms) in stream {
            // Find or create node for this triad
            let edge_id = match self.find_edge_by_notes(target_triad.notes()) {
                Some(id) => id,
                None => self.add_triad(target_triad)?,
            };

            // Apply transformations
            if let Some(node) = self.get_vnode_mut(&edge_id) {
                node.transform_batch(&transforms)?;

                // Capture the resulting state
                results.push((edge_id, transforms));
            }
        }

        Ok(results)
    }
    /// Process a stream of transformations with dynamic resource allocation
    pub fn process_transformation_stream<I>(&mut self, stream: I) -> crate::Result<()>
    where
        I: Iterator<Item = (EdgeId, LPR)>,
        D: TriadDriver,
    {
        // Batch size depends on system resources
        let optimal_batch_size = 10; // Could be dynamically calculated

        let mut current_batch = Vec::with_capacity(optimal_batch_size);
        let mut current_edge = None;

        for (edge_id, transform) in stream {
            // If we're switching to a different edge, process the current batch
            if current_edge != Some(edge_id) && !current_batch.is_empty() {
                if let Some(edge) = current_edge {
                    if let Some(node) = self.get_vnode_mut(&edge) {
                        node.transform_batch(&current_batch)?;
                    }
                }
                current_batch.clear();
            }

            // Add to current batch
            current_edge = Some(edge_id);
            current_batch.push(transform);

            // Process batch if it reaches optimal size
            if current_batch.len() >= optimal_batch_size {
                if let Some(node) = self.get_vnode_mut(&edge_id) {
                    node.transform_batch(&current_batch)?;
                }
                current_batch.clear();
            }
        }

        // Process any remaining transformations
        if let Some(edge_id) = current_edge {
            if !current_batch.is_empty() {
                if let Some(node) = self.get_vnode_mut(&edge_id) {
                    node.transform_batch(&current_batch)?;
                }
            }
        }

        Ok(())
    }
    /// Send a command to a specific surface node
    pub fn send_command(&mut self, node_id: EdgeId, transform: LPR) -> crate::Result<()>
    where
        D: TriadDriver,
    {
        if let Some(node) = self.get_vnode_mut(&node_id) {
            node.transform(transform).map_err(|err| err.into())
        } else {
            Err(crate::RuntimeError::NodeNotFound)
        }
    }
    /// Set operator mode for all nodes
    pub fn set_all_nodes_mode(&mut self, mode: OperatorKind) -> crate::Result<()> {
        for node in self.partitions_mut().values_mut() {
            node.set_operator_by_kind(mode);
        }
        Ok(())
    }
    /// Set operator mode for a specific node
    pub fn set_node_operator(&mut self, node_id: EdgeId, mode: OperatorKind) -> crate::Result<()> {
        if let Some(node) = self.get_vnode_mut(&node_id) {
            node.set_operator_by_kind(mode);
            Ok(())
        } else {
            Err(crate::RuntimeError::NodeNotFound)
        }
    }
    /// Share patterns between nodes to enhance collective memory
    pub fn share_patterns(&mut self) -> crate::Result<()> {
        // Collect all patterns from all nodes
        let mut all_patterns = Vec::new();

        for (&edge_id, node) in &self.partitions {
            // Get patterns with their importance and source
            let node_patterns = node
                .store()
                .patterns()
                .iter()
                .map(|p| (edge_id, p.sequence().clone(), *p.importance()))
                .collect::<Vec<_>>();

            all_patterns.extend(node_patterns);
        }

        // Sort by importance descending
        all_patterns
            .sort_by(|(_, _, a), (_, _, b)| b.partial_cmp(a).unwrap_or(std::cmp::Ordering::Equal));

        // Share the top patterns with all nodes
        let top_patterns = all_patterns.into_iter().take(10);

        for (source_id, pattern, ..) in top_patterns {
            for (&target_id, target_node) in self.partitions_mut() {
                if target_id != source_id {
                    // Convert pattern from usize to LPR for learning
                    let lpr_pattern = pattern
                        .clone()
                        .into_iter()
                        .filter_map(|p| match p {
                            0 => Some(LPR::Leading),
                            1 => Some(LPR::Parallel),
                            2 => Some(LPR::Relative),
                            _ => None,
                        })
                        .collect::<Vec<_>>();

                    // Learn the pattern if possible
                    let _ = target_node.learn_transformation_sequence(&lpr_pattern);
                }
            }
        }

        Ok(())
    }
    /// Split the fragment's workload based on available resources
    pub fn split_for_distributed_processing(&self) -> Vec<(EdgeId, Vec<LPR>)> {
        // Determine which nodes are resource-intensive
        let _capabilities = self.calculate_node_capabilities();

        // Create balanced workload units
        let mut workloads = Vec::new();

        for id in self.partitions.keys() {
            // Generate a sequence of transformations this node should process
            if let Some(node) = self.get_vnode(id) {
                if node.kind() == OperatorKind::Agent {
                    // Agents can propose their own transformations
                    if let Some(transform) = node.propose_transformation() {
                        workloads.push((*id, vec![transform]));
                    }
                }
            }
        }

        workloads
    }
    /// Calculate voice-leading distance between two triads
    pub fn voice_leading_distance(&self, from: &EdgeId, to: &EdgeId) -> Option<usize> {
        // Get the triads from both nodes
        let from_node = self.get_vnode(from)?;
        let to_node = self.get_vnode(to)?;

        let from_triad = from_node.headspace();
        let to_triad = to_node.headspace();

        // Calculate minimal voice leading distance
        let from_notes = from_triad.notes();
        let to_notes = to_triad.notes();

        // Start with basic voice-leading distance calculation
        let mut distance = 0;

        // For each note in the source triad, find the closest note in the target triad
        for from_note in from_notes {
            let mut min_dist = 12; // Maximum distance in semitones within an octave
            for to_note in to_notes {
                // Calculate minimal semitone distance (considering octave equivalence)
                let direct_dist = ((to_note as isize - from_note as isize).abs()).pmod() as usize;
                min_dist = min_dist.min(direct_dist);
            }
            distance += min_dist;
        }

        Some(distance)
    }
}