incin_macros/lib.rs
1//! # Incin Macros
2//!
3//! `incin-macros` provides procedural macros that form the ergonomic frontend for the Incin framework.
4//! Because Incin relies heavily on compile-time type verification using `typenum`, manipulating raw types can be extremely verbose (e.g., `Prod<UInt<UTerm, B1>, ...>`).
5//! These macros hide that complexity, allowing developers to write clean, intuitive syntax while the macros generate the underlying type boundaries.
6//!
7//! ## Provided Macros
8//!
9//! * **`s![...]`**: Defines a shape directly from integer literals (e.g., `s![1, 3, 224, 224]`).
10//! * **`i![...]`**: Defines runtime indexing/slicing arguments for tensors (e.g., `i![1..3, .., -1]`).
11//! * **`idx![...]`**: Defines an advanced type-level slicing target.
12//! * **`#[module]`**: Derives neural network module traits automatically for structs, similar to `#[derive(Module)]` but specifically tailored for Incin.
13//! * **`model!("model.onnx", Name)`**: Compiles an ONNX model file into a fully-typed Rust module structurally matching the ONNX graph.
14//! * **`import_model!("model.onnx", Name)`**: Compiles an ONNX model file into a fully-typed Rust module structurally matching the ONNX graph.
15#[macro_use]
16extern crate alloc;
17
18use proc_macro::TokenStream;
19
20/// Internal helper module for generating ArgInto implementations.
21mod arg_into;
22mod axis;
23
24/// Internal helper module for tensor index and slicing macro.
25mod idx;
26mod index_expr;
27/// Helper module for logical device mesh topology macro.
28#[cfg(feature = "distributed")]
29mod mesh;
30/// Helper module for deriving neural network module traits.
31mod module;
32/// Internal helper module for tensor placement macro.
33#[cfg(feature = "distributed")]
34mod placement;
35
36/// Internal helper module for distributed main macro.
37#[cfg(feature = "distributed")]
38mod distributed_main;
39/// Internal helper module for parallel block macro.
40#[cfg(feature = "distributed")]
41mod parallel_block;
42
43/// Helper module for parsing ONNX model graphs into Rust structs.
44mod onnx;
45/// The ONNX protobuf message types `onnx` parses into.
46///
47/// A checked-in `prost-build` output rather than the `onnx-pb` crate. `onnx-pb`
48/// has not been released since 2020, pinned this crate to `prost 0.6` beside
49/// `incin-core`'s `prost 0.14`, and ran `protoc` from a build script - which
50/// made a protobuf compiler a build requirement for everyone who depended on
51/// the facade. The file is byte-identical to `incin-core`'s copy and both are
52/// written by `cargo xtask onnx`, whose `--check` mode is the CI gate.
53#[allow(
54 dead_code,
55 clippy::doc_overindented_list_items,
56 clippy::enum_variant_names
57)]
58mod onnx_pb {
59 include!("generated/onnx.rs");
60}
61/// Helper module for importing model weights from safetensors.
62mod safetensors;
63/// Helper module for static shape macro expansion.
64mod shape;
65mod shape_value;
66/// Helper module for the tensor literal construction macro.
67mod tensor;
68
69/// A macro to construct static Tensor shapes ergonomically in the type system.
70///
71/// Instead of writing raw type bounds (e.g., `(typenum::U128, typenum::U256)`), this macro generates
72/// the underlying binary type trees directly from integer literals. This dramatically improves
73/// readability and reduces boilerplate when defining static tensor bounds.
74///
75/// Under the hood, `s![1, 3, 224, 224]` is expanded by the compiler into:
76/// `(typenum::U1, typenum::U3, typenum::U224, typenum::U224)`
77///
78/// ## Examples
79/// ```rust
80/// use incin::prelude::*;
81///
82/// // Defines a 4D tensor shape [Batch=2, Channels=3, Height=224, Width=224]
83/// type ImageBatch = s![2, 3, 224, 224];
84/// let t = Tensor::<ImageBatch>::zeros(()).unwrap();
85/// assert_eq!(t.dims().as_ref(), &[2, 3, 224, 224]);
86/// ```
87///
88/// You can also mix named symbolic dimensions (if they implement `Dim`):
89/// ```rust
90/// use incin::prelude::*;
91/// dim!(BatchSize);
92///
93/// type BatchedFeatures = s![BatchSize, 128];
94/// ```
95///
96/// A semantic tag and extent can also be written together. The extent stays
97/// independent from the tag, so named static axes use the same raw typenum
98/// representation as anonymous static axes:
99/// ```rust
100/// # use incin::prelude::*;
101/// # dim!(Batch, Features);
102/// type FeaturesBatch = s![Batch = 25, Features = 128];
103/// ```
104///
105/// ## Path resolution
106///
107/// The expansion names `::incin::prelude::…` absolutely, so it resolves
108/// against the crate rather than against whatever the caller happens to have
109/// in scope - including a module of their own called `incin` (`CI-005`).
110///
111/// The one form it cannot survive is a *package* rename in the caller's
112/// `Cargo.toml` (`incin_x = { package = "incin" }`), because `::incin` then
113/// names a crate that is not there. Resolving the real name requires reading
114/// the caller's manifest at expansion time, which the macro policy in
115/// `PROPOSALS.md` forbids.
116#[proc_macro]
117pub fn s(input: TokenStream) -> TokenStream {
118 shape::shape(input)
119}
120
121/// Builds a `Tensor` directly from a literal, inferring shape and (unless
122/// told otherwise) dtype from how it's written - the macro analogue of
123/// `vec![...]`.
124///
125/// `tensor![data...; dtype: T, grad: G]` - the `; clause, ...` tail is
126/// optional and either clause may appear in either order.
127///
128/// **Scope.** This macro is the convenience form for literal data on the
129/// default CPU backend, and nothing else. It has no `backend:` or `device:`
130/// clause: allocating somewhere specific is the allocation target's job, and
131/// ordinary Rust arrays carry shape and dtype just as well as a literal
132/// does, so the target form is usually the better one anyway:
133///
134/// ```text
135/// let x = Cpu.tensor([[1.0_f32, 2.0], [3.0, 4.0]])?; // same tensor
136/// let y = Wgpu::new(0).tensor([[1.0_f32, 2.0]])?; // and this one places it
137/// ```
138///
139/// See the target-first allocation API. An earlier revision
140/// of this macro did take a `device:` clause and inferred the backend from
141/// the *token spelling* of the expression, which could not see through
142/// `let d = Wgpu::new(0);`. That heuristic is gone rather than patched.
143///
144/// The shape comes from nesting depth, exactly like a Rust array literal:
145///
146/// ```rust
147/// use incin::prelude::*;
148///
149/// let v = tensor![1.0, 2.0, 3.0].unwrap(); // shape [3], f32
150/// let m = tensor![[1.0, 2.0], [3.0, 4.0]].unwrap(); // shape [2, 2], f32
151/// let t = tensor![[[1, 2], [3, 4]], [[5, 6], [7, 8]]] // shape [2, 2, 2], i64
152/// .unwrap();
153///
154/// let empty = tensor![].unwrap(); // shape [0], f32 - like vec![]
155/// ```
156///
157/// A ragged literal (a row whose length disagrees with its siblings, or a
158/// row mixing nested arrays with plain values) is a macro-expansion error
159/// naming the offending dimension, not a best-effort reshape.
160///
161/// ## Dtype inference
162///
163/// `dtype` is picked in this order:
164/// 1. An explicit `; dtype: T` clause.
165/// 2. A numeric-literal suffix (`2.0f64`, `2u8`), if every leaf that has one
166/// agrees.
167/// 3. `i64` if every leaf is a bare integer literal (`tensor![1, 2, 3]`,
168/// matching PyTorch's own `torch.tensor([1, 2, 3])`); otherwise `f32`.
169///
170/// Rule 3 is a default, not a proof: a leaf that is not a literal at all
171/// (a variable, a call, ...) has no dtype the macro can see at expansion
172/// time, so it is passed through unchanged rather than cast. If it turns out
173/// not to already be the resolved dtype, that surfaces as `rustc`'s own type
174/// mismatch at the `from_slice` call this macro expands to - not a silently
175/// narrowed value.
176///
177/// ## Clauses
178///
179/// An optional `; clause, clause, ...` tail after the data overrides a
180/// default:
181///
182/// ```rust
183/// use incin::prelude::*;
184///
185/// let precise = tensor![1.0, 2.0; dtype: f64].unwrap();
186/// ```
187///
188/// Clauses are matched by name, not position, so they can be written in any
189/// order - `; grad: NoGrad, dtype: f64` and `; dtype: f64, grad: NoGrad` are
190/// the same.
191///
192/// - `dtype: T` - the element type, overriding inference above.
193/// - `grad: G` - `Grad` or `NoGrad`, overriding the default `Grad` (matching
194/// `Tensor`'s own default). Only those two markers are accepted, since
195/// both take no runtime argument; `Dyn` (gradient tracking toggled at
196/// runtime) needs a value alongside the type, and `tensor!` has no
197/// value-carrying clause - construct
198/// directly with `Tensor::<S, B, K, Dyn>::from_slice(&data, (.., flag))`
199/// instead:
200///
201/// ```rust
202/// use incin::prelude::*;
203///
204/// let t = tensor![1.0, 2.0; grad: NoGrad].unwrap();
205/// assert!(!t.requires_grad());
206/// ```
207///
208/// ## Return type
209///
210/// Like every other fallible constructor on `Tensor` (`zeros`, `ones`,
211/// `from_slice`, ...), `tensor!` expands to a `Result<Tensor<...>>`
212/// expression rather than panicking - use `?` or `.unwrap()` at the call
213/// site.
214///
215/// ## Path resolution
216///
217/// The expansion names `::incin::prelude::…` absolutely, so it resolves
218/// against the crate rather than against whatever the caller happens to have
219/// in scope - including a module of their own called `incin` (`CI-005`).
220///
221/// The one form it cannot survive is a *package* rename in the caller's
222/// `Cargo.toml` (`incin_x = { package = "incin" }`), because `::incin` then
223/// names a crate that is not there. Resolving the real name requires reading
224/// the caller's manifest at expansion time, which the macro policy in
225/// `PROPOSALS.md` forbids.
226/// Builds a shape *value* for an allocation target, inferring which axes are
227/// static from how they are written.
228///
229/// The value-level counterpart of [`s!`](crate::s). `s!` names a shape
230/// *type*; `shape!` produces the argument a target's constructors take, and
231/// the shape type comes out of it:
232///
233/// ```text
234/// let w = gpu.zeros(shape![128, 784])?; // Tensor<s![128, 784], ..>
235/// let x = gpu.zeros(shape![batch, 784])?; // Tensor<s![usize, 784], ..>
236/// let y = gpu.zeros(shape![rows, cols])?; // Tensor<s![usize, usize], ..>
237/// ```
238///
239/// # Which axes are static
240///
241/// An integer literal is a static axis; anything else is a runtime axis. This
242/// is the same split `s!` already makes - `s![usize, 784]` - with the `usize`
243/// inferred rather than spelled.
244///
245/// The inference is *syntactic*, so a named constant reads as an expression
246/// and produces a runtime axis:
247///
248/// ```text
249/// const N: usize = 32;
250/// shape![N, 784] // s![usize, 784], not s![32, 784]
251/// ```
252///
253/// That is a weaker shape than was available, never a wrong one: the extent is
254/// still 32, it is simply carried at runtime instead of in the type. Where the
255/// stronger form matters, name it - `s![32, 784]` - which is
256/// what the explicit constructors remain for.
257///
258/// # What it does not carry
259///
260/// Only geometry. **Dtype comes from elsewhere**: generated tensors take the
261/// target's bound float (`gpu.zeros(..)` is `f32` unless the target was rebound
262/// with `dtype`), and data tensors take the element type of the data
263/// (`gpu.tensor([0_i64, 1])` is `i64`). Nothing in this macro can change
264/// either, which is deliberate - a shape argument that silently decided dtype
265/// would be the same mistake as a device argument that silently decided a
266/// backend.
267///
268/// Gradient tracking is likewise not here: it follows the object being built,
269/// so target constructors give `NoGrad` and parameters give `Grad`.
270///
271/// # Grammar
272///
273/// A comma-separated axis list, and nothing else. `s!`'s repeat, `Head` and
274/// `Tail` forms are not supported; write those with `s!` and the explicit
275/// constructors.
276///
277/// ```text
278/// shape![] // rank 0
279/// shape![8] // rank 1, static
280/// shape![batch] // rank 1, runtime
281/// shape![2, 3, 4] // rank 3, all static
282/// ```
283///
284/// A negative or fractional dimension is a compile error rather than a
285/// confusing `usize` type mismatch further along.
286///
287/// # Availability
288///
289/// Expands to a `ShapeValue` that implements the target-first `ShapeSpec`
290/// contract. It is available in the normal standard-library build.
291///
292/// ## Path resolution
293///
294/// The expansion names `::incin::prelude::…` absolutely, so it resolves
295/// against the crate rather than against whatever the caller happens to have
296/// in scope - including a module of their own called `incin` (`CI-005`).
297#[proc_macro]
298pub fn shape(input: TokenStream) -> TokenStream {
299 shape_value::shape_value(input)
300}
301
302#[proc_macro]
303/// Procedural macro `tensor!` building a typed tensor literal with static shape checking.
304pub fn tensor(input: TokenStream) -> TokenStream {
305 tensor::tensor(input)
306}
307
308#[proc_macro]
309#[doc(hidden)]
310pub fn impl_layer_args(input: TokenStream) -> TokenStream {
311 arg_into::impl_layer_args(input)
312}
313
314/// A macro to construct index and slicing arguments for tensor reshaping and subsetting.
315///
316/// This macro generates the highly complex underlying type trees needed for operations like
317/// partial slicing, full slicing (`..`), inferred dimensions (`-1`), and exact indices.
318///
319/// Unlike standard array slicing, tensors often require slicing across multiple dimensions
320/// simultaneously, or broadcasting axes. `idx!` abstracts the creation of the heterogeneous tuple
321/// (e.g., `(Slice<U0, U5>, Ellipsis, Slice<U15, U30>)`) that the `.slice()` trait expects.
322///
323/// ## Syntax Supported
324/// * `0..5` -> Translates to a statically bounded slice `Slice<U0, U5>`.
325/// * `..` -> Translates to `SliceIdx::Full` (take the whole dimension).
326/// * `...` or `..` (when alone) -> Translates to `Ellipsis` (fills missing dimensions).
327/// * `-1` -> Translates to `InferDim` (used mainly in reshaping to infer the dimension size).
328///
329/// ## Examples
330/// ```rust
331/// use incin::prelude::*;
332///
333/// // Given a tensor `t` of shape [10, 20, 30]
334/// // Slice the first dimension 0..5, take all of the second, and 15..30 of the third.
335/// let t = Tensor::<s![10, 20, 30]>::zeros(()).unwrap();
336/// let view = t.slice_idx::<idx![0..5, .., 15..30]>().unwrap();
337/// assert_eq!(view.dims().as_ref(), &[5, 20, 15]);
338/// ```
339///
340/// ## Path resolution
341///
342/// The expansion names `::incin::prelude::…` absolutely, so it resolves
343/// against the crate rather than against whatever the caller happens to have
344/// in scope - including a module of their own called `incin` (`CI-005`).
345///
346/// The one form it cannot survive is a *package* rename in the caller's
347/// `Cargo.toml` (`incin_x = { package = "incin" }`), because `::incin` then
348/// names a crate that is not there. Resolving the real name requires reading
349/// the caller's manifest at expansion time, which the macro policy in
350/// `PROPOSALS.md` forbids.
351#[proc_macro]
352pub fn idx(input: TokenStream) -> TokenStream {
353 idx::idx(input)
354}
355
356/// Build runtime indexing and slicing expressions for `Tensor::get`.
357///
358/// Negative indices count from the end. This macro is deliberately separate
359/// from `shape!`, whose `infer` token describes reshape geometry.
360#[proc_macro]
361pub fn i(input: TokenStream) -> TokenStream {
362 index_expr::index_expr(input)
363}
364
365/// Build an arbitrary static or runtime axis selector.
366#[proc_macro]
367pub fn axis(input: TokenStream) -> TokenStream {
368 axis::axis(input)
369}
370
371/// A macro to construct typed logical device mesh specifications ergonomically.
372///
373/// ## Examples
374/// ```text
375/// type MyMesh = mesh![dp = 2, tp = 4, pp = 1];
376/// ```
377#[cfg(feature = "distributed")]
378#[proc_macro]
379pub fn mesh(input: TokenStream) -> TokenStream {
380 mesh::mesh(input)
381}
382
383/// The `#[module]` attribute automatically derives composable module capabilities
384/// for custom neural network structs.
385///
386/// When creating custom network architectures (like a Residual Block or an entire ResNet),
387/// you need a way to collect all trainable weights (for the optimizer) and state buffers
388/// (for saving/loading checkpoints).
389///
390/// This macro iterates through every field in your `struct`. If a field implements typed
391/// parameter or state visitors (like `Linear`, `Conv2d`, or nested `Sequential` blocks), it recursively
392/// aggregates them. It ignores fields that don't store tensor state.
393///
394/// Generated capabilities can be disabled explicitly for forward-only or specialized modules:
395/// `no_stats`, `no_parameters`, `no_state`, `no_named_layers`, `no_shape_info`,
396/// `no_train_mode`, and `no_to_device`. Unknown arguments are rejected.
397///
398/// ## Examples
399/// ```rust
400/// use incin::backend_authoring::VariableBackend;
401/// use incin::prelude::*;
402///
403/// #[module]
404/// pub struct MyModel<B: VariableBackend> {
405/// fc1: Linear<s![128, 64], B>,
406/// fc2: Linear<s![64, 10], B>,
407/// }
408///
409/// // Now `MyModel` automatically supports typed parameter and state visitors!
410/// ```
411///
412/// ## Path resolution
413///
414/// The expansion names `::incin::prelude::…` absolutely, so it resolves
415/// against the crate rather than against whatever the caller happens to have
416/// in scope - including a module of their own called `incin` (`CI-005`).
417///
418/// The one form it cannot survive is a *package* rename in the caller's
419/// `Cargo.toml` (`incin_x = { package = "incin" }`), because `::incin` then
420/// names a crate that is not there. Resolving the real name requires reading
421/// the caller's manifest at expansion time, which the macro policy in
422/// `PROPOSALS.md` forbids.
423#[proc_macro_attribute]
424pub fn module(attr: TokenStream, item: TokenStream) -> TokenStream {
425 module::module(attr, item)
426}
427
428/// Expands a supported `.onnx` graph or imports `.safetensors` metadata.
429///
430/// ONNX support is intentionally partial and fail-closed. Initializers, unknown
431/// rank, control flow, custom domains, attributes, and unsupported nodes produce
432/// macro-expansion diagnostics instead of fabricated code or values.
433///
434/// ## Examples
435///
436/// The path is read at compile time, so this is shown rather than compiled -
437/// there is no feature set in which a doctest has `resnet18.onnx` to open.
438///
439/// ```text
440/// use incin::prelude::*;
441///
442/// model!("stateless_supported_graph.onnx", MyModel);
443/// ```
444#[proc_macro]
445pub fn model(input: TokenStream) -> TokenStream {
446 safetensors::import_model(TokenStream::new(), input)
447}
448
449#[proc_macro]
450/// Attribute-style entry: `#[distributed_main]` selects and wraps a process-rank main.
451pub fn import_model(input: TokenStream) -> TokenStream {
452 safetensors::import_model(TokenStream::new(), input)
453}
454
455/// Constructs a compile-time tensor placement.
456///
457/// Supports `Local`, `Replicated on Mesh`, `Sharded(axis) on Mesh`, `Partial(Op) on Mesh`,
458/// and `PipelineStage(index) on Mesh`.
459///
460/// ## Examples
461/// ```text
462/// type P1 = placement![Local];
463/// type P2 = placement![Replicated on MyMesh];
464/// type P3 = placement![Sharded(0) on MyMesh];
465/// type P4 = placement![Partial(Sum) on MyMesh];
466/// type P5 = placement![PipelineStage(0) on MyMesh];
467/// ```
468#[cfg(feature = "distributed")]
469#[proc_macro]
470pub fn placement(input: TokenStream) -> TokenStream {
471 placement::placement(input)
472}
473
474/// Evaluates a computation block in a parallel mesh context.
475///
476/// Accepts `parallel!(mesh => { ... })` or `parallel!({ ... })`.
477///
478/// ## Examples
479/// ```text
480/// let val = parallel!(mesh => { 42 });
481/// assert_eq!(val, 42);
482/// ```
483#[cfg(feature = "distributed")]
484#[proc_macro]
485pub fn parallel(input: TokenStream) -> TokenStream {
486 parallel_block::parallel_block(input)
487}
488
489/// Attributes a main function to initialize and run distributed launcher boilerplate.
490#[cfg(feature = "distributed")]
491#[proc_macro_attribute]
492pub fn distributed_main(attr: TokenStream, item: TokenStream) -> TokenStream {
493 distributed_main::distributed_main(attr, item)
494}