Struct DualRing 

pub struct DualRing<T> { /* private fields */ }

Dual Ring Structure for IRCP/RCP

Represents the same episodes in two different orderings:

• Temporal Ring (RCP): Ordered by causal/temporal flow
• Influence Ring (IRCP): Ordered by influence/attention weight

This enables efficient traversal in both directions:

• Forward (RCP): “What context led to this response?”
• Inverse (IRCP): “What did this response influence?”

Example

use rag_plusplus_core::trajectory::{DualRing, DualRingNode};

// Create nodes with temporal order and influence weights
let nodes = vec![
    DualRingNode::new(0, "episode_a", 0.8),  // temporal_idx=0, influence=0.8
    DualRingNode::new(1, "episode_b", 0.3),  // temporal_idx=1, influence=0.3
    DualRingNode::new(2, "episode_c", 0.9),  // temporal_idx=2, influence=0.9
    DualRingNode::new(3, "episode_d", 0.5),  // temporal_idx=3, influence=0.5
];

let dual = DualRing::new(nodes);

// Traverse temporally (RCP direction)
let temporal_order: Vec<_> = dual.iter_temporal().map(|n| n.value).collect();
// ["episode_a", "episode_b", "episode_c", "episode_d"]

// Traverse by influence (IRCP direction)
let influence_order: Vec<_> = dual.iter_by_influence().map(|n| n.value).collect();
// ["episode_c", "episode_a", "episode_d", "episode_b"] (by descending influence)

Implementations

impl<T> DualRing<T>

pub fn new(nodes: Vec<DualRingNode<T>>) -> Self

Create a dual ring from nodes.

Nodes should be provided in temporal order.

pub fn len(&self) -> usize

Number of nodes.

pub fn is_empty(&self) -> bool

Check if empty.

pub fn get_temporal(&self, idx: usize) -> &DualRingNode<T>

Get node by temporal index (wrapping).

pub fn temporal_next(&self, idx: usize) -> usize

Next in temporal order.

pub fn temporal_prev(&self, idx: usize) -> usize

Previous in temporal order.

pub fn temporal_distance(&self, a: usize, b: usize) -> usize

Temporal ring distance.

pub fn iter_temporal(&self) -> impl Iterator<Item = &DualRingNode<T>>

Iterate in temporal order (RCP direction).

pub fn iter_temporal_from( &self, start: usize, ) -> impl Iterator<Item = &DualRingNode<T>>

Iterate temporally from a starting point.

pub fn temporal_neighbors( &self, idx: usize, radius: usize, ) -> impl Iterator<Item = &DualRingNode<T>>

Get temporal neighbors within radius.

pub fn get_by_influence_rank(&self, rank: usize) -> &DualRingNode<T>

Get node by influence rank (0 = highest influence).

pub fn influence_rank_of(&self, temporal_idx: usize) -> usize

Get influence rank of a temporal index.

pub fn iter_by_influence(&self) -> impl Iterator<Item = &DualRingNode<T>>

Iterate by influence (IRCP direction, highest first).

pub fn top_influential( &self, k: usize, ) -> impl Iterator<Item = &DualRingNode<T>>

Get top-k most influential nodes.

pub fn influence_distance(&self, a_temporal: usize, b_temporal: usize) -> usize

Influence ring distance (distance in influence-sorted order).

pub fn influence_neighbors( &self, temporal_idx: usize, radius: usize, ) -> impl Iterator<Item = &DualRingNode<T>>

Get influence neighbors (nodes with similar influence).

pub fn influence_temporal_spread(&self) -> f32

Find the temporal distance from high-influence to low-influence nodes.

This measures how “spread out” influence is temporally. Low values mean influence clusters in time; high values mean it’s distributed.

pub fn forward_attention_flow(&self) -> f32

Compute attention flow from earlier to later nodes (RCP forward flow).

Returns total influence flowing from past to future.

pub fn inverse_attention_flow(&self) -> f32

Compute attention flow from later to earlier nodes (IRCP inverse flow).

Returns total influence flowing from future to past (attribution).

pub fn update_influence(&mut self, temporal_idx: usize, new_influence: f32)

Update influence weight for a node.

pub fn as_slice(&self) -> &[DualRingNode<T>]

Get underlying nodes.

Trait Implementations

impl<T: Clone> Clone for DualRing<T>

fn clone(&self) -> DualRing<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for DualRing<T>

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

Formats the value using the given formatter.