incin-core 0.1.0

Core tensor operations and static shape checking for incin
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
//! Structured shape-resolution errors.
//!
//! Every shape rule that cannot be discharged by trait resolution reports its
//! failure through [`ShapeError`]. The design goal, from `PROPOSALS.md` ยง1.2.3,
//! is that a failure names four things without the caller having to reconstruct
//! them: *which operation* was being resolved, *where* in the shape it failed,
//! *what rule* was violated, and *what the operands actually were*.
//!
//! Statically invalid operations remain compile errors; this type describes the
//! mixed and dynamic cases, which return `Result` rather than panicking or
//! fabricating a scalar or empty shape.
//!
//! Every variant is `Copy` and allocation-free - `&'static str` and `usize`
//! only - so a shape rule can report a precise diagnostic from `no_std` code
//! and from a context that must not allocate.

use core::fmt;

/// The operation whose shape or dtype rule was being resolved.
///
/// This is the single operation vocabulary for the crate. It spans two levels
/// of granularity on purpose:
///
/// * coarse *families* ([`Storage`](Self::Storage) through
///   [`Normalization`](Self::Normalization)), retained only for policy
///   classification and legacy geometry diagnostics;
/// * exact catalog identities, which are the only identities allowed to prove
///   execution support.
///
/// Keeping both levels in one enum prevents parallel vocabularies, while
/// [`is_exact`](Self::is_exact) prevents a family from being mistaken for a
/// capability declaration.
macro_rules! define_operation_kind {
    ($(($variant:ident, $name:literal, $family:ident, $profile:ident, $attrs:ident, $min:expr, $max:expr, $legacy:literal),)*) => {
        /// Exact identities generated from the canonical operation catalog.
        #[non_exhaustive]
        #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize)]
        pub enum OperationKind {
            /// Allocating or copying storage, independent of any compute.
            Storage,
            /// Filling a tensor with a constant.
            Fill,
            /// Sampling a tensor from a distribution.
            Random,
            /// Elementwise compute, unary or binary.
            Pointwise,
            /// Reduction along one or more axes.
            Reduction,
            /// Normalization over a set of axes.
            Normalization,
            /// Broadcasting two shapes to a common shape.
            Broadcast,
            /// Reinterpreting a shape with the same element count.
            Reshape,
            /// Collapsing a contiguous axis range into one axis.
            Flatten,
            /// Removing a length-1 axis.
            Squeeze,
            /// Inserting a length-1 axis.
            Unsqueeze,
            /// Reordering axes.
            Permute,
            /// Exchanging two axes.
            Transpose,
            /// Taking a strided sub-range of one or more axes.
            Slice,
            /// Joining tensors along an existing axis.
            Concat,
            /// Joining tensors along a new axis.
            Stack,
            /// Matrix multiplication, including its batched form.
            MatMul,
            /// One-dimensional convolution.
            Conv1d,
            /// Two-dimensional convolution.
            Conv2d,
            /// One-dimensional pooling.
            Pool1d,
            /// Two-dimensional pooling.
            Pool2d,
            /// Two-dimensional pooling to a caller-chosen output extent.
            AdaptiveAvgPool2d,
            /// Gathering rows of a table by index.
            Embedding,
            $(
                #[doc = concat!("Canonical semantic operation `", $name, "`.")]
                $variant,
            )*
        }
    };
}

incin_operation_catalog!(define_operation_kind);

macro_rules! impl_catalog_operation_kind {
    ($(($variant:ident, $name:literal, $family:ident, $profile:ident, $attrs:ident, $min:expr, $max:expr, $legacy:literal),)*) => {
        impl OperationKind {
            /// Whether this is an executable exact identity rather than a
            /// descriptive family/legacy geometry identity.
            #[must_use]
            pub const fn is_exact(self) -> bool {
                matches!(self, $(Self::$variant)|*)
            }

            const fn exact_family(self) -> Option<Self> {
                match self {
                    $(Self::$variant => Some(Self::$family),)*
                    _ => None,
                }
            }

            const fn exact_name(self) -> Option<&'static str> {
                match self {
                    $(Self::$variant => Some($name),)*
                    _ => None,
                }
            }
        }
    };
}

