Skip to main content

tenferro_runtime/
lib.rs

1//! Traced graph runtime and extension dispatch infrastructure for tenferro.
2//!
3//! This crate owns graph construction, lowering to execution IR, graph
4//! execution, and backend-parametric extension runtime dispatch. Standard
5//! operations are lowered through the runtime's internal operation vocabulary;
6//! tensor storage and backend kernels live in `tenferro-tensor`.
7//!
8//! Use this crate directly when you want concrete tensor helpers or reusable
9//! traced graph execution without depending on `tenferro-ad`. Start with
10//! [`TypedTensor`] when the scalar type is fixed in Rust, [`Tensor`] when dtype
11//! is selected at runtime, and [`TracedTensor`] plus [`GraphCompiler`] and
12//! [`Runtime`] when the same expression should be compiled once and run
13//! repeatedly. Operation-family crates such as `tenferro-einsum`,
14//! `tenferro-linalg`, and `tenferro-fft` register extension runtimes through
15//! runtime engine registrations when compiled execution reaches those
16//! operations.
17//!
18//! User-facing guides live at
19//! <https://tensor4all.org/tenferro-rs/guides/choosing-an-api.html> and
20//! <https://tensor4all.org/tenferro-rs/guides/execution-models.html>.
21//!
22//! `add` has no settings, so it has no options type and no `_with` form; only
23//! operations with semantic options (such as `dot_general`) have one:
24//!
25//! ```compile_fail,E0599
26//! use tenferro_cpu::CpuEngine;
27//! use tenferro_runtime::{CoreOps, Tensor};
28//!
29//! let a = Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
30//! let _ = a.add_with(&a, &mut CpuEngine::serial());
31//! ```
32//!
33//! ```compile_fail,E0432
34//! use tenferro_runtime::AddOptions;
35//! ```
36//!
37//! # Examples
38//!
39//! ```rust
40//! use tenferro_cpu::CpuEngine;
41//! use tenferro_runtime::{TraceContext, ExecutionEngine, GraphCompiler, Runtime, TracedTensor};
42//!
43//! let trace = TraceContext::new();
44//! let x = trace.from_vec_col_major(vec![2], vec![1.0_f64, 2.0]).unwrap();
45//! let y = (&x + &x).unwrap();
46//! let mut compiler = GraphCompiler::new();
47//! let program = compiler.compile(&y).unwrap();
48//! // One caller-held engine runs every slot of the prepared program.
49//! let mut engine = CpuEngine::serial();
50//! let mut builder = Runtime::builder();
51//! builder
52//!     .register_engine(tenferro_cpu::runtime_engine_registration(&engine).unwrap())
53//!     .unwrap();
54//! let runtime = builder.build().unwrap();
55//! let prepared = runtime.prepare(&program, &[], &[engine.target()]).unwrap();
56//! let out = runtime
57//!     .run(&mut [&mut engine], &prepared, &[])
58//!     .unwrap()
59//!     .pop()
60//!     .unwrap()
61//!     .into_tensor(&mut engine)
62//!     .unwrap();
63//! assert_eq!(out.as_slice::<f64>().unwrap(), &[2.0, 4.0]);
64//! ```
65
66#[doc(hidden)]
67pub mod ad_support;
68mod api;
69mod checkpoint;
70mod compiler;
71#[doc(hidden)]
72pub mod composite;
73pub mod error;
74mod exec;
75pub mod extension;
76pub mod extension_cache;
77mod extension_execution_context;
78pub mod graph;
79mod metadata;
80pub mod prelude;
81pub mod program;
82pub mod runtime;
83#[doc(hidden)]
84pub mod scalar_semantics;
85#[doc(hidden)]
86pub mod scale;
87mod segment;
88mod shape_constraint;
89mod shape_infer;
90mod shape_packing;
91pub mod sym_dim;
92mod tensor;
93mod trace;
94mod trace_ops;
95pub mod traced;
96mod typed_tensor;
97
98pub use api::{CoreOps, CoreRepr, SelectCondition, SelectOperand};
99pub use compiler::{CompilerOptions, OptimizerConfig};
100pub use error::{
101    ContextId, Error, ErrorPhase, Result, RuntimeFailureReasonRef, ShapeConstraintEvalError,
102};
103pub use extension_cache::{
104    ExtensionCacheKey, ExtensionCacheLimits, ExtensionCacheSelector, ExtensionCacheStore,
105};
106pub use extension_execution_context::ExtensionExecutionContext;
107pub use graph::{CompiledGraph, GraphCompiler};
108pub use runtime::{
109    assemble_executable_engine_registration, assemble_preparation_only_engine_registration,
110    CacheInFlightBehavior, CacheOwnerError, CacheOwnerFailure, CacheOwnerId, CoreCapabilityBundle,
111    CoreCapabilityBundleBuilder, CoreCapabilityKind, CorePrepareContext, Determinism,
112    DotGeneralPreparation, DotGeneralPrepareRequest, ElementwisePrepareRequest, ElementwiseRuntime,
113    EngineExecutionContractError, EngineId, EngineRegistration, EngineRegistrationMetadata,
114    EngineSnapshotView, EngineTarget, ErasedExecutionContext, EventDomainDriver, EventDomainError,
115    EventDomainId, EventDomainOperation, EventDomainRun, EventToken,
116    ExecutableEngineRegistrationConfig, ExecutionContextIdentity, ExecutionContextMismatch,
117    ExecutionEngine, ExecutionPolicy, ExecutionPolicyError, ExtensionEngine, ExtensionModule,
118    ExtensionModuleError, ExtensionModuleId, ExtensionModuleRegistrar, ExtensionPlanningConfig,
119    ExtensionPrepareRequest, HardwareClassId, IdentityError, IdentityKind,
120    ImmediateEventDomainDriver, IndexingPrepareRequest, IndexingRuntime, InputIngressContract,
121    InputIngressContractError, InputPlacementContract, InputSignature, InputSignatureContract,
122    InputSignatureEntry, InputSignatureError, InputSpecializationProjection,
123    InputSpecializationRequirements, InputSpecializationRequirementsBuilder,
124    InputSpecializationRequirementsError, LayoutClass, LayoutPrepareRequest, LayoutProjection,
125    LayoutRuntime, LayoutSpecialization, Output, PlacementConstraintError, PlacementProjection,
126    PlacementSpecialization, PreparationKeySummary, PreparationOnlyEngineRegistrationConfig,
127    PrepareCapability, PrepareError, PrepareOptions, PrepareOptionsKey, Prepared,
128    PreparedOperation, PreparedOperationBinding, PreparedOperationExecutor,
129    PreparedOperationExecutorHandle, PreparedOperationHandle, PreparedOperationPlan,
130    PreparedPlanCacheLimits, PreparedPlanCacheStats, ProgramPlacementConstraint,
131    ProviderContractError, ProviderDeviceIdentity, ProviderId, RankRequirement,
132    ReductionPrepareRequest, ReductionRuntime, RegistrationIdentity, RegistrationKey,
133    ResidentOutputContract, ResolvedPlanningConfig, ResolvedPlanningKey, ResolvedProgramPlacement,
134    Runtime, RuntimeCacheError, RuntimeCacheOwner, RuntimeCacheStats, RuntimeConfigBuilder,
135    RuntimeConfigError, RuntimeConfigSnapshot, RuntimeEpoch, RuntimeId, RuntimeInputContract,
136    RuntimeReconfiguration, RuntimeReconfigureError, RuntimeStateError, SpecializationError,
137    SpecializationProjection, SpecializationRequirements, StorageClass, TransferEndpoint,
138    TransferError, TransferProvider, TransferProviderContractError, TransferRequest,
139    UnsupportedReason,
140};
141#[doc(hidden)]
142pub use shape_constraint::ShapeGuard;
143pub use shape_packing::TracedSliceBuilder;
144pub use sym_dim::SymDim;
145pub use tenferro_ops::ShapeRelation;
146pub use tenferro_tensor::{
147    CacheStats, CompareDir, DType, DotGeneralConfig, Engine, GatherConfig, MemoryKind, PadConfig,
148    ScatterConfig, SliceConfig, Tensor, TensorRead, TensorScalar, TensorValue, TensorView,
149    TypedTensor, TypedTensorView,
150};
151pub use trace::{TraceContext, TraceValue, TracedGraph};
152
153pub use traced::TracedTensor;