strided_view/
lib.rs

1//! Device-agnostic strided view types and metadata operations.
2//!
3//! This crate is a Rust port of Julia's [StridedViews.jl](https://github.com/Jutho/StridedViews.jl),
4//! providing strided multidimensional array view types with zero-copy metadata transformations.
5//!
6//! # Core Types
7//!
8//! - [`StridedView`] / [`StridedViewMut`]: Dynamic-rank strided views over existing data
9//! - [`StridedArray`]: Owned strided multidimensional array
10//! - [`ElementOp`] trait and implementations ([`Identity`], [`Conj`], [`Transpose`], [`Adjoint`]):
11//!   Type-level element operations applied lazily on access
12//!
13//! # Metadata Transformations
14//!
15//! These operate only on dims/strides/offset and never access the underlying data:
16//! - `permute`: Reorder dimensions
17//! - `transpose_2d`, `adjoint_2d`: 2D matrix transformations
18//! - `conj`: Compose conjugation operation
19//! - `broadcast`: Expand size-1 dimensions
20
21pub mod auxiliary;
22mod element_op;
23mod raw;
24pub mod view;
25
26// ============================================================================
27// Element operations
28// ============================================================================
29pub use element_op::{
30    Adjoint, ComposableElementOp, Compose, Conj, ElementOp, ElementOpApply, Identity, Transpose,
31};
32
33// ============================================================================
34// View-based types
35// ============================================================================
36pub use raw::{
37    ErasedRawStridedMut, ErasedRawStridedPtr, ErasedRawStridedRef, ErasedRawStridedUninitMut,
38    KernelDType, KernelStorageElement, RawStridedMut, RawStridedRef,
39};
40pub use view::{col_major_strides, row_major_strides, StridedArray, StridedView, StridedViewMut};
41
42// ============================================================================
43// Error types
44// ============================================================================
45
46/// Errors that can occur during strided array operations.
47#[derive(Debug, thiserror::Error)]
48pub enum StridedError {
49    /// Array ranks do not match.
50    #[error("rank mismatch: {0} vs {1}")]
51    RankMismatch(usize, usize),
52
53    /// Array shapes are incompatible for the operation.
54    #[error("shape mismatch: {0:?} vs {1:?}")]
55    ShapeMismatch(Vec<usize>, Vec<usize>),
56
57    /// Invalid axis index for the given array rank.
58    #[error("invalid axis {axis} for rank {rank}")]
59    InvalidAxis { axis: usize, rank: usize },
60
61    /// Stride array length doesn't match dimensions.
62    #[error("stride and dims length mismatch")]
63    StrideLengthMismatch,
64
65    /// Integer overflow while computing array offset.
66    #[error("offset overflow while computing pointer")]
67    OffsetOverflow,
68
69    /// Failed to convert a scalar value for scaling operation.
70    #[error("failed to convert scalar for scaling")]
71    ScalarConversion,
72
73    /// Matrix is not square when a square matrix was required.
74    #[error("non-square matrix: rows={rows}, cols={cols}")]
75    NonSquare { rows: usize, cols: usize },
76
77    /// Mutable output layout maps multiple logical elements to the same memory offset.
78    #[error("mutable output layout is not injective")]
79    NonInjectiveOutputLayout,
80
81    /// Runtime view layout does not match the layout a prepared plan was compiled for.
82    #[error("view layout does not match the compiled plan")]
83    PlanLayoutMismatch,
84
85    /// Runtime dtype does not match the dtype a prepared plan was compiled for.
86    #[error("dtype mismatch: expected {expected}, got {actual}")]
87    DTypeMismatch {
88        expected: &'static str,
89        actual: &'static str,
90    },
91
92    /// A byte buffer length is not a whole number of dtype elements.
93    #[error(
94        "byte length {byte_len} is not a multiple of element size {element_size} for dtype {dtype}"
95    )]
96    ByteLengthMismatch {
97        dtype: &'static str,
98        byte_len: usize,
99        element_size: usize,
100    },
101
102    /// A byte buffer pointer does not satisfy the dtype alignment.
103    #[error("data pointer for dtype {dtype} is not aligned to {alignment} bytes")]
104    DataAlignmentMismatch {
105        dtype: &'static str,
106        alignment: usize,
107    },
108
109    /// A byte buffer for `bool` contains a value that is not a valid Rust bool.
110    #[error("invalid bool byte value {value}")]
111    InvalidBoolByte { value: u8 },
112
113    /// An execution context requested an invalid worker-thread budget.
114    #[error("invalid thread budget {max_threads}")]
115    InvalidThreadBudget { max_threads: usize },
116
117    /// The dtype is recognized but unsupported by the selected operation.
118    #[error("unsupported dtype {dtype}")]
119    UnsupportedDType { dtype: &'static str },
120
121    /// The dtype is recognized, but the selected op is not defined for it.
122    #[error("unsupported op {op} for dtype {dtype}")]
123    UnsupportedOp {
124        op: &'static str,
125        dtype: &'static str,
126    },
127
128    /// A mutable destination overlaps one of the operation inputs.
129    #[error("destination overlaps input {input}")]
130    OverlappingInputOutput { input: usize },
131
132    /// Integer division or remainder encountered a zero divisor.
133    #[error("integer {op} encountered a zero divisor")]
134    IntegerDivisionByZero { op: &'static str },
135
136    /// The operation arity is unsupported by this entry point.
137    #[error("unsupported arity {arity}; maximum supported arity is {max}")]
138    UnsupportedArity { arity: usize, max: usize },
139}
140
141/// Result type for strided array operations.
142pub type Result<T> = std::result::Result<T, StridedError>;
strided_view/lib.rs

strided_view/
lib.rs
