Improve and uniformize naming across CubeCL (axis/count/line_size)

Cargo.toml

@@ -88,7 +88,7 @@ rstest = "0.26"
 serial_test = "3.1.1"
 
 bytemuck = "1.16.1"
-bytes = { version = "1.10", default-features = false }
+bytes = { version = "1.11.1", default-features = false }
 float-ord = "0.3"
 float4 = "0.1"
 float8 = { version = "0.7", default-features = false }

conventions.md

@@ -0,0 +1,46 @@
+# CubeCL Naming Conventions
+
+This document describes the naming conventions used throughout the CubeCL codebase.
+
+## Tensor Dimensions
+
+- Use **`axis`** (not `dim` or `dimension`) when referring to a specific dimension of a tensor.
+  - `tensor.stride(axis)`, `tensor.shape(axis)`, `tensor.coordinate(index, axis)`
+
+## Counts
+
+- Use **`_count` suffix** (not `num_` prefix) for quantities.
+  - `streaming_multiprocessor_count`, `cpu_core_count`, `tensor_core_count`
+  - `elem_count`, `cube_count`, `meta_count`
+  - Constants: `SM_COUNT_APPROX`
+
+## Line Size
+
+- Use **`line_size`** (not `vectorization` or `vectorization_factor`) for the number of
+  elements packed into a line.
+  - `tensor.line_size()`, `find_line_size()`, `tensor_line_size_parallel()`
+  - `tensor_vectorization_factor()` remains only as a deprecated compatibility alias.
+
+## Tensor Ordering
+
+- **`RowMajor`** / **`ColMajor`** are the primary names for matrix layouts.
+- **`DecreasingOrder`** / **`IncreasingOrder`** are available as aliases:
+  - `MatrixLayout::IncreasingOrder` = `MatrixLayout::ColMajor`
+  - `MatrixLayout::DecreasingOrder` = `MatrixLayout::RowMajor`
+
+## Coordinates and Offsets
+
+- Use **`offset`** for linear buffer/slice positions.
+- Use **`coordinate`** for multi-dimensional tensor positions.
+
+## Topology Constants
+
+- Use **`POS`** suffix for positions: `UNIT_POS`, `CUBE_POS`, `PLANE_POS`.
+- Use **`DIM`** suffix for topology dimensions: `CUBE_DIM`, `PLANE_DIM`.
+
+## Type Naming
+
+- Use **postfix suffixes** for type categories:
+  - `*Error` for error types: `LineSizeError`, `LaunchError`
+  - `*Strategy` for strategy types: `ReadingStrategy`
+  - `*Expand` for expand/meta types: `TensorExpand`, `SliceExpand`

crates/cubecl-core/src/codegen/metadata.rs

