oxicuda_graph/
lib.rs

1//! OxiCUDA Graph — CUDA Graph execution engine.
2//!
3//! `oxicuda-graph` provides a high-level, Rust-native computation graph
4//! framework that sits above the raw CUDA driver API. It models GPU
5//! workloads as directed acyclic graphs (DAGs) of operations, applies a
6//! suite of optimisation passes, and lowers the result to an
7//! `oxicuda_driver::graph::Graph` for low-overhead CUDA graph submission.
8//!
9//! # Architecture
10//!
11//! ```text
12//!  ┌─────────────────────────────────────────────┐
13//!  │              GraphBuilder                   │  ← ergonomic API
14//!  └──────────────────┬──────────────────────────┘
15//!                     │ .build()
16//!  ┌──────────────────▼──────────────────────────┐
17//!  │             ComputeGraph                    │  ← DAG of GraphNodes
18//!  └──────────────────┬──────────────────────────┘
19//!           ┌─────────┴──────────┐
20//!           │   Analysis Passes  │
21//!           │  ┌─────────────┐   │
22//!           │  │ topo        │   │  ASAP/ALAP, slack, levels
23//!           │  │ liveness    │   │  buffer live intervals
24//!           │  │ dominance   │   │  Lengauer–Tarjan dominator tree
25//!           │  └─────────────┘   │
26//!           └─────────┬──────────┘
27//!           ┌─────────┴──────────┐
28//!           │ Optimisation Passes│
29//!           │  ┌─────────────┐   │
30//!           │  │ fusion      │   │  element-wise kernel merging
31//!           │  │ memory      │   │  interval-graph buffer colouring
32//!           │  │ stream      │   │  multi-stream partitioning
33//!           │  └─────────────┘   │
34//!           └─────────┬──────────┘
35//!  ┌──────────────────▼──────────────────────────┐
36//!  │             ExecutionPlan                   │  ← ordered PlanSteps
37//!  └──────────────────┬──────────────────────────┘
38//!           ┌─────────┴──────────┐
39//!           │   Executor Backends│
40//!           │  ┌─────────────┐   │
41//!           │  │ sequential  │   │  CPU simulator (testing)
42//!           │  │ cuda_graph  │   │  driver::graph::Graph capture
43//!           │  └─────────────┘   │
44//!           └────────────────────┘
45//! ```
46//!
47//! # Quick start
48//!
49//! ```rust
50//! use oxicuda_graph::builder::GraphBuilder;
51//! use oxicuda_graph::executor::{ExecutionPlan, SequentialExecutor};
52//! use oxicuda_graph::node::MemcpyDir;
53//!
54//! // 1. Build a computation graph.
55//! let mut b = GraphBuilder::new();
56//!
57//! let buf_in  = b.alloc_buffer("input",  4096);
58//! let buf_mid = b.alloc_buffer("mid",    4096);
59//! let buf_out = b.alloc_buffer("output", 4096);
60//!
61//! let upload   = b.add_memcpy("upload",   MemcpyDir::HostToDevice, 4096);
62//! let k0       = b.add_kernel("relu",   4, 256, 0)
63//!                 .fusible(true)
64//!                 .inputs([buf_in])
65//!                 .outputs([buf_mid])
66//!                 .finish();
67//! let k1       = b.add_kernel("scale",  4, 256, 0)
68//!                 .fusible(true)
69//!                 .inputs([buf_mid])
70//!                 .outputs([buf_out])
71//!                 .finish();
72//! let download = b.add_memcpy("download", MemcpyDir::DeviceToHost, 4096);
73//!
74//! b.chain(&[upload, k0, k1, download]);
75//!
76//! let graph = b.build().expect("graph builder produces a valid DAG");
77//!
78//! // 2. Compile to an execution plan.
79//! let plan = ExecutionPlan::build(&graph, /*max_streams=*/ 4).expect("graph is valid for plan compilation");
80//!
81//! // 3. Execute (sequential CPU simulation).
82//! let stats = SequentialExecutor::new(&plan).run().expect("sequential executor runs a valid plan");
83//! assert!(stats.kernels_launched <= 2);  // relu+scale may be fused to 1
84//! ```
85
86#![forbid(unsafe_code)]
87
88pub mod analysis;
89pub mod builder;
90pub mod capture;
91pub mod centrality;
92pub mod cluster;
93pub mod community;
94pub mod error;
95pub mod exec;
96pub mod executor;
97pub mod flow;
98pub mod graph;
99pub mod node;
100pub mod optimizer;
101pub mod schedule;
102
103// Re-export the most commonly used types at the crate root.
104pub use builder::GraphBuilder;
105pub use capture::{CaptureEvent, CaptureStatus, StreamCapture};
106pub use centrality::betweenness::betweenness_centrality;
107pub use centrality::closeness::closeness_centrality;
108pub use centrality::pagerank::{PageRankConfig, pagerank};
109pub use cluster::spectral::{SpectralClustering, SpectralConfig};
110pub use community::louvain::{LouvainConfig, LouvainResult, louvain_communities};
111pub use error::{GraphError, GraphResult};
112pub use exec::{ExecGraph, ExecGraphDiff, NodeParamUpdate};
113pub use executor::{ExecutionPlan, PlanStep, SequentialExecutor};
114pub use flow::min_cost_flow::{McfEdge, McfResult, min_cost_flow};
115pub use graph::ComputeGraph;
116pub use node::{BufferId, GraphNode, KernelConfig, MemcpyDir, NodeId, NodeKind, StreamId};
117pub use schedule::{Schedule, Wavefront};
oxicuda_graph/lib.rs

oxicuda_graph/
lib.rs