incin_operation_catalog!(impl_catalog_operation_kind);

impl OperationKind {
    /// The coarse family this operation resolves dtype policy at.
    ///
    /// Dtype support is a property of a *class* of work, not of an individual
    /// operation: a backend supports floating-point pointwise arithmetic, not
    /// `add` specifically. `EXE-001` folds every operation onto the six coarse
    /// variants so `incin-backends` can keep resolving policy at that
    /// granularity without a second enum to do it with.
    ///
    /// The groupings follow what the dtype rule actually is:
    ///
    /// * operations that only move or re-address bytes - every shape
    ///   manipulation, plus [`Embedding`](Self::Embedding), which gathers rows
    ///   by integer index - are [`Storage`](Self::Storage), and so accept
    ///   whatever dtype the backend can hold;
    /// * operations that accumulate - [`MatMul`](Self::MatMul), the
    ///   convolutions, and the poolings - are [`Reduction`](Self::Reduction),
    ///   because what makes them float-only and what earns them a widened
    ///   accumulator is that they sum many values into one.
    ///
    /// The result is always one of the six coarse variants, so the function is
    /// idempotent: `k.family().family() == k.family()`.
    #[must_use]
    pub const fn family(self) -> Self {
        if let Some(family) = self.exact_family() {
            return family;
        }
        match self {
            Self::Storage
            | Self::Broadcast
            | Self::Reshape
            | Self::Flatten
            | Self::Squeeze
            | Self::Unsqueeze
            | Self::Permute
            | Self::Transpose
            | Self::Slice
            | Self::Concat
            | Self::Stack
            | Self::Embedding => Self::Storage,
            Self::Fill => Self::Fill,
            Self::Random => Self::Random,
            Self::Pointwise => Self::Pointwise,
            Self::Reduction
            | Self::MatMul
            | Self::Conv1d
            | Self::Conv2d
            | Self::Pool1d
            | Self::Pool2d
            | Self::AdaptiveAvgPool2d => Self::Reduction,
            Self::Normalization => Self::Normalization,
            // Exact variants returned above. This arm keeps the method
            // forward-compatible with the non-exhaustive vocabulary.
            _ => Self::Storage,
        }
    }

    /// The lowercase name used in diagnostics.
    #[must_use]
    pub const fn name(self) -> &'static str {
        if let Some(name) = self.exact_name() {
            return name;
        }
        match self {
            Self::Storage => "storage",
            Self::Fill => "fill",
            Self::Random => "random",
            Self::Pointwise => "pointwise",
            Self::Reduction => "reduction",
            Self::Normalization => "normalization",
            Self::Broadcast => "broadcast",
            Self::Reshape => "reshape",
            Self::Flatten => "flatten",
            Self::Squeeze => "squeeze",
            Self::Unsqueeze => "unsqueeze",
            Self::Permute => "permute",
            Self::Transpose => "transpose",
            Self::Slice => "slice",
            Self::Concat => "concat",
            Self::Stack => "stack",
            Self::MatMul => "matmul",
            Self::Conv1d => "conv1d",
            Self::Conv2d => "conv2d",
            Self::Pool1d => "pool1d",
            Self::Pool2d => "pool2d",
            Self::AdaptiveAvgPool2d => "adaptive_avg_pool2d",
            Self::Embedding => "embedding",
            _ => "unknown_operation",
        }
    }
}

impl fmt::Display for OperationKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.name())
    }
}

/// The position in a shape at which a rule failed.
///
/// [`Named`](Self::Named) exists because the position alone is a poor
/// diagnostic for operations whose layout fixes the meaning of each axis:
/// "axis 1 mismatch" is much less useful than "axis 'channels' mismatch" for a
/// convolution.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Axis {
    /// A positional axis, counted from the front of the shape.
    Index(usize),
    /// An axis identified by the role its operation gives it, such as
    /// `"channels"` or `"height"`.
    Named(&'static str),
    /// The rule constrains the shape as a whole rather than one axis - for
    /// example reshape's element-count equality.
    Whole,
}

