vyre-primitives 0.6.3

Compositional primitives for vyre - marker types (always on) + Tier 2.5 LEGO substrate (feature-gated per domain).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use super::hash::persistent_bfs_program_layout_hash;
use super::layout::{
    persistent_bfs_single_dispatch_grid, PersistentBfsLayout, PersistentBfsPlanCacheKey,
    PersistentBfsPlanCacheKind, PersistentBfsStaticInputKey,
};
use super::program::persistent_bfs;
use crate::graph::program_graph::ProgramGraphShape;
use vyre_foundation::ir::Program;

/// Primitive-owned non-resident persistent-BFS dispatch plan.
pub struct PersistentBfsDispatchPlan {
    pub(super) layout: PersistentBfsLayout,
    pub(super) layout_hash: u64,
    pub(super) allow_mask: u32,
    pub(super) max_iters: u32,
}

impl PersistentBfsDispatchPlan {
    pub(super) fn new(
        layout: PersistentBfsLayout,
        layout_hash: u64,
        allow_mask: u32,
        max_iters: u32,
    ) -> Self {
        Self {
            layout,
            layout_hash,
            allow_mask,
            max_iters,
        }
    }

    /// Validated graph/frontier layout.
    #[must_use]
    pub const fn layout(&self) -> PersistentBfsLayout {
        self.layout
    }

    /// Stable graph-layout hash for plan caches.
    #[must_use]
    pub const fn layout_hash(&self) -> u64 {
        self.layout_hash
    }

    /// Number of words in each frontier bitset.
    #[must_use]
    pub const fn frontier_words(&self) -> usize {
        self.layout.words
    }

    /// Number of u32 words required by node-indexed scratch buffers.
    #[must_use]
    pub const fn node_words(&self) -> usize {
        self.layout.node_words
    }

    /// Number of u32 words required by edge-indexed buffers after zero padding.
    #[must_use]
    pub const fn edge_storage_words(&self) -> usize {
        self.layout.edge_storage_words
    }

    /// Single-query dispatch grid.
    #[must_use]
    pub const fn dispatch_grid(&self) -> [u32; 3] {
        persistent_bfs_single_dispatch_grid(self.layout.node_count)
    }

    /// Program graph shape with primitive-owned empty-edge padding.
    #[must_use]
    pub fn program_shape(&self) -> ProgramGraphShape {
        ProgramGraphShape::new(self.layout.node_count, self.layout.edge_count.max(1))
    }

    /// Build the canonical primitive program for this plan.
    #[must_use]
    pub fn program(&self, frontier_in: &str, frontier_out: &str) -> Program {
        persistent_bfs(
            self.program_shape(),
            frontier_in,
            frontier_out,
            self.allow_mask,
            self.max_iters,
        )
    }

    /// Build the primitive-owned program-cache key for this dispatch plan.
    #[must_use]
    pub const fn cache_key(&self, device_features: u64) -> PersistentBfsPlanCacheKey {
        PersistentBfsPlanCacheKey {
            layout_hash: self.layout_hash,
            node_count: self.layout.node_count,
            edge_count: self.layout.edge_count,
            words_per_query: self.layout.words_u32,
            query_count: 1,
            allow_mask: self.allow_mask,
            max_iters: self.max_iters,
            device_features,
            kind: PersistentBfsPlanCacheKind::Single,
        }
    }

    /// Build a shape-only program cache key for this non-resident dispatch plan.
    ///
    /// The persistent-BFS program depends on graph dimensions, frontier width,
    /// traversal options, dispatch kind, and device features. CSR edge contents
    /// are dispatch inputs, not shader source, so they must not fragment the
    /// compiled-program cache.
    #[must_use]
    pub fn program_cache_key(&self, device_features: u64) -> PersistentBfsPlanCacheKey {
        PersistentBfsPlanCacheKey {
            layout_hash: persistent_bfs_program_layout_hash(
                self.layout.node_count,
                self.layout.edge_count,
                self.layout.words_u32,
                1,
                PersistentBfsPlanCacheKind::Single,
            ),
            node_count: self.layout.node_count,
            edge_count: self.layout.edge_count,
            words_per_query: self.layout.words_u32,
            query_count: 1,
            allow_mask: self.allow_mask,
            max_iters: self.max_iters,
            device_features,
            kind: PersistentBfsPlanCacheKind::Single,
        }
    }

    /// Stable identity for immutable graph inputs associated with this plan.
    #[must_use]
    pub const fn static_input_key(&self) -> PersistentBfsStaticInputKey {
        PersistentBfsStaticInputKey {
            layout_hash: self.layout_hash,
            node_count: self.layout.node_count,
            edge_count: self.layout.edge_count,
            words: self.layout.words_u32,
        }
    }
}