Skip to main content

incin/
lib.rs

1//! # Incin
2//!
3//! Incin is a lightweight, strictly-typed neural network framework for Rust, built with an emphasis on **shape safety** at compile time, while remaining fully compatible with dynamic runtime shapes. It is designed to catch tensor dimension mismatches during compilation using Rust's powerful type system, rather than failing at runtime.
4//!
5//! ## Key Features
6//!
7//! * **Compile-time Shape Verification**: Write tensor operations with `Tensor<s![Batch, Channels, Height, Width], Backend>` and let the compiler guarantee that shapes align for operations like `matmul`, `conv2d`, `concat`, etc.
8//! * **Backends**: CPU is enabled by default and is the complete backend - every backend-executable operation in the canonical catalog has a CPU executor. The native CUDA, WGPU, and Metal backends are explicit opt-ins and are previews: each covers a documented subset of the catalog, so a model built from the layers in this crate trains on CPU. `docs/capabilities.md` is generated from the backend registrations and answers this per operation. The third-party Candle adapter is available through the `external-candle` feature under `external::candle`.
9//! * **Macro-driven Ergonomics**: Stable macros such as `s![]`, `shape![]`, `axis![]`, and `i![]` define shapes, selectors, and indexing. Partial ONNX expansion is available separately as `experimental::model!`.
10//! * **Zero-Cost Abstractions**: The static shape information (`typenum`) exists entirely in the type system and evaporates at runtime, introducing zero overhead to the underlying backend operations.
11//!
12//! ## Quick Start
13//!
14//! Tensors are allocated by starting from a target device such as `Cpu`:
15//!
16//! ```rust
17//! use incin::prelude::*;
18//!
19//! // Statically shaped, zero-filled: (Batch=2, Channels=3, Height=224, Width=224)
20//! let x = Cpu.zeros(shape![2, 3, 224, 224]).unwrap();
21//! ```
22//!
23//! [`TargetExt`](prelude::TargetExt) documents the rest of the creation API
24//! (`randn`, `rand`, `ones`, `full`, `arange`, `linspace`, `tensor`, dynamic
25//! runtime shapes) with a runnable example on every method.
26
27//!
28//! ## Neural Network Modules
29//!
30//! Building and running a model is straightforward using the `#[module]` attribute and the
31//! `seq!`/`SeqTy!` macros - `SeqTy!` names the same nested `Sequential<...>`
32//! type that `seq!` builds a value of, so a layer list only needs to be written once per meaning
33//! instead of the field type being hand-nested separately:
34//!
35//! ```rust,no_run
36//! use incin::prelude::*;
37//!
38//! type Backend = IncinBackend<Cpu>;
39//!
40//! #[module(no_shape_info)]
41//! pub struct MLP {
42//!     net: SeqTy!(
43//!         Linear<s![768, 256], Backend>,
44//!         ReLU,
45//!         Linear<s![256, 10], Backend>
46//!     ),
47//! }
48//!
49//! impl MLP {
50//!     pub fn new() -> Result<Self> {
51//!         Ok(Self {
52//!             net: seq!(
53//!                 Linear::<s![768, 256], Backend>::build(())?,
54//!                 ReLU,
55//!                 Linear::<s![256, 10], Backend>::build(())?
56//!             )
57//!         })
58//!     }
59//!
60//!     pub fn forward(&self, x: Tensor<s![2, 768], Backend>) -> Result<Tensor<s![2, 10], Backend, f32, Grad>>
61//!     {
62//!         self.net.forward(x)
63//!     }
64//! }
65//! ```
66//!
67//! ## ONNX Import
68//!
69//! ONNX expansion is currently partial and fail-closed. Stateless graphs using
70//! the documented supported subset can produce typed eager code. Models with
71//! initializers, unknown rank, control flow, custom domains, or unsupported
72//! nodes are rejected during macro expansion; no weights or metadata are
73//! invented.
74// mdBook's standalone tester does not receive Cargo's `--extern` arguments.
75// Keep a Cargo-backed doctest mirror so the user-facing chapters are checked
76// against the real facade and feature set.
77
78#[cfg(all(doctest, feature = "backend-authoring"))]
79#[doc = concat!(
80    include_str!("../../../docs/book/src/introduction.md"),
81    include_str!("../../../docs/book/src/installation.md"),
82    include_str!("../../../docs/book/src/editor_integrations.md"),
83    include_str!("../../../docs/book/src/quickstart.md"),
84    include_str!("../../../docs/book/src/tensors.md"),
85    include_str!("../../../docs/book/src/shapes.md"),
86    include_str!("../../../docs/book/src/advanced_shapes.md"),
87    include_str!("../../../docs/book/src/autograd.md"),
88    include_str!("../../../docs/book/src/building_models.md"),
89    include_str!("../../../docs/book/src/sequential.md"),
90    include_str!("../../../docs/book/src/transformer.md"),
91    include_str!("../../../docs/book/src/training.md"),
92    include_str!("../../../docs/book/src/data_loading.md"),
93    include_str!("../../../docs/book/src/quantization.md"),
94    include_str!("../../../docs/book/src/distributed.md"),
95    include_str!("../../../docs/book/src/metrics.md"),
96    include_str!("../../../docs/book/src/saving_loading.md"),
97    include_str!("../../../docs/book/src/backends.md"),
98    include_str!("../../../docs/book/src/target_api.md"),
99    include_str!("../../../docs/book/src/backend_authoring.md"),
100    include_str!("../../../docs/book/src/proofs_to_execution.md"),
101    include_str!("../../../docs/book/src/custom_operations.md"),
102    include_str!("../../../docs/book/src/macros.md"),
103    include_str!("../../../docs/book/src/feature_flags.md"),
104    include_str!("../../../docs/book/src/invariants.md"),
105    include_str!("../../../docs/book/src/errors.md"),
106    include_str!("../../../docs/book/src/experimental.md"),
107    include_str!("../../../docs/book/src/pytorch_cheatsheet.md"),
108    include_str!("../../../docs/book/src/release_notes.md"),
109    include_str!("../../../docs/book/src/whats_not_finished.md"),
110    include_str!("../../../docs/book/src/deep_architecture.md"),
111    include_str!("../../../docs/book/src/deep_type_semantics.md"),
112    include_str!("../../../docs/book/src/deep_lowering.md"),
113    include_str!("../../../docs/book/src/deep_proofs.md"),
114    include_str!("../../../docs/book/src/deep_macros_internals.md"),
115)]
116mod book_docs {}
117
118#[cfg(all(doctest, feature = "backend-authoring"))]
119mod target_api_book_docs {}
120
121extern crate alloc;
122
123pub use incin_backends::IncinBackend;
124pub use incin_core::autograd::Gradients;
125pub use incin_core::error::{
126    BackendError, BackwardError, ConversionFailure, Error, ErrorMessage, FloatToIntPolicy,
127    NonFiniteSite, Result, convert_f64_to_i64,
128};
129pub use incin_core::nn::module::Module;
130pub use incin_core::nn::param::{Buffer, TrainState};
131pub use incin_core::nn::state::{
132    StateMutVisitor, StatePath, StateRole, StateSnapshot, StateValue, StateVisitor, VisitState,
133    VisitStateMut,
134};
135pub use incin_core::optim::{
136    Adam, AdamW, ConstantLR, LRScheduler, LinearLR, Optimizer, OptimizerBackend, SGD,
137};
138#[cfg(feature = "std")]
139pub use incin_core::optim::{CosineAnnealingLR, StepLR};
140pub use incin_core::shapes::{Dyn, DynShape, Shape};
141pub use incin_core::tensor::device::{
142    Cpu, Device, DeviceId, DeviceKind, DevicePreference, DeviceSet, DeviceSetError,
143};
144pub use incin_core::tensor::dtype::{
145    BoolDType, BuiltinDType, ConstDType, DType, DTypeDescriptor, DTypeId, DTypeKey, DTypeKind,
146    FloatDType, IntDType, PlainDType, Q8_0, QuantDType, TensorElement, bf16, f16,
147};
148pub use incin_core::tensor::grad::{Grad, NoGrad, RequiresGrad};
149
150/// Incin's target-backed adapter for model-ready MNIST batches.
151#[derive(Clone)]
152pub struct TargetBatch<T>(pub T);
153
154impl<T> incin_data::vision::mnist::MnistBatchTarget for TargetBatch<T>
155where
156    T: incin_backends::target::TensorTarget + Clone + Send + Sync + 'static,
157    T::Backend: incin_core::backend_authoring::HostInterop,
158    <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<f32>: Send + 'static,
159    <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<u8>: Send + 'static,
160    <T::Device as incin_core::tensor::device::Device>::Field: Send + 'static,
161{
162    type Images = incin_backends::target::TargetTensor<T, incin_core::shapes::Dyn, f32>;
163    type Labels = incin_backends::target::TargetTensor<T, incin_core::shapes::Dyn, u8>;
164
165    fn batch(
166        &self,
167        images: Vec<f32>,
168        labels: Vec<u8>,
169        batch_size: usize,
170    ) -> incin_data::BatchResult<(Self::Images, Self::Labels)> {
171        use incin_backends::target::TargetExt;
172
173        let images = self
174            .0
175            .tensor_from_vec(images, vec![batch_size, 1, 28, 28])
176            .map_err(|error| incin_data::DataError::InvalidBatch(error.to_string()))?;
177        let labels = self
178            .0
179            .tensor_from_vec(labels, vec![batch_size])
180            .map_err(|error| incin_data::DataError::InvalidBatch(error.to_string()))?;
181        Ok((images, labels))
182    }
183}
184
185/// Target-value MNIST loader extension for the facade crate.
186pub trait MnistTargetExt {
187    /// Builds a model-ready loader on the supplied target value.
188    fn loader_on<T>(
189        self,
190        target: T,
191    ) -> incin_data::loader::DataLoaderBuilder<
192        incin_data::vision::mnist::MnistDataset,
193        incin_data::vision::mnist::TensorCollate<TargetBatch<T>>,
194    >
195    where
196        T: incin_backends::target::TensorTarget + Clone + Send + Sync + 'static,
197        T::Backend: incin_core::backend_authoring::HostInterop,
198        <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<f32>: Send + 'static,
199        <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<u8>: Send + 'static,
200        <T::Device as incin_core::tensor::device::Device>::Field: Send + 'static;
201}
202
203impl MnistTargetExt for incin_data::vision::mnist::MnistDataset {
204    fn loader_on<T>(
205        self,
206        target: T,
207    ) -> incin_data::loader::DataLoaderBuilder<
208        incin_data::vision::mnist::MnistDataset,
209        incin_data::vision::mnist::TensorCollate<TargetBatch<T>>,
210    >
211    where
212        T: incin_backends::target::TensorTarget + Clone + Send + Sync + 'static,
213        T::Backend: incin_core::backend_authoring::HostInterop,
214        <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<f32>: Send + 'static,
215        <T::Backend as incin_core::backend_authoring::StorageBackend>::Storage<u8>: Send + 'static,
216        <T::Device as incin_core::tensor::device::Device>::Field: Send + 'static,
217    {
218        incin_data::vision::mnist::MnistDataset::loader(self, TargetBatch(target))
219    }
220}
221
222#[cfg(feature = "cuda")]
223pub use incin_core::tensor::device::{Cuda, CudaN};
224#[cfg(feature = "metal")]
225pub use incin_core::tensor::device::{Metal, MetalN};
226#[cfg(feature = "wgpu")]
227pub use incin_core::tensor::device::{Wgpu, WgpuN};
228
229pub use incin_core::dim;
230pub use incin_macros::module;
231
232/// Expert type-level and physical-layout contracts that are not part of the
233/// ordinary user prelude.
234pub mod types {
235    pub use incin_core::shapes::{
236        ConcreteStaticExtent, DimCons, Nil, ReplaceAt, StructuralConcatShape,
237    };
238
239    /// Physical storage encoding used by dtype descriptors and serializers.
240    pub mod dtype {
241        pub use incin_core::tensor::dtype::StorageEncoding;
242    }
243}
244
245/// Implementation details used by exported procedural macros.
246///
247/// This module is public solely because macro expansion occurs in the
248/// consumer crate. Its contents are not part of the stable end-user facade.
249#[doc(hidden)]
250pub mod __macro_support {
251    pub use alloc::{collections::BTreeMap, format, string::String, vec::Vec};
252    pub use incin_core::backend_authoring::Backend;
253    pub use incin_core::backend_authoring::{
254        Capabilities, Execute, StorageTransfer, SupportsDType, TransferTo, VariableBackend, op,
255    };
256    pub use incin_core::error::Result;
257    #[cfg(feature = "std")]
258    pub use incin_core::nn::save::load_safetensors;
259    pub use incin_core::nn::{ComputeStats, LayerStats};
260    pub use incin_core::nn::{
261        LayerNode, NamedLayers, ParameterVisitor, ShapeInfo, StateMutVisitor, StatePath,
262        StateVisitor, TrainMode, VisitParameters, VisitState, VisitStateMut,
263    };
264    pub use incin_core::tensor::device::Device;
265    pub use incin_core::tensor::ops::index::IndexSpec;
266    pub use incin_core::tensor::transfer::ToDevice;
267}
268
269/// Unstable APIs that carry no compatibility guarantee.
270pub mod experimental {
271    /// Partial, fail-closed model import macros.
272    pub use incin_macros::{import_model, model};
273    #[cfg(feature = "distributed")]
274    /// Experimental distributed declaration macros.
275    pub use incin_macros::{mesh, parallel, placement};
276
277    #[cfg(feature = "compiled")]
278    /// Preview compiled-plan inspection and CPU reference evaluation.
279    ///
280    /// This namespace is deliberately excluded from Incin's stable API. It is
281    /// a CPU reference evaluator and inspection surface, not an optimized
282    /// compiler, deployment target, or portable artifact ABI. Optimizations
283    /// that lack an executable lowering fail closed.
284    pub mod compiled {
285        pub use incin_backends::cpu::{
286            CpuBuffer, CpuCompiledFunction, CpuCompiledInvocation, CpuCompiledPlan,
287            CpuCompiledSupport, CpuStorage, compiled_support,
288        };
289        pub use incin_core::experimental::compiled::{
290            AllocationPlanner, ArtifactHeader, ArtifactVersion, BoundedPlanTuner, BufferSlot,
291            CapturedGraph, CapturedNode, CompileOptions, CompiledArtifact, CompiledPlan,
292            ConstantFolder, DynamicShapePolicy, FusedKernel, FusionBlocker, FusionCandidate,
293            FusionPass, FusionPolicy, LivenessInterval, LivenessMap, MemoryPlan, PlanTuningReport,
294            ReproducibilityManifest, SavedTensorSet, ShapeBucket, ShapeGuard, TuningUnavailable,
295            WeightPrepacker,
296        };
297        /// Minimal graph and descriptor-building types for the preview CPU
298        /// evaluator. These remain experimental with the rest of this module.
299        pub use incin_core::{
300            exec::{
301                OperationIdentity,
302                catalog::{CapturedDescriptor, Descriptor, LogicalTensorMeta, NoAttributes, op},
303            },
304            graph::{AttributeValue, DescriptorPayload, Graph},
305            shapes::OperationKind,
306            tensor::{device::DeviceId, dtype::DTypeId},
307        };
308    }
309
310    #[cfg(feature = "autotune")]
311    /// Preview tuning configuration and inspection types.
312    pub mod tuning {
313        pub use incin_backends::tuning::{
314            AlignmentClass, AutotunePolicy, CacheLimits, CacheRecovery, CompilerFingerprint,
315            DTypePolicyId, DeviceFingerprint, KernelSignature, PersistentTuningCache, RankClass,
316            SelectionSource, TuningContext, TuningEnvironmentFingerprint, TuningExplain,
317            TuningProvenance, TuningScope, TuningSelection,
318        };
319    }
320
321    #[cfg(feature = "distributed")]
322    /// Experimental distributed planning and placement contracts.
323    pub mod distributed {
324        /// Typed logical mesh declarations and runtime binding contracts.
325        pub mod mesh {
326            pub use incin_core::dist::mesh::{
327                AXIS_COUNT, BindError, CollectiveGroups, Data, DeviceIdentity, DeviceMesh,
328                LinkClass, MeshAxis, MeshId, MeshSpec, Pipeline, ProcessLayout, TensorParallel,
329                TopologyFingerprint, TopologyProbe, TransportVersion, ValidMesh,
330            };
331        }
332
333        #[cfg(feature = "distributed-nccl")]
334        pub use incin_backends::dist::{
335            BootstrapRole, NcclBuffer, NcclEvent, NcclTopology, NcclTransport, NcclTransportError,
336            TwoRankBootstrapConfig,
337        };
338        pub use incin_core::dist::{
339            ActivationCheckpoint, AgreedPlan, CollectiveDType, CollectiveDescriptor,
340            CollectiveError, CollectiveKind, CollectivePlan, CollectivePlanBuilder,
341            CollectiveReductionDType, CollectiveTag, CommunicationEvidence, CompletePlacement,
342            ConstPlacement, ContextError, ContextFailure, DataParallelDType, DataParallelError,
343            DataParallelPlan, DataParallelPlanBuilder, DistributedContext,
344            DistributedContextHandle, DistributedContextState, DistributedError,
345            DistributedIdentity, DistributedInputs, DistributedRule, ElementwisePlacement,
346            FsdpError, FsdpMemoryReport, FsdpParameterDescriptor, FsdpParameterId, FsdpPlan,
347            FsdpPlanBuilder, GPipe, GradientDescriptor, GradientId, GroupId, HybridPlanDType,
348            HybridPlanError, HybridPlanReport, HybridPlanner, HybridWorkload,
349            LOCAL_CUDA_DEVICE_ENV, LegalTransition, Local, Max, Mean, MemoryLimit, Min,
350            OneForwardOneBackward, ParallelOptions, ParallelStrategy, ParallelStrategyKind,
351            Partial, PartialReduction, PipelineAction, PipelineBoundaryId, PipelineClock,
352            PipelineDType, PipelineError, PipelinePhase, PipelinePlan, PipelinePlanBuilder,
353            PipelineSchedule, PipelineScheduleDescriptor, PipelineStage, PipelineTransfer,
354            PipelineTransferDescriptor, Placement, PlacementAxis, PlacementBuf, PlacementKind,
355            PlacementOn, PlacementTransition, PlacementTransitionRule, PlanError, PlanObjective,
356            PlanSummary, PlannedCollectiveTransition, PlanningCollectiveKind, Prod, RANK_ENV,
357            RENDEZVOUS_ADDR_ENV, RENDEZVOUS_TIMEOUT_MS_ENV, RUN_ID_ENV, ReduceShardedAxis,
358            RejectedStrategy, Replicated, RunId, SequenceToken, ShardDivisible, ShardEvidence,
359            ShardRemainderPolicy, Sharded, StaticParallelOptions, StaticPipelineSchedule,
360            StaticTwoRank, StrategyCandidate, StrategyRejection, StrategySet, StreamId, Sum,
361            TWO_RANK_WORLD, TensorParallelCollective, TensorParallelDType,
362            TensorParallelDescriptor, TensorParallelDimension, TensorParallelError,
363            TensorParallelId, TensorParallelPlan, TensorParallelPlanBuilder, TwoRankDataParallel,
364            TwoRankPipeline, TwoRankPlanningTopology, TwoRankTensorParallel, TwoWayShard,
365            ValidatedDistributed, WORLD_SIZE_ENV, WorkloadField, ZeROStage, preflight,
366            validate_collective_dtype, validate_collective_reduction, validate_data_parallel_dtype,
367            validate_hybrid_plan_dtype, validate_microbatches, validate_pipeline_dtype,
368            validate_pipeline_stage, validate_shard, validate_tensor_parallel_dtype,
369            validate_transition, validate_two_way_extent,
370        };
371        #[cfg(feature = "std")]
372        pub use incin_core::dist::{
373            DynRendezvousConfig, RankLaunch, RendezvousEndpoint, StaticRendezvousConfig,
374            TwoRankLaunchPlan,
375        };
376    }
377
378    #[cfg(feature = "train")]
379    /// Preview training planner and trainer.
380    pub mod training {
381        pub use crate::train::{
382            Decision, FitOutcome, HostMachine, Machine, Plan, TrainError, Trainer, TrainerBuilder,
383        };
384
385        /// Preview training-plan report renderer.
386        pub mod plan_report {
387            pub use crate::plan_report::{EXIT_OK, EXIT_USAGE, run, run_with_machine};
388        }
389    }
390
391    #[cfg(feature = "std")]
392    /// Preview tuning-report renderer used by the CLI.
393    pub mod tuning_report {
394        pub use crate::tune_report::{EXIT_OK, EXIT_USAGE, run};
395    }
396}
397
398#[cfg(feature = "backend-authoring")]
399/// Contracts and extension traits for backend authors.
400pub mod backend_authoring {
401    pub use incin_core::backend_authoring::{
402        Alignment, AttributeContract, AutogradBackend, Backend, Capabilities, CapabilityQuery,
403        CapabilityRegistry, DescriptorError, Execute, ExecuteOutput, ExecutionContext,
404        ExecutionDescriptor, ExecutionRequest, HostInterop, HostReadback, LogicalTensorMeta,
405        LossScaling, Operation, OperationIdentity, OperationKey, PrecisionSpec,
406        RuntimePrecisionPolicy, ShapeBuf, StorageBackend, StorageOutput, StorageTransfer,
407        SupportLevel, SupportsDType, TensorBackend, TensorMeta, TransferBackend, TransferTo,
408        UnsupportedReason, Validated, VariableBackend, VariableTransfer,
409    };
410    pub use incin_core::backend_authoring::{
411        execute, execute_shaped, execute_shaped_with_payload, execute_with_payload,
412    };
413
414    /// Canonical exact operation descriptors and typed attributes.
415    pub mod operations {
416        pub use incin_core::backend_authoring::operations::{
417            AdamAttributes, AdamWAttributes, AdaptivePool2dAttributes, AddmmAttributes,
418            ArangeAttributes, ArgsortAttributes, AttentionAttributes, AvgPool2dAttributes,
419            AxisAttributes, AxisVarianceAttributes, BatchNormAttributes, CanonicalOperation,
420            ChunkAttributes, ClampAttributes, Conv1dAttributes, Conv2dAttributes,
421            ConvTranspose2dAttributes, CreationAttributes, DTypeAttributes, Descriptor,
422            DescriptorError, DeviceAttributes, DiagonalAttributes, DistributionAttributes,
423            DropoutAttributes, DuplicateIndexRule, EpsilonAttributes, FlattenAttributes,
424            FullAttributes, GroupNormAttributes, IndexReductionAttributes, LayerNormAttributes,
425            LerpAttributes, LinearAttributes, LinspaceAttributes, LogicalTensorMeta,
426            LossAttributes, LossReduction, NarrowAttributes, NoAttributes, NormAttributes,
427            OPERATION_CATALOG, Operation, OperationCatalogEntry, OperationKey, PadAttributes,
428            PixelShuffleAttributes, Pool2dAttributes, QuantizationAttributes, RecurrentAttributes,
429            RepeatAttributes, ScalarAttributes, ScatterAttributes, SgdAttributes, ShapeAttributes,
430            SliceAttributes, SplitAttributes, TopKAttributes, TransposeAttributes,
431            UnfoldAttributes, ValidatedInvocation, VarianceAttributes, catalog_entry, op,
432        };
433        // Mirrors the core tier exactly: the classification enums every field
434        // of the re-exported `OperationCatalogEntry` is typed as.
435        pub use incin_core::backend_authoring::operations::{
436            BroadcastingRule, DTypeRule, EmptyRule, ExecutionSite, GradientRule, LayoutRule,
437            NumericRule, OutputRule, SemanticProfile,
438        };
439        #[cfg(feature = "std")]
440        pub use incin_core::backend_authoring::operations::{
441            CapturedDescriptor, DescriptorCaptureError,
442        };
443    }
444}
445
446#[cfg(feature = "test-utils")]
447/// Deterministic fault injection for tests that need a backend operation to
448/// fail on demand. There is no stand-in backend here: a test that needs a
449/// backend uses a real one.
450pub mod test_utils {
451    #[cfg(feature = "cpu")]
452    pub use incin_backends::test_utils::{AssignFailureGuard, fail_assign_on, fail_assignments_at};
453}
454
455/// Neural network modules, activation functions, layers, and building blocks.
456pub mod nn {
457    pub use incin_core::nn::loss::{
458        BCEWithLogitsShape, CrossEntropyReductionShape, CrossEntropyShape, L1ReductionShape,
459        L1Shape, MSEShape, Mean, NoneReduction, Reduction, ReductionMode, Sum,
460    };
461    pub use incin_core::nn::param;
462    pub use incin_core::nn::{
463        AdaptiveAvgPool2d, AvgPool2d, BCEWithLogitsLoss, BatchNorm2d, BatchNormShape, Buffer,
464        ComputeStats, Conv1d, Conv1dShape, Conv2d, Conv2dShape, CrossEntropyLoss, Dropout, ELU,
465        Embedding, EmbeddingShape, False, Flatten, GELU, Init, L1Loss, LSTM, LSTMCell, LayerNode,
466        LayerNorm, LayerNormShape, LayerStats, Linear, LinearShape, LstmShape, MSELoss, MaxPool2d,
467        Mish, ModelStats, Module, NamedLayers, OptionalField, Param, ParameterVisitor, RMSNorm,
468        RMSNormShape, RNN, RNNCell, ReLU, RnnShape, Sequential, Sigmoid, Softmax, Swish, Tanh,
469        TrainMode, TrainState, True, VisitParameters, batch_norm2d, conv1d, conv2d, embedding,
470        format_layer_summary, format_layer_summary_with_stats, layer_norm, linear, lstm, rms_norm,
471        rnn, sum_stats,
472    };
473    #[cfg(feature = "distributed")]
474    pub use incin_core::nn::{TwoWayColumnLinearShape, TwoWayRowLinearShape};
475    pub use incin_core::tensor::transfer::ToDevice;
476}
477
478/// Optimization algorithms, loss functions, and learning rate schedulers.
479pub mod optim {
480    pub use incin_core::optim::{
481        Adam, AdamW, ConstantLR, Gradients, LRScheduler, LinearLR, Optimizer, OptimizerBackend,
482        ParameterGroup, SGD, clip_grad_norm, clip_grad_value,
483    };
484    #[cfg(feature = "std")]
485    pub use incin_core::optim::{CosineAnnealingLR, StepLR};
486}
487
488/// Evaluation metrics (Accuracy, Precision, Recall, F1Score, MSE, ConfusionMatrix).
489pub mod metrics {
490    pub use incin_core::metrics::{
491        Accuracy, ConfusionMatrix, F1Score, MSE, Metric, Precision, Recall,
492    };
493}
494
495/// Dataset abstractions and data loading utilities.
496pub mod data {
497    pub use super::MnistTargetExt;
498    pub use incin_data::vision;
499    pub use incin_data::vision::mnist::MnistBatchTarget;
500    pub use incin_data::{
501        BatchResult, Collate, DataError, DataLoader, DataLoaderBuilder, Dataset, Downloader,
502    };
503}
504
505/// Data transformations and augmentation pipeline.
506pub mod transforms {
507    pub use incin_data::transforms::{
508        CenterCrop, Compose, Normalize, RandomHorizontalFlip, Scale, Transform,
509    };
510}
511
512/// HuggingFace Hub downloading & pretrained model loading utilities.
513#[cfg(feature = "data-hub")]
514pub mod hub {
515    pub use incin_data::hub::{HubApi, HubRepo, download, download_dataset, from_pretrained};
516}
517
518/// Typenum compile-time type-level integers.
519pub use incin_core::typenum;
520
521/// The `cargo incin doctor` report: devices, features, caches, and probes.
522///
523/// In the library rather than in `src/bin/cargo-incin.rs` because an
524/// integration test links the library and not the binary, and `UX-014`'s
525/// evidence command is `cargo test -p incin --test doctor`.
526#[cfg(feature = "std")]
527pub mod doctor;
528
529/// Model checkpoint artifacts and transactional state loading.
530pub mod state {
531    pub use incin_core::nn::state::{
532        StateMutVisitor, StatePath, StateRole, StateSnapshot, StateSnapshotVisitor, StateValue,
533        StateVisitor, VisitState, VisitStateMut, collect_state, load_state,
534    };
535}
536
537// Enabling an accelerator must never silently change application behavior.
538// CPU remains the default whenever it is available; accelerator-only builds
539// get the one enabled device family.
540#[cfg(feature = "cpu")]
541/// Default device used by the standard installation.
542pub type DefaultDevice = incin_core::tensor::device::Cpu;
543#[cfg(all(not(feature = "cpu"), feature = "wgpu"))]
544/// Default device for a WGPU-only build.
545pub type DefaultDevice = incin_core::tensor::device::Wgpu;
546#[cfg(all(not(feature = "cpu"), not(feature = "wgpu"), feature = "cuda"))]
547/// Default device for a CUDA-only build.
548pub type DefaultDevice = incin_core::tensor::device::Cuda;
549
550#[cfg(feature = "train")]
551mod plan_report;
552#[cfg(feature = "train")]
553mod train;
554#[cfg(feature = "std")]
555mod tune_report;
556
557#[cfg(feature = "cpu")]
558/// Default backend on the CPU, equivalent to `IncinBackend<Cpu>`.
559pub type DefaultBackend = incin_backends::IncinBackend<incin_core::tensor::device::Cpu>;
560
561// No `DefaultBackend` fallback when `cpu` is disabled: a `()` placeholder
562// (the previous approach) doesn't implement `Backend`, so every type alias
563// below that defaults its `B` param to it would compile-error deep inside
564// trait-bound resolution the moment anyone actually used it, far from the
565// real problem ("you disabled `cpu` and didn't pick another backend").
566// Instead, every alias below drops the `B = DefaultBackend` default entirely
567// in this configuration, same as `Tensor` already did - forcing an explicit,
568// immediate "expected 2 generic arguments" error at the actual call site.
569
570#[cfg(feature = "cpu")]
571/// Tensor.
572pub type Tensor<
573    S,
574    B = DefaultBackend,
575    K = f32,
576    G = incin_core::tensor::grad::NoGrad,
577    P = incin_core::dist::Local,
578> = incin_core::tensor::base::Tensor<S, B, K, G, P>;
579
580#[cfg(not(feature = "cpu"))]
581/// Tensor.
582pub type Tensor<
583    S,
584    B, // User must specify backend if Cpu is disabled
585    K = f32,
586    G = incin_core::tensor::grad::NoGrad,
587    P = incin_core::dist::Local,
588> = incin_core::tensor::base::Tensor<S, B, K, G, P>;
589
590// Neural Network Layer Aliases
591//
592// Each of these that takes a `B` (backend) param is declared twice, gated on
593// the `cpu` feature: with a `= DefaultBackend` default when `cpu` is on
594// (the common case), and with NO default when it's off - same reasoning as
595// `Tensor` above and `DefaultBackend` itself.
596#[cfg(feature = "cpu")]
597/// Linear.
598pub type Linear<S, B = DefaultBackend> = incin_core::nn::Linear<S, B>;
599#[cfg(not(feature = "cpu"))]
600/// Linear.
601pub type Linear<S, B> = incin_core::nn::Linear<S, B>;
602
603#[cfg(feature = "cpu")]
604/// Conv1d.
605pub type Conv1d<S, B = DefaultBackend> = incin_core::nn::Conv1d<S, B>;
606#[cfg(not(feature = "cpu"))]
607/// Conv1d.
608pub type Conv1d<S, B> = incin_core::nn::Conv1d<S, B>;
609
610#[cfg(feature = "cpu")]
611/// Conv2d.
612pub type Conv2d<S, B = DefaultBackend> = incin_core::nn::Conv2d<S, B>;
613#[cfg(not(feature = "cpu"))]
614/// Conv2d.
615pub type Conv2d<S, B> = incin_core::nn::Conv2d<S, B>;
616
617#[cfg(feature = "cpu")]
618/// Batch norm2d.
619pub type BatchNorm2d<C, B = DefaultBackend> = incin_core::nn::BatchNorm2d<C, B>;
620#[cfg(not(feature = "cpu"))]
621/// Batch norm2d.
622pub type BatchNorm2d<C, B> = incin_core::nn::BatchNorm2d<C, B>;
623
624#[cfg(feature = "cpu")]
625/// Layer norm.
626pub type LayerNorm<C, B = DefaultBackend> = incin_core::nn::LayerNorm<C, B>;
627#[cfg(not(feature = "cpu"))]
628/// Layer norm.
629pub type LayerNorm<C, B> = incin_core::nn::LayerNorm<C, B>;
630
631/// Avg pool2d.
632pub type AvgPool2d<K, S, P = typenum::U0, D = typenum::U1> = incin_core::nn::AvgPool2d<K, S, P, D>;
633/// Max pool2d.
634pub type MaxPool2d<K, S, P = typenum::U0, D = typenum::U1> = incin_core::nn::MaxPool2d<K, S, P, D>;
635/// Sequential.
636pub type Sequential<L1, L2> = incin_core::nn::Sequential<L1, L2>;
637
638#[cfg(feature = "cpu")]
639/// Param.
640pub type Param<T, B = DefaultBackend> = incin_core::nn::Param<T, B>;
641#[cfg(not(feature = "cpu"))]
642/// Param.
643pub type Param<T, B> = incin_core::nn::Param<T, B>;
644
645#[cfg(feature = "cpu")]
646/// Rnncell.
647pub type RNNCell<S, B = DefaultBackend> = incin_core::nn::RNNCell<S, B>;
648#[cfg(not(feature = "cpu"))]
649/// Rnncell.
650pub type RNNCell<S, B> = incin_core::nn::RNNCell<S, B>;
651
652#[cfg(feature = "cpu")]
653/// Rnn.
654pub type RNN<S, B = DefaultBackend> = incin_core::nn::RNN<S, B>;
655#[cfg(not(feature = "cpu"))]
656/// Rnn.
657pub type RNN<S, B> = incin_core::nn::RNN<S, B>;
658
659#[cfg(feature = "cpu")]
660/// Embedding.
661pub type Embedding<S, B = DefaultBackend> = incin_core::nn::Embedding<S, B>;
662#[cfg(not(feature = "cpu"))]
663/// Embedding.
664pub type Embedding<S, B> = incin_core::nn::Embedding<S, B>;
665
666/// Macros.
667pub mod macros {
668    // `impl_arg_into` deliberately excluded: it's an internal codegen helper
669    // invoked once, internally, by `incin-core` itself
670    // (`incin_macros::impl_arg_into!()` in `tensor/arg_into.rs`) - no
671    // end-user code calls it, and it has no documented public contract.
672    pub use incin_macros::{i, s, shape, tensor};
673
674    /// Advanced type-level slicing and reshape syntax.
675    pub mod advanced {
676        pub use incin_macros::idx;
677    }
678}
679
680/// Prelude re-exporting high-frequency user types, macros, NN modules, and optimizers.
681pub mod prelude {
682    pub use super::Tensor;
683    pub use incin_core::SeqTy;
684    pub use incin_core::error::{
685        BackendError, BackwardError, ConversionFailure, Error, ErrorMessage, FloatToIntPolicy,
686        NonFiniteSite, Result, convert_f64_to_i64,
687    };
688    pub use incin_core::nn::module::Module;
689    pub use incin_core::nn::state::{StatePath, StateRole, StateSnapshot, StateValue};
690    pub use incin_core::shapes::{
691        AxisIdentity, AxisSchema, ConstDim, Dim, Dyn, DynShape, InferShape, NamedDim, Ranked,
692        Shape, ShapeArgs, ShapeSpec, ShapeValue,
693    };
694    pub use incin_core::tensor::device::{
695        ConstDevice, Cpu, Device, DeviceId, DeviceKind, DevicePreference, DeviceSet, DeviceSetError,
696    };
697    pub use incin_core::tensor::dtype::{
698        BoolDType, BuiltinDType, ConstDType, DType, DTypeDescriptor, DTypeId, DTypeKey, DTypeKind,
699        FloatDType, IntDType, PlainDType, Q8_0, QuantDType, TensorElement, bf16, f16,
700    };
701    pub use incin_core::tensor::grad::{Grad, NoGrad, RequiresGrad};
702    pub use incin_core::tensor::matmul::MatMulShape;
703    pub use incin_core::tensor::transfer::ToDevice;
704
705    pub use incin_core::exec::AxisSet;
706    pub use incin_core::shapes::broadcast::BroadcastDim;
707    pub use incin_core::shapes::concat::ConcatShape;
708    pub use incin_core::shapes::stack::StackShape;
709    pub use incin_core::shapes::{
710        AppendDim, Axis, BroadcastExtent, BroadcastShape, ReshapeShape, SameCount, Scalar,
711        TryReshape,
712    };
713
714    #[cfg(feature = "cuda")]
715    pub use incin_core::tensor::device::{Cuda, CudaN};
716    #[cfg(feature = "metal")]
717    pub use incin_core::tensor::device::{Metal, MetalN};
718    #[cfg(feature = "wgpu")]
719    pub use incin_core::tensor::device::{Wgpu, WgpuN};
720
721    #[cfg(feature = "cpu")]
722    pub use super::DefaultBackend;
723    #[cfg(any(feature = "cpu", feature = "wgpu", feature = "cuda"))]
724    pub use super::DefaultDevice;
725    pub use incin_backends::IncinBackend;
726
727    // Device values are the preferred allocation targets.
728    // These are extension traits, so they only resolve when in scope - which
729    // is the whole reason they are in the prelude rather than left to a
730    // module path. See `docs/plan/UX-ARCHITECTURE-HANDOFF.md`.
731    pub use incin_backends::nn_target::InitOnTarget;
732    #[cfg(feature = "external-candle")]
733    pub use incin_backends::target::Candle;
734    pub use incin_backends::target::{
735        DtypeTarget, EngineSpec, GeneratedFill, Native, PrecisionSpec, Target, TargetExt,
736        TensorData, TensorTarget, precision,
737    };
738
739    pub use incin_core::dim;
740    pub use incin_core::seq;
741    pub use incin_core::typenum;
742
743    pub use incin_macros::{axis, i, idx, module, s, shape, tensor};
744
745    pub use super::{
746        BatchNorm2d, Buffer, Conv1d, Conv2d, Embedding, LayerNorm, Linear, Param, RNN, RNNCell,
747    };
748
749    pub use incin_core::nn::{
750        activation::{GELU, ReLU, Sigmoid, Softmax, Swish, Tanh},
751        avg_pool2d::AvgPool2d,
752        dropout::Dropout,
753        flatten::{Flatten, FlattenAxes, StructuralFlatten},
754        init::Init,
755        loss::{
756            BCEWithLogitsLoss, CrossEntropyLoss, L1Loss, MSELoss, Mean, NoneReduction, Reduction,
757        },
758        lstm::{LSTM, LSTMCell},
759        max_pool2d::MaxPool2d,
760        module::{Sequential, TrainMode},
761        rms_norm::RMSNorm,
762    };
763
764    #[cfg(feature = "std")]
765    pub use incin_core::serialization::{Format, ModelExt, STATE_FORMAT_VERSION};
766
767    pub use incin_core::exec::{LossScaleState, LossScaling};
768    pub use incin_core::optim::{
769        Adam, AdamW, ConstantLR, Gradients, LRScheduler, LinearLR, Optimizer, ParameterGroup, SGD,
770        ScaledOptimizer,
771    };
772    #[cfg(feature = "std")]
773    pub use incin_core::optim::{CosineAnnealingLR, StepLR};
774
775    pub use incin_core::metrics::{
776        Accuracy, ConfusionMatrix, F1Score, MSE, Metric, Precision, Recall,
777    };
778
779    #[cfg(feature = "distributed")]
780    pub use incin_core::dist::{Local, Placement, PlacementKind};
781}
782
783/// Structural shape proofs for advanced generic code.
784pub mod advanced {
785    pub use incin_core::shapes::idx::{
786        AxisCursor, AxisSelector, DimIdx, Ellipsis, ForwardAxis, FromEnd, Here, InferDim,
787        NamedAxisLookup, NamedAxisSelector, Next, ReshapeTarget, ReverseAxis, Slice, SliceIdx,
788        SliceTarget, StaticAxis, StaticCursor, ToAxisIndex,
789    };
790    pub use incin_core::shapes::{At, ReduceAt, ReduceKeepAt, RemoveAt, SwapAt};
791    pub use incin_core::typenum;
792}
793
794#[cfg(test)]
795/// Tests.
796mod tests {
797    use super::*;
798
799    #[test]
800    #[cfg(feature = "cpu")]
801    /// Runtime dtype creation keeps the dtype tag in a `Dyn` tensor.
802    fn test_runtime_dtype_tensor_creation() {
803        let t = Tensor::<Dyn, DefaultBackend, Dyn>::ones((std::vec![2, 2], DTypeId::F64)).unwrap();
804        assert_eq!(t.dtype(), DTypeId::F64.descriptor());
805    }
806
807    #[test]
808    #[cfg(feature = "cpu")]
809    /// Test tensor export.
810    fn test_tensor_export() {
811        let _t = Tensor::<Dyn, DefaultBackend>::zeros(std::vec![2, 2]).unwrap();
812    }
813}