@@ -44,32 +44,32 @@ const EXTENDED_LEN: u32 = 3;
 /// Helper to calculate metadata offsets based on buffer count and position
 #[derive(Clone, Debug, Default)]
 pub struct Metadata {
-    num_meta: u32,
-    num_extended_meta: u32,
+    meta_count: u32,
+    extended_meta_count: u32,
 }
 
 impl Metadata {
-    pub fn new(num_meta: u32, num_extended_meta: u32) -> Self {
+    pub fn new(meta_count: u32, extended_meta_count: u32) -> Self {
         Self {
-            num_meta,
-            num_extended_meta,
+            meta_count,
+            extended_meta_count,
         }
     }
 
     fn offset_of(&self, id: u32) -> u32 {
-        self.num_meta * id
+        self.meta_count * id
     }
 
     fn base_len(&self) -> u32 {
-        self.num_meta * BASE_LEN
+        self.meta_count * BASE_LEN
     }
 
     pub fn static_len(&self) -> u32 {
-        self.num_meta * BASE_LEN + self.num_extended_meta * EXTENDED_LEN
+        self.meta_count * BASE_LEN + self.extended_meta_count * EXTENDED_LEN
     }
 
     fn offset_of_extended(&self, id: u32) -> u32 {
-        self.base_len() + self.num_extended_meta * id
+        self.base_len() + self.extended_meta_count * id
     }
 
     pub fn buffer_len_index(&self, buffer_idx: u32) -> u32 {
@@ -163,11 +163,11 @@ impl MetadataBuilder {
     /// Build the final serialized metadata struct
     pub fn finish(&mut self, address_type: AddressType) -> MetadataBinding {
         fn finish_inner<T: Pod + NumCast>(state: &mut State<T>) -> MetadataBinding {
-            let num_base = state.buffer_lens.len();
-            let num_ext = state.ranks.len();
+            let base_count = state.buffer_lens.len();
+            let ext_count = state.ranks.len();
 
             // All entries have buffer_len and len, extended also have rank, shape_offs, strides_offs
-            let static_len = num_base * BASE_LEN as usize + num_ext * EXTENDED_LEN as usize;
+            let static_len = base_count * BASE_LEN as usize + ext_count * EXTENDED_LEN as usize;
             let dynamic_len = state.shapes.len() + state.strides.len();
             let total_len = static_len + dynamic_len;
 

crates/cubecl-core/src/compute/launcher.rs

@@ -192,18 +192,16 @@ impl<R: Runtime> TensorState<R> {
     }
 
     fn process_tensor(&mut self, tensor: &TensorArg<'_, R>) -> Option<Binding> {
-        let (tensor, vectorization) = match tensor {
+        let (tensor, line_size) = match tensor {
             TensorArg::Handle {
-                handle,
-                line_size: vectorization_factor,
-                ..
-            } => (handle, vectorization_factor),
+                handle, line_size, ..
+            } => (handle, line_size),
             TensorArg::Alias { .. } => return None,
         };
 
-        let elem_size = tensor.elem_size * *vectorization;
+        let elem_size = tensor.elem_size * *line_size;
         let buffer_len = tensor.handle.size() / elem_size as u64;
-        let len = tensor.shape.iter().product::<usize>() / *vectorization;
+        let len = tensor.shape.iter().product::<usize>() / *line_size;
         with_metadata(|meta| {
             meta.register_tensor(
                 tensor.strides.len() as u64,
@@ -225,21 +223,19 @@ impl<R: Runtime> TensorState<R> {
     }
 
     fn process_array(&mut self, array: &ArrayArg<'_, R>) -> Option<Binding> {
-        let (array, vectorization) = match array {
+        let (array, line_size) = match array {
             ArrayArg::Handle {
-                handle,
-                line_size: vectorization_factor,
-                ..
-            } => (handle, vectorization_factor),
+                handle, line_size, ..
+            } => (handle, line_size),
             ArrayArg::Alias { .. } => return None,
         };
 
-        let elem_size = array.elem_size * *vectorization;
+        let elem_size = array.elem_size * *line_size;
         let buffer_len = array.handle.size() / elem_size as u64;
         with_metadata(|meta| {
             meta.register_array(
                 buffer_len,
-                array.length[0] as u64 / *vectorization as u64,
+                array.length[0] as u64 / *line_size as u64,
                 self.address_type(),
             )
         });

crates/cubecl-core/src/frontend/container/tensor/base.rs

@@ -37,15 +37,15 @@ mod metadata {
 
     #[cube]
     impl<T: CubeType> Tensor<T> {
-        /// Obtain the stride of input at dimension dim
+        /// Obtain the stride of input at the given axis
         #[allow(unused_variables)]
-        pub fn stride(&self, dim: usize) -> usize {
+        pub fn stride(&self, axis: usize) -> usize {
             intrinsic!(|scope| {
-                let dim: ExpandElement = dim.into();
+                let axis: ExpandElement = axis.into();
                 let out = scope.create_local(Type::new(usize::as_type(scope)));
                 scope.register(Instruction::new(
                     Metadata::Stride {
-                        dim: *dim,
+                        axis: *axis,
                         var: self.expand.into(),
                     },
                     out.clone().into(),
@@ -54,15 +54,15 @@ mod metadata {
             })
         }
 
-        /// Obtain the shape of input at dimension dim
+        /// Obtain the shape of input at the given axis
         #[allow(unused_variables)]
-        pub fn shape(&self, dim: usize) -> usize {
+        pub fn shape(&self, axis: usize) -> usize {
             intrinsic!(|scope| {
-                let dim: ExpandElement = dim.into();
+                let axis: ExpandElement = axis.into();
                 let out = scope.create_local(Type::new(usize::as_type(scope)));
                 scope.register(Instruction::new(
                     Metadata::Shape {
-                        dim: *dim,
+                        axis: *axis,
                         var: self.expand.into(),
                     },
                     out.clone().into(),
@@ -71,32 +71,32 @@ mod metadata {
             })
         }
 
-        /// Obtain the coordinate corresponding to the given `index` of the tensor at dimension `dim`.
+        /// Obtain the coordinate corresponding to the given `index` of the tensor at the given `axis`.
         ///
         /// A coordinate is a list of indices corresponding to the multi-dimensional position of an element in the tensor.
-        /// The `dim` element in a coordinate is the position along the `dim` dimension of the tensor.
+        /// The `axis` element in a coordinate is the position along that axis of the tensor.
         #[allow(unused_variables)]
-        pub fn coordinate(&self, index: usize, dim: usize) -> usize {
+        pub fn coordinate(&self, index: usize, axis: usize) -> usize {
             intrinsic!(|scope| {
                 let index: ExpandElement = index.into();
-                let stride = self.clone().__expand_stride_method(scope, dim.clone());
-                let shape = self.clone().__expand_shape_method(scope, dim.clone());
+                let stride = self.clone().__expand_stride_method(scope, axis.clone());
+                let shape = self.clone().__expand_shape_method(scope, axis.clone());
 
-                // Compute `num_strides = index / stride`.
-                let num_strides = scope.create_local(Type::new(usize::as_type(scope)));
+                // Compute `stride_count = index / stride`.
+                let stride_count = scope.create_local(Type::new(usize::as_type(scope)));
                 scope.register(Instruction::new(
                     Arithmetic::Div(BinaryOperator {
                         lhs: *index,
                         rhs: stride.expand.into(),
                     }),
-                    num_strides.clone().into(),
+                    stride_count.clone().into(),
                 ));
 
-                // Compute `coordinate = num_strides % shape `.
+                // Compute `coordinate = stride_count % shape `.
                 let coordinate = scope.create_local(Type::new(usize::as_type(scope)));
                 scope.register(Instruction::new(
                     Arithmetic::Modulo(BinaryOperator {
-                        lhs: *num_strides,
+                        lhs: *stride_count,
                         rhs: shape.expand.into(),
                     }),
                     coordinate.clone().into(),
@@ -106,12 +106,12 @@ mod metadata {
             })
         }
 
-        /// The number of vectorized elements in the tensor.
+        /// The number of lined elements in the tensor.
         ///
         /// # Warning
         ///
-        /// The length will be affected by the vectorization factor. To obtain the number of elements,
-        /// you should multiply the length by the vectorization factor.
+        /// The length will be affected by the line size. To obtain the number of elements,
+        /// you should multiply the length by the line size.
         #[allow(clippy::len_without_is_empty)]
         pub fn len(&self) -> usize {
             intrinsic!(|scope| {
@@ -120,12 +120,12 @@ mod metadata {
             })
         }
 
-        /// The length of the buffer representing the tensor in terms of vectorized elements.
+        /// The length of the buffer representing the tensor in terms of lined elements.
         ///
         /// # Warning
         ///
-        /// The buffer length will be affected by the vectorization factor. To obtain the number of
-        /// elements, you should multiply the length by the vectorization factor.
+        /// The buffer length will be affected by the line size. To obtain the number of
+        /// elements, you should multiply the length by the line size.
         #[allow(clippy::len_without_is_empty)]
         pub fn buffer_len(&self) -> usize {
             intrinsic!(|scope| {

crates/cubecl-core/src/frontend/container/tensor/launch.rs

@@ -21,7 +21,7 @@ pub enum TensorArg<'a, R: Runtime> {
     Handle {
         /// The tensor handle.
         handle: TensorHandleRef<'a, R>,
-        /// The vectorization factor.
+        /// The line size.
         line_size: LineSize,
     },
     /// The tensor is aliasing another input tensor.
@@ -118,7 +118,7 @@ impl<C: CubePrimitive> LaunchArg for Tensor<C> {
 }
 
 impl<'a, R: Runtime> TensorArg<'a, R> {
-    /// Create a new tensor argument specified with its vectorization factor.
+    /// Create a new tensor argument specified with its line size.
     ///
     /// # Safety
     ///
@@ -128,7 +128,7 @@ impl<'a, R: Runtime> TensorArg<'a, R> {
         handle: &'a cubecl_runtime::server::Handle,
         strides: &'a [usize],
         shape: &'a [usize],
-        factor: LineSize,
+        line_size: LineSize,
     ) -> Self {
         unsafe {
             Self::Handle {
@@ -138,12 +138,12 @@ impl<'a, R: Runtime> TensorArg<'a, R> {
                     shape,
                     E::size().expect("Element should have a size"),
                 ),
-                line_size: factor,
+                line_size,
             }
         }
     }
 
-    /// Create a new tensor argument specified with its vectorization factor with a manual element
+    /// Create a new tensor argument specified with its line size with a manual element
     /// size in bytes.
     ///
     /// # Safety
@@ -154,13 +154,13 @@ impl<'a, R: Runtime> TensorArg<'a, R> {
         handle: &'a cubecl_runtime::server::Handle,
         strides: &'a [usize],
         shape: &'a [usize],
-        factor: LineSize,
+        line_size: LineSize,
         elem_size: usize,
     ) -> Self {
         unsafe {
             Self::Handle {
                 handle: TensorHandleRef::from_raw_parts(handle, strides, shape, elem_size),
-                line_size: factor,
+                line_size,
             }
         }
     }