Skip to main content

incin_core/
lib.rs

1//! Core tensor operations, static shape checking, and autograd for Incin.
2#![cfg_attr(not(feature = "std"), no_std)]
3
4#[macro_use]
5pub(crate) extern crate alloc;
6
7pub(crate) mod err;
8
9#[macro_use]
10mod operation_catalog;
11
12#[cfg(feature = "compiled")]
13pub mod compiled;
14pub mod dist;
15pub mod distributions;
16/// Structured errors returned by core and its extension crates.
17pub mod error {
18    pub use crate::err::{
19        BackendError, BackwardError, ConversionFailure, Error, ErrorMessage, FloatToIntPolicy,
20        NonFiniteSite, Result, convert_f64_to_i64,
21    };
22}
23pub mod exec;
24/// Capture-level graph representation shared by import and compiled previews.
25pub mod graph;
26mod graph_recording;
27
28/// Bounded model-file readers (GGUF metadata, format inspection).
29pub mod io;
30pub mod metrics;
31pub mod nn;
32#[cfg(feature = "std")]
33pub(crate) mod onnx_exporter;
34#[cfg(feature = "std")]
35pub(crate) mod onnx_pb;
36pub mod optim;
37pub mod resource;
38pub(crate) mod serialize;
39#[cfg(feature = "std")]
40/// Named serialization surface for applications that do not use the prelude.
41pub mod serialization {
42    pub use crate::serialize::{Format, ModelExt, STATE_FORMAT_VERSION};
43}
44#[cfg(feature = "std")]
45/// ONNX import and export helpers for graph interchange.
46pub mod onnx {
47    pub use crate::onnx_exporter::{OnnxExporter, OnnxImporter, export_to_onnx};
48}
49pub mod shapes;
50
51pub mod autograd;
52/// The tensor frontend: construction, operations, and device plumbing.
53pub mod tensor;
54pub use typenum;
55
56/// Implementation details used by procedural macros expanded inside this crate.
57#[doc(hidden)]
58pub mod __macro_support {
59    pub use crate::err::Result;
60    pub use crate::nn::{
61        ComputeStats, LayerNode, LayerStats, NamedLayers, ParameterVisitor, ShapeInfo,
62        StateMutVisitor, StatePath, StateSnapshot, StateVisitor, TrainMode, VisitParameters,
63        VisitState, VisitStateMut,
64    };
65    pub use crate::tensor::backend::{
66        Backend, StorageTransfer, SupportsDType, TransferTo, VariableBackend,
67    };
68    pub use crate::tensor::device::Device;
69    pub use crate::tensor::transfer::ToDevice;
70    pub use alloc::{collections::BTreeMap, format, string::String, vec::Vec};
71}
72
73/// Loss functions and reduction definitions.
74pub mod loss {
75    pub use crate::nn::loss::{
76        BCEWithLogitsLoss, BCEWithLogitsShape, BceReductionShape, CrossEntropyLoss,
77        CrossEntropyReductionShape, CrossEntropyShape, L1Loss, L1ReductionShape, L1Shape, MSELoss,
78        MSEShape, Mean, MseReductionShape, NoneReduction, Reduction, ReductionMode, Sum,
79    };
80}
81
82/// Unstable APIs that carry no compatibility guarantee.
83pub mod experimental {
84    #[cfg(feature = "compiled")]
85    /// Preview graph plans and symbolic guards. The matching
86    /// `incin-backends/compiled` feature supplies a CPU reference evaluator;
87    /// it is not an optimized compiler, deployment target, or portable
88    /// artifact ABI. Folding, prepacking, and fusion without executable
89    /// lowerings fail closed.
90    pub mod compiled {
91        pub use crate::compiled::{
92            AllocationPlanner, ArtifactHeader, ArtifactVersion, BoundedPlanTuner, BufferSlot,
93            CapturedGraph, CapturedNode, CompileOptions, CompiledArtifact, CompiledPlan,
94            ConstantFolder, DynamicShapePolicy, FusedKernel, FusionBlocker, FusionCandidate,
95            FusionPass, FusionPolicy, LivenessInterval, LivenessMap, MemoryPlan, PlanTuningReport,
96            ReproducibilityManifest, SavedTensorSet, ShapeBucket, ShapeGuard, TuningUnavailable,
97            WeightPrepacker,
98        };
99    }
100}
101
102/// Extension traits and operation descriptor contracts for backend authors.
103pub mod backend_authoring {
104    pub use crate::exec::dispatch::{
105        execute, execute_shaped, execute_shaped_with_payload, execute_with_payload,
106    };
107    pub use crate::exec::{
108        Alignment, AttributeContract, CanonicalOperation, Capabilities, CapabilityQuery,
109        CapabilityRegistry, Descriptor, DescriptorError, ExecutionContext, ExecutionDescriptor,
110        LogicalTensorMeta, LossScaling, OPERATION_CATALOG, Operation, OperationCatalogEntry,
111        OperationIdentity, OperationKey, PrecisionSpec, RuntimePrecisionPolicy, SupportLevel,
112        TensorMeta, UnsupportedReason, Validated, ValidatedInvocation, op,
113    };
114    pub use crate::shapes::ShapeBuf;
115    pub use crate::tensor::backend::{
116        AutogradBackend, Backend, Execute, ExecuteOutput, ExecutionRequest, HostInterop,
117        HostReadback, StorageBackend, StorageOutput, StorageTransfer, SupportsDType, TensorBackend,
118        TransferBackend, TransferTo, VariableBackend, VariableTransfer,
119    };
120    /// Read the tracing graph mid-flight, without draining it.
121    ///
122    /// Here rather than in the prelude because the caller is a backend's tape
123    /// emitting telemetry, not a user collecting a graph they built: the
124    /// public [`extract_graph`](crate::tensor::tracing::extract_graph) drains and is
125    /// the one a user wants. Keeping the snapshot hook in the authoring namespace
126    /// prevents a backend-only observation point from becoming ordinary user API.
127    pub use crate::tensor::tracing::tracing_graph_snapshot;
128
129    /// Exact operation markers, typed attributes, and storage-free metadata.
130    pub mod operations {
131        pub use crate::exec::catalog::{
132            AdamAttributes, AdamWAttributes, AdaptivePool2dAttributes, AddmmAttributes,
133            ArangeAttributes, ArgsortAttributes, AttentionAttributes, AvgPool2dAttributes,
134            AxisAttributes, AxisVarianceAttributes, BatchNormAttributes, CanonicalOperation,
135            ChunkAttributes, ClampAttributes, Conv1dAttributes, Conv2dAttributes,
136            ConvTranspose2dAttributes, CreationAttributes, DTypeAttributes, Descriptor,
137            DescriptorError, DeviceAttributes, DiagonalAttributes, DistributionAttributes,
138            DropoutAttributes, DuplicateIndexRule, EpsilonAttributes, FlattenAttributes,
139            FullAttributes, GroupNormAttributes, IndexReductionAttributes, LayerNormAttributes,
140            LerpAttributes, LinearAttributes, LinspaceAttributes, LogicalTensorMeta,
141            LossAttributes, LossReduction, NarrowAttributes, NoAttributes, NormAttributes,
142            OPERATION_CATALOG, Operation, OperationCatalogEntry, OperationKey, PadAttributes,
143            PixelShuffleAttributes, Pool2dAttributes, QuantizationAttributes, RecurrentAttributes,
144            RepeatAttributes, ScalarAttributes, ScatterAttributes, SgdAttributes, ShapeAttributes,
145            SliceAttributes, SplitAttributes, TopKAttributes, TransposeAttributes,
146            UnfoldAttributes, ValidatedInvocation, VarianceAttributes, catalog_entry, op,
147        };
148        // The enums that every classification field of `OperationCatalogEntry`
149        // is typed as. The entry is re-exported above, so without these a
150        // backend author can read `row.site` or `row.profile` but cannot write
151        // down the type of what they read, or match on it exhaustively.
152        pub use crate::exec::catalog::{
153            BroadcastingRule, DTypeRule, EmptyRule, ExecutionSite, GradientRule, LayoutRule,
154            NumericRule, OutputRule, SemanticProfile,
155        };
156        #[cfg(feature = "std")]
157        pub use crate::exec::catalog::{CapturedDescriptor, DescriptorCaptureError};
158    }
159}
160
161/// Expert type-level shape vocabulary kept outside the normal prelude.
162pub mod types {
163    pub use crate::shapes::{ConcreteStaticExtent, DimCons, Nil, ReplaceAt, StructuralConcatShape};
164}
165
166/// Core prelude re-exporting common types, neural network modules, shapes, and backend traits.
167pub mod prelude {
168    pub use super::err::{
169        BackendError, BackwardError, ConversionFailure, Error, ErrorMessage, FloatToIntPolicy,
170        NonFiniteSite, Result, convert_f64_to_i64,
171    };
172    pub use crate::SeqTy;
173    pub use half::{bf16, f16};
174
175    pub use crate::dim;
176
177    pub use crate::dist::{Local, Placement, PlacementKind};
178    pub use crate::distributions::{Bernoulli, Distribution, Exponential, Gumbel, Normal, Uniform};
179
180    pub use super::exec::{AxisSet, RankSupport};
181    pub use super::tensor::matmul::{StaticDim, StaticOrNamedDim};
182    pub use crate::metrics::{Accuracy, ConfusionMatrix, F1Score, MSE, Metric, Precision, Recall};
183    pub use crate::nn::{
184        activation::{GELU, ReLU, Sigmoid, Softmax, Swish, Tanh},
185        avg_pool2d::AvgPool2d,
186        batch_norm::{BatchNorm2d, BatchNorm2dBuilder, BatchNormShape, batch_norm2d},
187        conv1d::{Conv1d, Conv1dBuilder, Conv1dShape, conv1d},
188        conv2d::{Conv2d, Conv2dBuilder, Conv2dShape, conv2d},
189        dropout::Dropout,
190        embedding::{Embedding, EmbeddingBuilder, EmbeddingShape, embedding},
191        flatten::{Flatten, FlattenAxes, StructuralFlatten},
192        init::{self, Fan, Init, InitContext, InitPlan, ParameterRole},
193        layer_norm::{LayerNorm, LayerNormBuilder, LayerNormShape, layer_norm},
194        linear::{Linear, LinearBuilder, LinearShape, linear},
195        loss::{
196            BCEWithLogitsLoss, CrossEntropyLoss, L1Loss, MSELoss, Mean, NoneReduction, Reduction,
197        },
198        lstm::{LSTM, LSTMBuilder, LSTMCell, LSTMCellBuilder, LstmShape, lstm, lstm_cell},
199        max_pool2d::MaxPool2d,
200        module::{
201            LayerNode, Module, NamedLayers, ParameterVisitor, Sequential, ShapeInfo, TrainMode,
202            VisitParameters,
203        },
204        optional::{False, OptionalField, True},
205        param::{Buffer, Frozen, Param, TrainState, Trainable},
206        rms_norm::{RMSNorm, RMSNormBuilder, RMSNormShape, rms_norm},
207        rnn::{RNN, RNNBuilder, RNNCell, RNNCellBuilder, RnnShape, rnn, rnn_cell},
208        state::{
209            StateMutVisitor, StatePath, StateRole, StateSnapshot, StateSnapshotVisitor, StateValue,
210            StateVisitor, VisitState, VisitStateMut, collect_state, load_state,
211        },
212        stats::{ComputeStats, LayerStats, ModelStats},
213    };
214    pub use crate::seq;
215    pub use crate::tensor::ops::index::IndexSpec;
216    #[cfg(feature = "distributed")]
217    pub use incin_macros::mesh;
218    pub use incin_macros::{axis, i, module, s, shape};
219
220    pub use super::shapes::prelude::{
221        AdaptiveAvgPool2dShape, AppendDim, Axis, AxisIdentity, AxisKey, AxisSchema, AxisTag,
222        BroadcastDim, BroadcastExtent, BroadcastShape, CheckedNumel, ConcatShape,
223        ConcreteStaticExtent, ConstDim, ConvOutDim, Dim, DimCons, DimensionConstraint, DynShape,
224        ElementCount, EndsWith, FlatDim, HasChannels1D, HasChannels2D, INLINE_RANK, NamedDim, Nil,
225        OperationKind, Pool2dShape, ProductDims, RankExpectation, Ranked, ReplaceAt,
226        ReplaceLastDim, ReshapeShape, SameCount, Scalar, Shape, ShapeArgs, ShapeBuf, ShapeError,
227        ShapeSpec, ShapeValue, SpatialConv1d, SpatialConv2d, SpatialOut, StackShape, StrideBuf,
228        StructuralConcatShape, SwapAt, TryConcatShape, TryReshape, broadcast_dim_slices,
229        checked_numel_from_dims, shape_buf_from_dims, spatial_out_size,
230    };
231    #[cfg(feature = "distributed")]
232    pub use super::tensor::prelude::PlacedTensorError;
233    pub use super::tensor::prelude::{
234        ArgInto, BestDevice, BestDeviceAt, BoolDType, BuiltinDType, CheckedByteLen, ConstDType,
235        ConstDevice, Cpu, DType, DTypeDescriptor, DTypeId, DTypeKey, DTypeKind, Device, DeviceId,
236        DeviceKind, DevicePreference, DeviceSet, DeviceSetError, Dyn, FloatDType, Grad, GradJoin,
237        IntDType, JoinedGrad, MatMulShape, NoGrad, PlainDType, Q8_0, QuantDType, RequiresGrad,
238        Tensor, TensorArgs, TensorArgsData, TensorElement, ToDevice, checked_byte_len_from_dims,
239    };
240    #[cfg(feature = "cuda")]
241    pub use super::tensor::prelude::{Cuda, CudaN};
242    #[cfg(feature = "metal")]
243    pub use super::tensor::prelude::{Metal, MetalN};
244    #[cfg(feature = "wgpu")]
245    pub use super::tensor::prelude::{Wgpu, WgpuN};
246    pub use crate::distributions::TensorDistributionExt;
247    #[cfg(feature = "std")]
248    pub use crate::io::{
249        GgufExporter, GgufMetadata, MlxExporter, QuantScheme, ResourceLimits, inspect_file,
250    };
251    #[cfg(feature = "std")]
252    pub use crate::nn::save::{load_safetensors, load_safetensors_snapshot, save_safetensors};
253    #[cfg(feature = "std")]
254    pub use crate::onnx::{OnnxExporter, OnnxImporter, export_to_onnx};
255    pub use crate::optim::{
256        Adam, AdamW, ConstantLR, Gradients, LRScheduler, LinearLR, Optimizer, ParameterGroup, SGD,
257    };
258    #[cfg(feature = "std")]
259    pub use crate::optim::{CosineAnnealingLR, StepLR};
260    #[cfg(feature = "std")]
261    pub use crate::serialize::{Format, ModelExt};
262    pub use crate::tensor::ops::reduce::ReduceSelector;
263    pub use alloc::boxed::Box;
264    pub use alloc::collections::BTreeMap;
265    pub use alloc::format;
266    pub use alloc::string::{String, ToString};
267    pub use alloc::vec::Vec;
268    pub use typenum;
269}
270
271/// Structural shape cursors retained for low-level and legacy integrations.
272/// Ordinary application code should prefer signed numeric axis selectors.
273pub mod advanced {
274    pub use crate::shapes::idx::{
275        AxisCursor, DimIdx, Ellipsis, ForwardAxis, InferDim, NamedAxisLookup, Next, ReshapeTarget,
276        ReverseAxis, Slice, SliceIdx, SliceTarget, StaticCursor,
277    };
278    pub use crate::shapes::prelude::{At, ReduceAt, ReduceKeepAt, RemoveAt, SwapAt};
279    pub use crate::shapes::{
280        AxisSelector, FromEnd, Here, NamedAxisSelector, StaticAxis, ToAxisIndex,
281    };
282    pub use crate::typenum;
283    pub use incin_macros::idx;
284}
285
286pub use incin_macros::axis;