Crate rstsr 

Notes to API document

This crate is a re-export of the rstsr-core, and possibly the other underlying crates.

We refer these crates for API document.

Notes to User document

User document is currently on readthedocs.

This crate is still in early development. APIs are not fully stablized.

RSTSR: An n-Dimensional Rust Tensor Toolkit

Resources	Badges
User Document
API Document
Crate

Welcome to RSTSR, an n-dimensional tensor toolkit library, in native rust.

This crate will be a building block for scientific computation in native Rust, similar to NumPy of Python.

For users comes from NumPy, the NumPy-RSTSR Cheatsheet (简体中文) will let you quickly be familiar with RSTSR.

This project is still in early stage, and radical code factorization could occur; dev-documentation can still be greatly improved.

Features

• Simple syntex (looks like NumPy, and some core concepts from rust crate ndarray).
• % (remainder) as matrix multiplication (you can &a % &b to perform a.matmul(&b)).
• Allow different devices in framework.
  • We will try to support CUDA and HIP in near future.
• Full support of n-dimensional, broadcasting, basic slicing, reshape.
• Fast on multi-threading CPU.
  • Matmul is provided by backends (such as faer or OpenBLAS).
  • Other cases (summation, element-wise operations) are on-par or even much faster than NumPy (by fast layout iterators and rayon threading).
• Either row-major or column-major is supported (controled by cargo feature). Dynamic row/col-major control can also be performed by device setting.

Supported devices (backends)	Device type name	Crate	Cargo feature
Naive Serial CPU	DeviceCpuSerial	rstsr-core	(always built)
Faer	DeviceFaer	rstsr-core	rstsr/faer
OpenBLAS	DeviceOpenBLAS	rstsr-openblas	rstsr/openblas
oneAPI MKL	DeviceMKL	rstsr-mkl	rstsr/mkl
BLIS/FLAME	DeviceBLIS	rstsr-blis	rstsr/blis
AOCL	DeviceAOCL	rstsr-aocl	rstsr/aocl
KML	DeviceKML	rstsr-kml	rstsr/kml

Illustrative Example

To start with, you may try to run the following code:

use rstsr::prelude::*;

// 3x2 matrix with c-contiguous memory layout
let a = rt::asarray((vec![6., 2., 7., 4., 8., 5.], [3, 2].c()));

// 2x4x3 matrix by arange and reshaping
let b = rt::arange(24.);
let b = b.reshape((-1, 4, 3));
// in one line, you can also
// let b = rt::arange(24.).into_shape((-1, 4, 3));

// broadcasted matrix multiplication
let c = &b % &a;

// print the result
println!("{:6.1}", c);
// output:
// [[[   23.0   14.0]
//   [   86.0   47.0]
//   [  149.0   80.0]
//   [  212.0  113.0]]
//
//  [[  275.0  146.0]
//   [  338.0  179.0]
//   [  401.0  212.0]
//   [  464.0  245.0]]]

// print layout of the result
println!("{:?}", c.layout());
// output:
// 3-Dim (dyn), contiguous: Cc
// shape: [2, 4, 2], stride: [8, 2, 1], offset: 0

Short FAQs

Why RSTSR? There seems many numeric and machine-learning libraries in rust already.

We need a numeric library that supports

• a data structure that supports arbitary types (including complex, half, and arbitary-precision)
• a framework that supports different backends
• fast, at least efficient on server CPU
• supports parallel by threading (specifically rayon)
• large dynamic dimension tensor and its reshape
• functionality can be extended by other crates

And further more,

• the framework may not overwhelm chemist scientists

Many crates in native rust done well in some aspects but not all.

This crate gets inspires from NumPy, Array API standard, ndarray, candle, Burn.

What is supposed to be supported in near future?

• Plugins: Einstein summation, FFT
• GPU devices: CUDA and HIP device support
• rstsr-sci-traits: Optimization, ODE, special functions
• rstsr-core: Full support of Python array API standard (in native rust instead of python binding)
  • searching functions
  • manuplication functions (tile, roll, moveaxis)

What’s RSTSR meaning?

RSTSR actually refers to its relationship with REST Tensor (REST), instead of Rust Tensor. This crate was originally tried to developed a more dev-friendly experience for chemist programmer from numpy/scipy/pytorch.

Is there an illustrative project for using RSTSR in real-world project?

We refer a project that developed before rstsr v0.1: showcase of RI-CCSD. File riccsd.rs is a demonstration of code style to use RSTSR.

如果您能阅读简体中文，REST Workshop：Rust 计算化学程序开发演示 是更加完整的实战项目。它表明 RSTSR 在开发电子结构程序时，兼备开发效率与运行效率。该项目也可以作为 RSTSR 的代码风格展示。

What features will not be implemented?

We do not support autodiff and lazy-evaluation in far future. In this mean time, we are not very concern on machine-learning applications, but focus more on traditional scientific computing, especially applications in electronic structure.

Miscellaneous

Current MSRV (minimal supported rust version) is

• 1.84.1: with crate faer built;
• 1.82.0: other cases (due to crate half and rust language usage of unsafe extern "C").

You are welcomed to raise problems or suggestions in github repo issues or discussions.

Modules

prelude