strided_kernel/
lib.rs

1//! Cache-optimized kernels for strided multidimensional array operations.
2//!
3//! This crate is a Rust port of Julia's [Strided.jl](https://github.com/Jutho/Strided.jl)
4//! and [StridedViews.jl](https://github.com/Jutho/StridedViews.jl) libraries, providing
5//! efficient operations on strided multidimensional array views.
6//!
7//! # Core Types
8//!
9//! - [`StridedView`] / [`StridedViewMut`]: Dynamic-rank strided views over existing data
10//! - [`StridedArray`]: Owned strided multidimensional array
11//! - [`ElementOp`] trait and implementations ([`Identity`], [`Conj`], [`Transpose`], [`Adjoint`]):
12//!   Type-level element operations applied lazily on access
13//!
14//! # Primary API (view-based, Julia-compatible)
15//!
16//! ## Map Operations
17//!
18//! - [`map_into`]: Apply a function element-wise from source to destination
19//! - [`zip_map2_into`], [`zip_map3_into`], [`zip_map4_into`]: Multi-array element-wise operations
20//!
21//! ## Reduce Operations
22//!
23//! - [`reduce`]: Full reduction with map function
24//! - [`reduce_axis`]: Reduce along a single axis
25//!
26//! ## Basic Operations
27//!
28//! - [`copy_into`]: Copy array contents
29//! - [`add`], [`mul`]: Element-wise arithmetic
30//! - [`axpy`]: y = alpha*x + y (array version)
31//! - [`sum`], [`dot`]: Reductions
32//! - [`symmetrize_into`], [`symmetrize_conj_into`]: Matrix symmetrization
33//!
34//! # Example
35//!
36//! ```rust
37//! use strided_kernel::{StridedView, StridedViewMut, StridedArray, Identity, map_into};
38//!
39//! // Create a column-major array (Julia default)
40//! let src = StridedArray::<f64>::from_fn_col_major(&[2, 3], |idx| {
41//!     (idx[0] * 10 + idx[1]) as f64
42//! });
43//! let mut dest = StridedArray::<f64>::col_major(&[2, 3]);
44//!
45//! // Map with view-based API
46//! map_into(&mut dest.view_mut(), &src.view(), |x| x * 2.0).unwrap();
47//! assert_eq!(dest.get(&[1, 2]), 24.0); // (1*10 + 2) * 2
48//! ```
49//!
50//! # Cache Optimization
51//!
52//! The library uses Julia's blocking strategy for cache efficiency:
53//! - Dimensions are sorted by stride magnitude for optimal memory access
54//! - Operations are blocked into tiles fitting L1 cache ([`BLOCK_MEMORY_SIZE`] = 32KB)
55//! - Contiguous arrays use fast paths bypassing the blocking machinery
56
57mod block;
58mod fuse;
59mod fused;
60mod kernel;
61mod order;
62mod simd;
63#[cfg(feature = "parallel")]
64mod threading;
65
66mod maybe_sync;
67pub use maybe_sync::{MaybeSend, MaybeSendSync, MaybeSync};
68
69// View-based operation modules
70mod copy_plan;
71mod map_view;
72mod ops_view;
73mod outer_product;
74mod raw_ops;
75mod reduce_view;
76
77// ============================================================================
78// Re-exports from strided_view for backward compatibility
79// ============================================================================
80pub use strided_view::view;
81pub use strided_view::{
82    col_major_strides, row_major_strides, Adjoint, ComposableElementOp, Compose, Conj, ElementOp,
83    ElementOpApply, Identity, RawStridedMut, RawStridedRef, Result, StridedArray, StridedError,
84    StridedView, StridedViewMut, Transpose,
85};
86
87// ============================================================================
88// Map operations
89// ============================================================================
90pub use map_view::{
91    broadcast_mul_into, map_into, mul_into, zip_map2_into, zip_map3_into, zip_map4_into,
92};
93
94// ============================================================================
95// Runtime-DAG fused elementwise operations
96// ============================================================================
97pub use fused::{fused_elementwise_into, FusedInst, FusedOp, FusedPlan, FusedScalar};
98
99// ============================================================================
100// Outer-product operations
101// ============================================================================
102pub use outer_product::batched_outer_product_into;
103
104// ============================================================================
105// High-level operations
106// ============================================================================
107pub use ops_view::{
108    add, axpy, copy_conj, copy_into, copy_into_col_major, copy_scale, copy_transpose_scale_into,
109    dot, fma, mul, sum, symmetrize_conj_into, symmetrize_into,
110};
111
112// ============================================================================
113// Raw (borrowed-metadata, allocation-free) operations
114// ============================================================================
115pub use raw_ops::{
116    axpy_conj_raw, axpy_raw, copy_scale_conj_raw, copy_scale_raw, RAW_FUSED_RANK_LIMIT,
117};
118
119// ============================================================================
120// Prepared (compile-once, execute-many) plans
121// ============================================================================
122pub use copy_plan::CopyPlan;
123
124// ============================================================================
125// Reduce operations
126// ============================================================================
127pub use reduce_view::{reduce, reduce_axis};
128
129// ============================================================================
130// SIMD trait
131// ============================================================================
132pub use simd::MaybeSimdOps;
133
134// ============================================================================
135// Constants
136// ============================================================================
137
138/// Block memory size for cache-optimized iteration (L1 cache target).
139///
140/// Operations are blocked into tiles that fit within this size to maximize cache hits.
141/// Default: 32KB (typical L1 data cache size).
142pub const BLOCK_MEMORY_SIZE: usize = 32 * 1024;
143
144/// Cache line size in bytes.
145///
146/// Used for memory region calculations in block size computation.
147pub const CACHE_LINE_SIZE: usize = 64;
strided_kernel/lib.rs

strided_kernel/
lib.rs