impl fmt::Display for Axis {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Index(i) => write!(f, "axis {i}"),
            Self::Named(name) => write!(f, "axis '{name}'"),
            Self::Whole => f.write_str("the shape as a whole"),
        }
    }
}

/// What an operation required of an operand's rank.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum RankExpectation {
    /// Exactly this rank.
    Exactly(usize),
    /// This rank or higher.
    AtLeast(usize),
    /// This rank or lower - usually the rank ceiling of a shape rule.
    AtMost(usize),
    /// Within an inclusive range.
    Between {
        /// Lowest accepted rank.
        min: usize,
        /// Highest accepted rank.
        max: usize,
    },
    /// The same rank as another operand, whose rank is recorded so the message
    /// can state both sides.
    SameAs {
        /// Name of the operand that set the expectation, such as `"lhs"`.
        operand: &'static str,
        /// That operand's rank.
        rank: usize,
    },
}

impl fmt::Display for RankExpectation {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Exactly(n) => write!(f, "exactly {n}"),
            Self::AtLeast(n) => write!(f, "at least {n}"),
            Self::AtMost(n) => write!(f, "at most {n}"),
            Self::Between { min, max } => write!(f, "between {min} and {max}"),
            Self::SameAs { operand, rank } => write!(f, "the same rank as {operand} ({rank})"),
        }
    }
}

/// The rule that related two dimensions at the same axis.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DimensionConstraint {
    /// The two dimensions must be equal.
    Equal,
    /// The two dimensions must be equal, or one of them must be 1.
    Broadcastable,
    /// The left dimension must be an exact multiple of the right.
    DivisibleBy,
    /// The left dimension must be at least the right.
    AtLeast,
}

impl DimensionConstraint {
    /// The rule as a clause that reads after "which must be".
    #[must_use]
    pub const fn describe(self) -> &'static str {
        match self {
            Self::Equal => "equal",
            Self::Broadcastable => "equal, or one of them 1",
            Self::DivisibleBy => "an exact multiple",
            Self::AtLeast => "greater than or equal",
        }
    }
}

impl fmt::Display for DimensionConstraint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.describe())
    }
}

