Expand description
§Incin
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.
§Key Features
- 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 likematmul,conv2d,concat, etc. - 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.mdis generated from the backend registrations and answers this per operation. The third-party Candle adapter is available through theexternal-candlefeature underexternal::candle. - Macro-driven Ergonomics: Stable macros such as
s![],shape![],axis![], andi![]define shapes, selectors, and indexing. Partial ONNX expansion is available separately asexperimental::model!. - 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.
§Quick Start
Tensors are allocated by starting from a target device such as Cpu:
use incin::prelude::*;
// Statically shaped, zero-filled: (Batch=2, Channels=3, Height=224, Width=224)
let x = Cpu.zeros(shape![2, 3, 224, 224]).unwrap();TargetExt documents the rest of the creation API
(randn, rand, ones, full, arange, linspace, tensor, dynamic
runtime shapes) with a runnable example on every method.
§Neural Network Modules
Building and running a model is straightforward using the #[module] attribute and the
seq!/SeqTy! macros - SeqTy! names the same nested Sequential<...>
type that seq! builds a value of, so a layer list only needs to be written once per meaning
instead of the field type being hand-nested separately:
use incin::prelude::*;
type Backend = IncinBackend<Cpu>;
#[module(no_shape_info)]
pub struct MLP {
net: SeqTy!(
Linear<s![768, 256], Backend>,
ReLU,
Linear<s![256, 10], Backend>
),
}
impl MLP {
pub fn new() -> Result<Self> {
Ok(Self {
net: seq!(
Linear::<s![768, 256], Backend>::build(())?,
ReLU,
Linear::<s![256, 10], Backend>::build(())?
)
})
}
pub fn forward(&self, x: Tensor<s![2, 768], Backend>) -> Result<Tensor<s![2, 10], Backend, f32, Grad>>
{
self.net.forward(x)
}
}§ONNX Import
ONNX expansion is currently partial and fail-closed. Stateless graphs using the documented supported subset can produce typed eager code. Models with initializers, unknown rank, control flow, custom domains, or unsupported nodes are rejected during macro expansion; no weights or metadata are invented.
Re-exports§
pub use incin_core::typenum;
Modules§
- advanced
- Structural shape proofs for advanced generic code.
- backend_
authoring - Contracts and extension traits for backend authors.
- data
- Dataset abstractions and data loading utilities.
- doctor
- The
cargo incin doctorreport: devices, features, caches, and probes. - experimental
- Unstable APIs that carry no compatibility guarantee.
- hub
- HuggingFace Hub downloading & pretrained model loading utilities.
- macros
- Macros.
- metrics
- Evaluation metrics (Accuracy, Precision, Recall, F1Score, MSE, ConfusionMatrix).
- nn
- Neural network modules, activation functions, layers, and building blocks.
- optim
- Optimization algorithms, loss functions, and learning rate schedulers.
- prelude
- Prelude re-exporting high-frequency user types, macros, NN modules, and optimizers.
- state
- Model checkpoint artifacts and transactional state loading.
- test_
utils - Deterministic fault injection for tests that need a backend operation to fail on demand. There is no stand-in backend here: a test that needs a backend uses a real one.
- transforms
- Data transformations and augmentation pipeline.
- types
- Expert type-level and physical-layout contracts that are not part of the ordinary user prelude.
Macros§
- dim
- Generates zero-sized semantic tags for named tensor dimensions.
Runtime extents remain in
ShapeBuf, while the generated tags provide stable schema identity for compile-time metadata and lookup.
Structs§
- Adam
- Adam optimization algorithm.
- AdamW
- AdamW optimizer (Adam with decoupled weight decay).
- Buffer
- A non-trainable state buffer.
- ConstantLR
- Constant learning rate scheduler.
- Cosine
AnnealingLR - Cosine annealing learning rate scheduler.
- Cpu
- The CPU device. A zero-sized type - there is only one CPU, so no ordinal is needed. This is a Tier 3 (fully static) device selector.
- DType
Descriptor - Combined logical and physical description of a dtype.
- DType
Key - A stable, extensible logical dtype key.
- Device
Id - A runtime device identifier: a backend family (
DeviceKind) plus an ordinal distinguishing multiple devices of the same family (e.g. GPU 0 vs. GPU 1). This is theDevicetrait’s runtime counterpart - everyDevice::to_incinresolves to one of these. - Device
Set - An ordered, non-empty set of devices a run is asked to use.
- Dyn
- A marker for a runtime-selected shape, dtype, device, or placement.
- Error
Message - Bounded diagnostic text used by typed failures.
- Grad
- Marker: this tensor always tracks gradients.
- Gradients
- Encapsulates the backend-specific gradients obtained from a backward pass.
- LinearLR
- Linear learning rate decay.
- NoGrad
- Marker: this tensor never tracks gradients.
- Q8_0
- Q8_0 block quantization: groups of 32 elements share one
f16scale, each element stored as a scaledi8. - SGD
- Stochastic Gradient Descent (SGD) optimizer.
- State
Path - Durable, hierarchical state name. This is a serialization path, not a parameter/runtime-variable identity or alias identifier.
- State
Snapshot - An owned collection of heterogeneous model state.
- State
Value - One owned, exact-dtype state value.
- StepLR
- Step learning rate decay.
- Target
Batch - Incin’s target-backed adapter for model-ready MNIST batches.
- bf16
- A 16-bit floating point type implementing the
bfloat16format. - f16
- A 16-bit floating point type implementing the IEEE 754-2008 standard
binary16a.k.a “half” format.
Enums§
- Backend
Error - Structured failure returned by descriptor executors.
- Backward
Error - Structured failure raised while walking the autograd tape backward
(
GRD-005). - Conversion
Failure - Why a checked scalar conversion was rejected.
- DTypeId
- A runtime-identifiable tag for the current built-in Incin dtypes.
- DType
Kind - Broad semantic category of a dtype.
- Device
Kind - The runtime-identifiable backend family a
DeviceIdbelongs to. - Device
Preference - What a caller wants when they have not named specific devices.
- Device
SetError - Why a
DeviceSetcould not be built. - Error
- Central error enum for the Incin framework.
- Float
ToInt Policy - Explicit behavior requested for a floating-point to integer conversion.
- NonFinite
Site - Where a non-finite gradient was found.
- State
Role - Whether a state value is trainable or a persistent non-trainable buffer.
Traits§
- BoolD
Type - Marker for the boolean dtype.
- BuiltinD
Type - A
ConstDTypethat additionally has a current built-inDTypeId. - ConstD
Type - A
DTypewhose identity is fully known at compile time (as opposed toDyn, which is resolved at runtime). - DType
- A type-level tensor dtype: a logical description of what kind of values a tensor holds.
- Device
- A type-level compute device.
- DynShape
- A shape with runtime-accessible dimension information (rank, total elements, per-axis sizes).
- FloatD
Type - Marker for floating-point dtypes (
f32/f64/f16/bf16). - IntD
Type - Marker for integer dtypes (
u8/u32/i64). - LRScheduler
- Trait for learning rate schedulers.
- Mnist
Target Ext - Target-value MNIST loader extension for the facade crate.
- Module
- A generic Neural Network Layer or Module. Capable of taking an input and returning an output or error.
- Optimizer
- Trait defining a generic optimization algorithm.
- Optimizer
Backend - The canonical execution profile required by generic optimizers.
- PlainD
Type - A
ConstDTypethat additionally has a plain Rust POD scalar element. - QuantD
Type - Marker for block-quantized dtypes (e.g.
Q8_0) - storage formats with their own internal scale/block structure, not plain scalar elements. - Requires
Grad - A type-level marker for whether a
Tensortracks gradients:Grad(always tracks),NoGrad(never tracks), orDyn(decided at runtime). - Shape
- The fundamental trait for all tensor shape types.
- State
MutVisitor - Receives mutable typed state leaves while restoring a snapshot.
- State
Visitor - Receives typed state leaves during module traversal.
- Tensor
Element - Marker trait enforcing that a tensor element type is POD, Zeroable, safe,
and sealed (
SEC-005). The set of implementors is limited to Incin’s built-in scalar element types; custom logicalDTypeimplementations remain supported, but cannot provide a customTensorElement. - Train
State - Trait defining parameter trainability typestate.
- Visit
State - Structural traversal of typed parameter and buffer leaves.
- Visit
State Mut - Structural mutable traversal used by snapshot restoration.
Functions§
- convert_
f64_ to_ i64 - Converts
valuetoi64under an explicit policy.
Type Aliases§
- AvgPool2d
- Avg pool2d.
- Batch
Norm2d - Batch norm2d.
- Conv1d
- Conv1d.
- Conv2d
- Conv2d.
- Default
Backend - Default backend on the CPU, equivalent to
IncinBackend<Cpu>. - Default
Device - Default device used by the standard installation.
- Embedding
- Embedding.
- Incin
Backend - Unified backend selected by device.
- Layer
Norm - Layer norm.
- Linear
- Linear.
- MaxPool2d
- Max pool2d.
- Param
- Param.
- RNN
- Rnn.
- RNNCell
- Rnncell.
- Result
- Convenience type alias for
Result<T, Error>. - Sequential
- Sequential.
- Tensor
- Tensor.
Attribute Macros§
- module
- The
#[module]attribute automatically derives composable module capabilities for custom neural network structs.