Skip to main content

Crate incin

Crate incin 

Source
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 like matmul, 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.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.
  • 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!.
  • 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 doctor report: 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.
CosineAnnealingLR
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.
DTypeDescriptor
Combined logical and physical description of a dtype.
DTypeKey
A stable, extensible logical dtype key.
DeviceId
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 the Device trait’s runtime counterpart - every Device::to_incin resolves to one of these.
DeviceSet
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.
ErrorMessage
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 f16 scale, each element stored as a scaled i8.
SGD
Stochastic Gradient Descent (SGD) optimizer.
StatePath
Durable, hierarchical state name. This is a serialization path, not a parameter/runtime-variable identity or alias identifier.
StateSnapshot
An owned collection of heterogeneous model state.
StateValue
One owned, exact-dtype state value.
StepLR
Step learning rate decay.
TargetBatch
Incin’s target-backed adapter for model-ready MNIST batches.
bf16
A 16-bit floating point type implementing the bfloat16 format.
f16
A 16-bit floating point type implementing the IEEE 754-2008 standard binary16 a.k.a “half” format.

Enums§

BackendError
Structured failure returned by descriptor executors.
BackwardError
Structured failure raised while walking the autograd tape backward (GRD-005).
ConversionFailure
Why a checked scalar conversion was rejected.
DTypeId
A runtime-identifiable tag for the current built-in Incin dtypes.
DTypeKind
Broad semantic category of a dtype.
DeviceKind
The runtime-identifiable backend family a DeviceId belongs to.
DevicePreference
What a caller wants when they have not named specific devices.
DeviceSetError
Why a DeviceSet could not be built.
Error
Central error enum for the Incin framework.
FloatToIntPolicy
Explicit behavior requested for a floating-point to integer conversion.
NonFiniteSite
Where a non-finite gradient was found.
StateRole
Whether a state value is trainable or a persistent non-trainable buffer.

Traits§

BoolDType
Marker for the boolean dtype.
BuiltinDType
A ConstDType that additionally has a current built-in DTypeId.
ConstDType
A DType whose identity is fully known at compile time (as opposed to Dyn, 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).
FloatDType
Marker for floating-point dtypes (f32/f64/f16/bf16).
IntDType
Marker for integer dtypes (u8/u32/i64).
LRScheduler
Trait for learning rate schedulers.
MnistTargetExt
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.
OptimizerBackend
The canonical execution profile required by generic optimizers.
PlainDType
A ConstDType that additionally has a plain Rust POD scalar element.
QuantDType
Marker for block-quantized dtypes (e.g. Q8_0) - storage formats with their own internal scale/block structure, not plain scalar elements.
RequiresGrad
A type-level marker for whether a Tensor tracks gradients: Grad (always tracks), NoGrad (never tracks), or Dyn (decided at runtime).
Shape
The fundamental trait for all tensor shape types.
StateMutVisitor
Receives mutable typed state leaves while restoring a snapshot.
StateVisitor
Receives typed state leaves during module traversal.
TensorElement
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 logical DType implementations remain supported, but cannot provide a custom TensorElement.
TrainState
Trait defining parameter trainability typestate.
VisitState
Structural traversal of typed parameter and buffer leaves.
VisitStateMut
Structural mutable traversal used by snapshot restoration.

Functions§

convert_f64_to_i64
Converts value to i64 under an explicit policy.

Type Aliases§

AvgPool2d
Avg pool2d.
BatchNorm2d
Batch norm2d.
Conv1d
Conv1d.
Conv2d
Conv2d.
DefaultBackend
Default backend on the CPU, equivalent to IncinBackend<Cpu>.
DefaultDevice
Default device used by the standard installation.
Embedding
Embedding.
IncinBackend
Unified backend selected by device.
LayerNorm
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.