/// A shape rule that could not be discharged.
///
/// Returned by every fallible shape computation. Statically invalid programs do
/// not reach this type - they fail to compile.
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ShapeError {
    /// An operand had the wrong number of dimensions.
    #[error("{operation}: expected rank {expected}, got {actual}")]
    RankMismatch {
        /// Operation being resolved.
        operation: OperationKind,
        /// What the operation required.
        expected: RankExpectation,
        /// The rank the operand actually had.
        actual: usize,
    },

    /// Two dimensions at the same axis violated the operation's rule.
    #[error("{operation}: {axis} mismatch: {lhs} vs {rhs}, which must be {constraint}")]
    DimensionMismatch {
        /// Operation being resolved.
        operation: OperationKind,
        /// Where the rule failed.
        axis: Axis,
        /// The left operand's dimension.
        lhs: usize,
        /// The right operand's dimension.
        rhs: usize,
        /// The rule that related them.
        constraint: DimensionConstraint,
    },

    /// An axis range was empty, reversed, or reached past the operand's rank.
    #[error("{operation}: axis range {start}..{end} is invalid for rank {rank}")]
    InvalidAxisRange {
        /// Operation being resolved.
        operation: OperationKind,
        /// Inclusive start of the requested range.
        start: usize,
        /// Exclusive end of the requested range.
        end: usize,
        /// Rank of the operand the range was applied to.
        rank: usize,
    },

    /// A scalar operation parameter was outside its legal domain - most often a
    /// stride or kernel extent of 0.
    #[error("{operation}: parameter '{parameter}' has invalid value {value}")]
    InvalidParameter {
        /// Operation being resolved.
        operation: OperationKind,
        /// Name of the parameter, as it is spelled in the public API.
        parameter: &'static str,
        /// The rejected value.
        value: usize,
    },

    /// A shape computation overflowed `usize`.
    ///
    /// `expression` names the failing term of the operation's formula, so a
    /// diagnostic points at one multiplication rather than the whole rule.
    #[error("{operation}: arithmetic overflow evaluating '{expression}'")]
    ArithmeticOverflow {
        /// Operation being resolved.
        operation: OperationKind,
        /// The term that overflowed, written as it appears in the formula.
        expression: &'static str,
    },

    /// A computed dimension list did not fit the typed shape it must produce.
    ///
    /// Raised where a rule has already computed its output dimensions as plain
    /// numbers and must rebuild the typed field from them: either the rank
    /// differs, or an axis the target type fixes at compile time disagrees.
    ///
    /// The axis is deliberately absent. Recovering it needs per-axis knowledge
    /// that the erased `&[usize]` form has thrown away - which is the reason
    /// `SHP-004` reconstructs the field axis by axis wherever the arity is
    /// known, and reports [`DimensionMismatch`](Self::DimensionMismatch) with a
    /// real axis there. This variant covers what is left.
    #[error("{operation}: the computed rank-{rank} shape does not fit the target shape type")]
    TargetShapeRejected {
        /// Operation being resolved.
        operation: OperationKind,
        /// Rank of the dimension list that was rejected.
        rank: usize,
    },

    /// An axis index reached past the operand's rank.
    #[error("axis {axis} is invalid for rank {rank}")]
    InvalidAxis {
        /// Axis index.
        axis: usize,
        /// Rank of the operand.
        rank: usize,
    },

    /// An axis selector specified a duplicate axis.
    #[error("axis {axis} specified multiple times in selector sequence")]
    DuplicateAxis {
        /// Axis index that was duplicated.
        axis: usize,
    },

    /// A named selector did not occur in the current structural shape.
    #[error("named axis '{name}' is not present in the shape")]
    MissingNamedAxis {
        /// Axis name referenced.
        name: &'static str,
    },

    /// A named selector occurred more than once and cannot be resolved implicitly.
    #[error("named axis '{name}' is ambiguous: it occurs more than once")]
    AmbiguousNamedAxis {
        /// Axis name referenced.
        name: &'static str,
    },

    /// Two positionally paired broadcast axes carry different semantic names.
    #[error("broadcast axis {axis} has conflicting names '{lhs}' and '{rhs}'")]
    ConflictingNamedAxes {
        /// Right-aligned output axis.
        axis: usize,
        /// Name from the left operand.
        lhs: &'static str,
        /// Name from the right operand.
        rhs: &'static str,
    },

    /// The rule resolved successfully but produced a zero-length axis.
    ///
    /// This is separate from [`DimensionMismatch`](Self::DimensionMismatch)
    /// because no input dimension is wrong: a kernel simply does not fit its
    /// padded input. It is the case the pre-`SHP-005` spatial code silently
    /// produced instead of reporting.
    #[error("{operation}: {axis} would have length 0")]
    EmptyOutput {
        /// Operation being resolved.
        operation: OperationKind,
        /// The axis that collapsed.
        axis: Axis,
    },
}

impl ShapeError {
    /// The operation that failed, for callers that route on it rather than
    /// matching every variant.
    #[must_use]
    pub const fn operation(&self) -> OperationKind {
        match self {
            Self::RankMismatch { operation, .. }
            | Self::DimensionMismatch { operation, .. }
            | Self::InvalidAxisRange { operation, .. }
            | Self::InvalidParameter { operation, .. }
            | Self::ArithmeticOverflow { operation, .. }
            | Self::TargetShapeRejected { operation, .. }
            | Self::EmptyOutput { operation, .. } => *operation,
            _ => OperationKind::Storage,
        }
    }

    /// The axis the failure is attributed to, when the variant names one.
    pub const fn axis(&self) -> Option<Axis> {
        match self {
            Self::DimensionMismatch { axis, .. } | Self::EmptyOutput { axis, .. } => Some(*axis),
            Self::InvalidAxis { axis, .. } | Self::DuplicateAxis { axis } => {
                Some(Axis::Index(*axis))
            }
            _ => None,
        }
    }
}