Skip to main content

tenferro_xla/
lib.rs

1//! Experimental StableHLO lowering and runtime PJRT plugin loading for tenferro.
2//!
3//! This crate is an optional peer executor over `tenferro-runtime`
4//! [`SemanticProgram`](tenferro_runtime::program::SemanticProgram) values. It does not
5//! implement `Engine` and it does not change native CPU, CUDA, or
6//! WebGPU execution.
7//!
8//! # Examples
9//!
10//! ```
11//! use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
12//! use tenferro_xla::lower_compiled_to_stablehlo;
13//!
14//! let trace = TraceContext::new();
15//! let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
16//! let y = (&x + &x).unwrap();
17//! let mut compiler = GraphCompiler::new();
18//! let program = compiler.compile(&y).unwrap();
19//! let module = lower_compiled_to_stablehlo(&program).unwrap();
20//! assert!(module.as_str().contains("stablehlo.add"));
21//! ```
22
23mod error;
24mod executor;
25mod layout;
26mod lowering;
27mod stablehlo;
28
29#[cfg(feature = "pjrt")]
30mod pjrt;
31
32pub use error::{Error, Result};
33pub use executor::{XlaExecutor, XlaExecutorOptions};
34#[cfg(feature = "pjrt")]
35pub use pjrt::PjrtPlugin;
36pub use stablehlo::{StableHloModule, StableHloModuleFingerprint};
37
38/// Environment variable used for the default PJRT plugin path.
39///
40/// # Examples
41///
42/// ```
43/// use tenferro_xla::TENFERRO_PJRT_PLUGIN_ENV;
44///
45/// assert_eq!(TENFERRO_PJRT_PLUGIN_ENV, "TENFERRO_PJRT_PLUGIN");
46/// ```
47pub const TENFERRO_PJRT_PLUGIN_ENV: &str = "TENFERRO_PJRT_PLUGIN";
48
49/// Environment variable used for a GPU-specific PJRT plugin path.
50///
51/// # Examples
52///
53/// ```
54/// use tenferro_xla::TENFERRO_PJRT_GPU_PLUGIN_ENV;
55///
56/// assert_eq!(TENFERRO_PJRT_GPU_PLUGIN_ENV, "TENFERRO_PJRT_GPU_PLUGIN");
57/// ```
58pub const TENFERRO_PJRT_GPU_PLUGIN_ENV: &str = "TENFERRO_PJRT_GPU_PLUGIN";
59
60/// Lower a static-shaped graph program to StableHLO MLIR text.
61///
62/// # Examples
63///
64/// ```
65/// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
66/// use tenferro_xla::lower_to_stablehlo;
67///
68/// let trace = TraceContext::new();
69/// let x = trace.from_vec_col_major(vec![1], vec![3.0_f64]).unwrap();
70/// let mut compiler = GraphCompiler::new();
71/// let y = x.neg().unwrap();
72/// let program = compiler.compile(&y).unwrap();
73/// let module = lower_to_stablehlo(program.program()).unwrap();
74/// assert!(module.as_str().contains("stablehlo.negate"));
75/// ```
76///
77/// # Errors
78///
79/// Returns `Error::UnsupportedDType`, `Error::UnsupportedOp`, or
80/// `Error::NonStaticShape` for unsupported graph content, and
81/// `Error::InvalidProgram` for inconsistent graph metadata.
82pub fn lower_to_stablehlo(
83    program: &tenferro_runtime::program::SemanticProgram,
84) -> Result<StableHloModule> {
85    lowering::lower_to_stablehlo(program)
86}
87
88/// Lower a compiled graph to StableHLO MLIR text.
89///
90/// This is the preferred public lowering boundary for graph users. It consumes
91/// the backend-neutral [`CompiledGraph`](tenferro_runtime::CompiledGraph) view
92/// directly and does not route through native [`Runtime`](tenferro_runtime::Runtime)
93/// execution staging.
94///
95/// # Examples
96///
97/// ```
98/// use tenferro_runtime::{TraceContext, GraphCompiler, TracedTensor};
99/// use tenferro_xla::lower_compiled_to_stablehlo;
100///
101/// let trace = TraceContext::new();
102/// let x = trace.from_vec_col_major(vec![1], vec![3.0_f64]).unwrap();
103/// let mut compiler = GraphCompiler::new();
104/// let y = x.neg().unwrap();
105/// let program = compiler.compile(&y).unwrap();
106/// let module = lower_compiled_to_stablehlo(&program).unwrap();
107/// assert!(module.as_str().contains("stablehlo.negate"));
108/// ```
109///
110/// # Errors
111///
112/// Returns `Error::UnsupportedDType`, `Error::UnsupportedOp`, or
113/// `Error::NonStaticShape` for unsupported graph content, and
114/// `Error::InvalidProgram` for inconsistent graph metadata.
115pub fn lower_compiled_to_stablehlo(
116    program: &tenferro_runtime::CompiledGraph,
117) -> Result<StableHloModule> {
118    lowering::lower_to_stablehlo(program.program())
119}