Russell - Rust Scientific Library <!-- omit from toc -->

<h1 align="center"> <a href="https://github.com/cpmech/russell"><img src="logo.svg" alt="Russell" width="368px"></a> <br> </h1> <p align="center"> <b>Numerical mathematics, ordinary differential equations, special math functions, high-performance (sparse) linear algebra</b><br /> </p>

---

---

---

---

Contents <!-- omit from toc -->

• Introduction
• Installation
  • Debian/Ubuntu Linux
  • Rocky Linux
  • Arch Linux
  • macOS
  • Optional feature "local_suitesparse"
  • Optional feature "with_mumps"
  • Optional feature "intel_mkl"
  • Number of threads
• 🌟 Examples
  • (lab) Numerical integration (quadrature)
  • (lab) Solution of PDEs using spectral collocation
  • (lab) Matrix visualization
  • (lab) Singular value decomposition
  • (lab) Cholesky factorization
  • (lab) Solution of a (dense) linear system
  • (lab) Reading table-formatted data files
  • (sparse) Solution of a sparse linear system
  • (ode) Solution of the Brusselator ODE
  • (ode) Solution of the Brusselator PDE
  • (stat) Generate the Frechet distribution
  • (tensor) Allocate second-order tensors
• Roadmap

Introduction

Russell (Rust Scientific Library) assists in developing high-performance computations involving linear algebra, sparse linear systems, differential equations, statistics, and continuum mechanics using the Rust programming language. The applications built with Russell revolve around the computational mechanics discipline; however, since Russell deals with fundamental mathematics and numerics, it is also helpful for other disciplines.

Russell aims to deliver efficient, reliable, and easy-to-maintain code. Thus, Russell implements several unit and integration tests and requires test coverage to be over 95%. For the sake of code maintenance, Russell avoids overcomplicated Rust constructions. Nonetheless, Russell considers a good range of Rust concepts, such as generics and traits, and convenient/powerful constructs, such as enums, options, and results. Another goal of Russell is to publish examples of all computations in the documentation to assist the user/developer.

Available libraries:

• russell_lab Scientific laboratory with special math functions, linear algebra, interpolation, quadrature, numerical derivation, and more
• russell_ode Solvers for ordinary differential equations (ODEs) and differential algebraic equations (DAEs)
• russell_sparse Solvers for large sparse linear systems (wraps MUMPS and UMFPACK)
• russell_stat Statistics calculations and (engineering) probability distributions
• russell_tensor Tensor analysis, calculus, and functions for continuum mechanics

👆 Check the crate version and update your Cargo.toml accordingly. Examples:

[dependencies]
russell_lab = "*"
russell_sparse = "*"
russell_ode = "*"
russell_stat = "*"
russell_tensor = "*"

All crates have an option to use Intel MKL instead of the default OpenBLAS. For instance, the features keyword may be configured as follows:

[dependencies]
russell_lab = { version = "*", features = ["intel_mkl"] }
russell_sparse = { version = "*", features = ["intel_mkl"] }
russell_ode = { version = "*", features = ["intel_mkl"] }
russell_stat = { version = "*", features = ["intel_mkl"] }
russell_tensor = { version = "*", features = ["intel_mkl"] }

External associated and recommended crates:

• plotpy Plotting tools using Python3/Matplotlib as an engine (for quality graphics)
• tritet Triangle and tetrahedron mesh generators (with Triangle and Tetgen)
• gemlab Geometry, meshes, and numerical integration for finite element analyses

Installation

Russell requires some non-Rust libraries (e.g., OpenBLAS, Intel MKL, MUMPS, SuiteSparse) to achieve the max performance. These libraries can be installed as explained in each subsection next.

After installing the dependencies, you may add each crate using:

cargo add russell_lab
cargo add russell_sparse # etc.

Debian/Ubuntu Linux

Required libraries:

# install libraries for russell
sudo apt-get install -y --no-install-recommends \
    liblapacke-dev \
    libopenblas-dev \
    libsuitesparse-dev

Rocky Linux

Required libraries:

# initialize
dnf update -y
dnf install epel-release -y
crb enable

# install libraries for russell
dnf install -y \
  lapack-devel \
  openblas-devel \
  suitesparse-devel

Arch Linux

Required libraries:

# install libraries for russell
yay -Y --gendb --noconfirm && yay -Y --devel --save
yay -Syu blas-openblas --noconfirm
yay -Syu suitesparse --noconfirm

macOS

First, install Homebrew. Then, run:

# install libraries for russell
brew install lapack openblas suite-sparse

Optional feature "local_suitesparse"

russell_sparse allows the use of a locally compiled SuiteSparse, installed in /usr/local/include/suitesparse and /usr/local/lib/suitesparse. This option is defined by the local_suitesparse feature. The compile-and-install-suitesparse script may be used in this case:

bash zscripts/compile-and-install-suitesparse.bash

Optional feature "with_mumps"

russell_sparse has an optional feature named with_mumps which enables the MUMPS solver. To use this feature, MUMPS needs to be locally compiled first. The compile-and-install-mumps script may be used in this case:

bash zscripts/compile-and-install-mumps.bash

Optional feature "intel_mkl"

To enable Intel MKL (and disable OpenBLAS), the optional intel_mkl feature may be used. In this case SuiteSparse (and MUMPS) must be locally compiled (with Intel MKL). This step can be easily accomplished by the compile-and-install-suitesparse and [compile