WIP: API Document Update (#67)

* core -- add lifetime annotation to TensorRefAPI / TensorRefMutAPI

* core -- add macro tensor_from_nested

* docs -- incooperate rstsr-core API specification document into rstsr

* core -- split tensor/manuplication

* doc -- try to add doc of to_broadcast

* core -- changed tensor_from_nested to allow input of device

* common -- refactor error handling code to allow backtrace

* common -- use rstsr_unwrap in most cases instead of unwrap

* linalg-traits, sci-traits -- use rstsr_unwrap in most cases instead of unwrap

* core -- fix allclose to make it accept two tensors broadcasting

* doc -- to_broadcast

* doc -- to_broadcast variants

* doc -- broadcast_arrays

* doc -- expand_dims

* core -- changed impl of tensor_from_nested

* core -- fix bug in expand_dims

* doc -- reshape

* common and doc -- changes to AxesIndex, add unittest of flip

- no_std for rstsr-common and rstsr-native-impl
- do not depend `use_std` feature for crate itertools
- add TryInto impl of AxesIndex<u/isize>
- add function `normalize_axes_index` (similar to numpy.normalize_axis_tuple)
- fix the case where flip can accept multiple same dimensions, and changes behavior of zero-sized axes to be the same to numpy
- add some unittests to flip
- add .gitignore to ignore repomix file (for LLM)

* meta -- further fix no_std

* doc -- flip

* doc and common -- into_dim

- in rstsr-common, changed prelude_dev exports
- in rstsr-common, let `const_ndims` to be member function instead of associated function to type itself

* cargo fmt

* common -- use std::backtrace::Backtrace instead of String for error data-structure representation

Author: ajz34

.github/workflows/rstsr-core-test.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: unittest
-        run: cargo test -p rstsr-core --lib --release --no-default-features --features="std faer rayon col_major faer_as_default"
+        run: cargo test -p rstsr-core --lib --release --no-default-features --features="std backtrace faer rayon col_major faer_as_default"
 
   integration-tests:
     runs-on: ubuntu-latest

.gitignore

@@ -8,6 +8,7 @@ tarpaulin-report.html
 .idea
 book
 *.npy
+repomix-output*
 
 # bindgen
 blas_bindgen.h

Cargo.toml

@@ -55,11 +55,11 @@ rstsr-blis-ffi = { version = "0.2", default-features = false, features = ["lapac
 rstsr-aocl-ffi = { version = "0.2", default-features = false, features = ["blis", "lapack"] }
 rstsr-kml-ffi = { version = "0.2", default-features = false, features = ["kblas", "lapack"] }
 # basic dependencies
-num = { version = "0.4" }
-itertools = { version = "0.13" }
-half = { version = "2.4", features = ["num-traits"] }
+num = { version = "0.4", default-features = false, features = ["alloc", "libm"] }
+itertools = { version = "0.13", default-features = false, features = ["use_alloc"] }
+half = { version = "2.7", default-features = false, features = ["alloc", "num-traits"] }
 libm = { version = "0.2" }
-derive_builder = { version = "0.20" }
+derive_builder = { version = "0.20", default-features = false, features = ["alloc"] }
 duplicate = { version = "2.0" }
 # optional dependencies
 rayon = { version = ">=1.10" }

rstsr-common/Cargo.toml

@@ -21,6 +21,7 @@ rstsr-core = { path = "../rstsr-core", default-features = false }
 
 [features]
 std = []
+backtrace = ["std"]
 rayon = ["dep:rayon"]
 
 # Row-major or Col-major will be contractidary features.

rstsr-common/src/axis_index.rs

@@ -15,7 +15,7 @@ impl<T> AsRef<[T]> for AxesIndex<T> {
     }
 }
 
-/* #region AxisIndex self-type from */
+/* #region AxesIndex self-type from */
 
 impl<T> From<T> for AxesIndex<T> {
     fn from(value: T) -> Self {
@@ -84,25 +84,30 @@ where
     }
 }
 
-impl TryFrom<()> for AxesIndex<usize> {
+#[duplicate_item(T; [usize]; [isize])]
+impl TryFrom<()> for AxesIndex<T> {
     type Error = Error;
 
     fn try_from(_: ()) -> Result<Self> {
         Ok(AxesIndex::Vec(vec![]))
     }
 }
 
-impl TryFrom<()> for AxesIndex<isize> {
+#[duplicate_item(T; [usize]; [isize])]
+impl TryFrom<Option<T>> for AxesIndex<T> {
     type Error = Error;
 
-    fn try_from(_: ()) -> Result<Self> {
-        Ok(AxesIndex::Vec(vec![]))
+    fn try_from(value: Option<T>) -> Result<Self> {
+        match value {
+            Some(v) => Ok(AxesIndex::Val(v)),
+            None => Ok(AxesIndex::Vec(vec![])),
+        }
     }
 }
 
-/* #endregion AxisIndex self-type from */
+/* #endregion AxesIndex self-type from */
 
-/* #region AxisIndex other-type from */
+/* #region AxesIndex other-type from */
 
 macro_rules! impl_try_from_axes_index {
     ($t1:ty, $($t2:ty),*) => {
@@ -129,7 +134,7 @@ macro_rules! impl_try_from_axes_index {
                 fn try_from(value: Vec<$t2>) -> Result<Self> {
                     let value = value
                         .into_iter()
-                        .map(|v| v.try_into().map_err(|_| Error::TryFromIntError(String::new())))
+                        .map(|v| v.try_into().map_err(|_| rstsr_error!(TryFromIntError)))
                         .collect::<Result<Vec<$t1>>>()?;
                     Ok(AxesIndex::Vec(value))
                 }
@@ -173,9 +178,9 @@ macro_rules! impl_try_from_axes_index {
 impl_try_from_axes_index!(usize, isize, u32, u64, i32, i64);
 impl_try_from_axes_index!(isize, usize, u32, u64, i32, i64);
 
-/* #endregion AxisIndex other-type from */
+/* #endregion AxesIndex other-type from */
 
-/* #region AxisIndex tuple-type from */
+/* #region AxesIndex tuple-type from */
 
 // it seems that this directly implementing arbitary AxesIndex<T> will cause
 // conflicting implementation so make a macro for this task
@@ -372,4 +377,45 @@ macro_rules! impl_from_tuple_to_axes_index {
 impl_from_tuple_to_axes_index!(isize);
 impl_from_tuple_to_axes_index!(usize);
 
-/* #endregion AxisIndex tuple-type from */
+/* #endregion AxesIndex tuple-type from */
+
+/* #region utilities for AxesIndex */
+
+/// Normalize axes argument into a tuple of non-negative integer axes.
+pub fn normalize_axes_index(axes: AxesIndex<isize>, ndim: usize, allow_duplicate: bool) -> Result<Vec<isize>> {
+    // generate the normalized axes vector
+    let vec = match axes {
+        AxesIndex::Val(axis) => {
+            let axis = if axis < 0 { (ndim as isize) + axis } else { axis };
+            if axis < 0 || axis >= ndim as isize {
+                rstsr_raise!(InvalidValue, "Axis index {axis} is out of bounds for tensor with {ndim} dimensions.")?;
+            }
+            vec![axis]
+        },
+        AxesIndex::Vec(axes) => {
+            let mut normalized_axes = Vec::with_capacity(axes.len());
+            for &axis in axes.iter() {
+                let norm_axis = if axis < 0 { (ndim as isize) + axis } else { axis };
+                if norm_axis < 0 || norm_axis >= ndim as isize {
+                    rstsr_raise!(
+                        InvalidValue,
+                        "Axis index {axis} is out of bounds for tensor with {ndim} dimensions."
+                    )?;
+                }
+                normalized_axes.push(norm_axis);
+            }
+            normalized_axes.sort();
+            normalized_axes
+        },
+    };
+    if !allow_duplicate {
+        for i in 1..vec.len() {
+            if vec[i] == vec[i - 1] {
+                rstsr_raise!(InvalidValue, "Duplicate axis index {} found in axes argument.", vec[i])?;
+            }
+        }
+    }
+    Ok(vec)
+}
+
+/* #endregion */