russell

Contents

• Introduction
  • External associated and recommended crates
  • Features
• WebAssembly
• Installation
  • Arch Linux
    • Option 1: OpenBLAS and SuiteSparse from the package manager
    • Option 2: Locally compiled SuiteSparse and MUMPS with OpenBLAS
    • Option 3: Locally compiled SuiteSparse and MUMPS with Intel MKL
  • Debian/Ubuntu Linux
    • Option 1: OpenBLAS and SuiteSparse from the package manager
    • Option 2: Locally compiled SuiteSparse and MUMPS with OpenBLAS
    • Option 3: Locally compiled SuiteSparse and MUMPS with Intel MKL
  • Rocky Linux
    • Option 1: OpenBLAS and SuiteSparse from the package manager
  • macOS
    • Option 1: OpenBLAS and SuiteSparse from the package manager
    • Option 2: Locally compiled MUMPS
  • Windows
  • 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
  • (lab) Line search for optimization
  • (nonlin) Numerical continuation of a B-spline curve
  • (sparse) Solution of a sparse linear system
  • (sparse) Solution of a complex sparse linear system
  • (ode) Solution of the Brusselator ODE
  • (ode) Solution of the Brusselator PDE
  • (pde) Spectral collocation in 2D with transfinite mapping
  • (stat) Generate the Frechet distribution
  • (tensor) Allocate second-order tensors
• Roadmap
• For developers
  • Naming conventions
  • russell_lab — BLAS/LAPACK
  • russell_sparse — sparse solvers
• About the name

Introduction

Russell (Rust Scientific Library) helps develop high-performance computations involving linear algebra, sparse linear systems, numerical mathematics (continuation), differential equations, statistics, and continuum mechanics using the Rust programming language. While applications built with Russell mainly focus on computational mechanics, its foundation in fundamental mathematics and numerics makes it useful for other disciplines as well.

This project aims to deliver efficient, reliable, and easy-to-maintain code. To support this, Russell includes unit and integration tests, with test coverage required to be over 95%. For better code maintenance, Russell avoids overly complex Rust constructions. However, it still makes use of Rust features such as generics, traits, enums, options, and results. Another goal of Russell is to provide examples of all computations in the documentation to assist users and developers.

This project is split into the following crates:

1. russell_lab — Core mathematical and linear algebra laboratory:
   • Data structures: NumVector, NumMatrix (column-major layout for direct BLAS/LAPACK interoperability), and stack-allocated SmallVector/SmallMatrix.
   • Linear Algebra: BLAS 1/2/3 and LAPACK routines (dense solves, SVD, Cholesky, symmetric and general eigenvalues/eigenvectors for real and complex numbers).
   • Numerics & Special Functions: Bessel, modified Bessel, Beta, Gamma, Erf, Elliptic integrals, Chebyshev/Legendre polynomials, Lagrange interpolation, B-splines, quadrature, Brent's root-finding, Newton solver, cubic solver, and numerical derivatives/Jacobians.
   • Backends: pure-Rust BLAS/LAPACK from the algebra_linear crate by default; OpenBLAS (open_blas) or Intel oneAPI MKL (intel_mkl) as opt-in accelerators.
2. russell_tensor — Tensor calculus and continuum mechanics:
   • Tensor types: Tensor1 (3D vectors), Tensor2 (2nd-order), Tensor3 (3rd-order), Tensor4 (4th-order).
   • Kelvin-Mandel representation: Maps tensors to vector/matrix spaces preserving Euclidean norms.
   • Operations & Calculus: Dot/ddot contractions, dyadic products, polar decompositions, principal/deviatoric/octahedral invariants, Lode invariant, first and second derivatives of invariants and tensor functions, linear elasticity / Hooke's law.
3. russell_sparse — Sparse matrix structures and solvers:
   • Formats: CooMatrix, CscMatrix, CsrMatrix (both real f64 and Complex64).
   • Direct Solvers: pure-Rust Direct (Genie::Direct, always available), UMFPACK (SuiteSparse), and MUMPS (mumps).
   • Iterative Solvers: preconditioned CG, BiCGStab, and restarted GMRES with algebraic multigrid (pure Rust, always available).
   • Utilities: Matrix Market I/O, vismatrix exporter, numerical Jacobian assembly, linear system verification.
4. russell_ode — ODE and Index-1 DAE solvers:
   • Explicit Runge-Kutta (DoPri5, DoPri8, Forward Euler) with stiffness detection and dense output.
   • Implicit solvers: Backward Euler and Radau5 (supports mass matrices, DAEs, and concurrent real/complex linear solves).
5. russell_pde — Partial differential equation tools:
   • 1D/2D Finite Difference Methods (FDM) and Spectral Collocation (SPC) on Chebyshev/Legendre-Lobatto nodes.
   • Transfinite mappings for deformed/curved domains.
   • Essential boundary conditions via System Partitioning (SPS) or Lagrange Multipliers (LMM).
6. russell_nonlin — Continuation methods for parameterized nonlinear systems $G(u, \lambda) = 0$:
   • Predictor-corrector continuation: Natural continuation and Pseudo-arclength continuation (handling folds/limit points).
7. russell_stat — Engineering statistics and extreme value distributions
   • Frechet, Gumbel, Lognormal, Normal, Uniform, quantiles, IQR, ASCII histogram generation.

Below is a summary of internal dependencies:

russell_lab
  ├── russell_stat
  ├── russell_tensor
  ├── russell_sparse
  │     ├── russell_pde
  │     │     └── russell_ode
  │     └── russell_nonlin

External associated and recommended crates

The following crates are not part of russell but are associated with it and recommended:

• 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
• benchmark-russell Performance benchmarks for this project

Features

This project can use SuiteSparse (or MUMPS) for the solution of large (sparse) linear systems of equations. Dense linear algebra comes from russell_lab's own Rust implementation, and OpenBLAS or Intel MKL may be selected as accelerators.

The default build needs no external library. russell_lab ships pure-Rust BLAS/LAPACK kernels and russell_sparse has the Direct solver (pure Rust), so cargo build works on every platform, WebAssembly included. The external libraries are optional, and each one is selected by a Cargo feature:

• open_blas and intel_mkl fill the same slot; intel_mkl takes precedence when both are enabled.
• umfpack and mumps are independent of each other and of the kernels above, and any combination is valid — including none of them.
• MUMPS is never taken from a package manager. The distributions rarely ship the sequential build this project uses, so it is compiled locally and found through RUSSELL_LOCAL_PREFIX; see the per-OS options below.
• On Windows the two Rust toolchains have different sources: MSVC takes UMFPACK from vcpkg, and only the GNU toolchain under MSYS2 can link MUMPS. See windows.md.

An accelerator is worth it for large problems but is never required: the native kernels reach about half of OpenBLAS's throughput per core, and dense solves are further behind because dgetrf is not blocked yet. The russell_lab README has the measured table.

The following table summarizes which features each crate forwards:

Below is an example of how to enable the intel_mkl, umfpack and mumps features with the russell_sparse crate in the Cargo.toml file:

[dependencies]
russell_lab = { version = "*", features = ["intel_mkl"] }
russell_sparse = { version = "*", features = ["intel_mkl", "umfpack", "mumps"] }

Replace "*" with the desired version. Note that russell_sparse (and all other crates in this project) require russell_lab as a dependency.

WebAssembly

The workspace builds for both WebAssembly targets with the default features, i.e. with the Direct solver (pure Rust) and no external libraries:

cargo check --workspace --target wasm32-unknown-unknown
cargo check --workspace --target wasm32-wasip1

The browser target has no filesystem: the Matrix Market readers/writers and the JSON statistics helpers compile, but they return errors when called. WASI exposes the filesystem when the runtime preopens a directory. Timers work in both: wasm32-unknown-unknown uses web-time (performance.now()), while WASI uses the standard library clock. Enabling umfpack or mumps is only possible on native targets.

Installation

Every option below is optional: the default build needs no external library, and the Cargo.toml snippet under each option lists the features that make the build actually use the libraries installed by it. Without those features, the libraries are present but unused, and the build keeps the Rust kernels and the Direct solver (pure Rust).

RUSSELL_LOCAL_PREFIX is the single variable that locates locally compiled solvers. With umfpack it is optional: when set to a directory containing the UMFPACK layout below, that installation is used; otherwise the build falls back to the system library. With mumps it is required. The layout is fixed:

$RUSSELL_LOCAL_PREFIX/include/umfpack     $RUSSELL_LOCAL_PREFIX/lib/umfpack
$RUSSELL_LOCAL_PREFIX/include/mumps       $RUSSELL_LOCAL_PREFIX/lib/mumps

The compilation scripts below install into exactly that layout: the Linux scripts use /usr/local, the macOS script takes the prefix as its argument, and the Windows MUMPS script installs into the MSYS2 root (see windows.md). Two SuiteSparse builds share the libumfpack.so.6 soname, so the directory of the selected one must also be reachable by the dynamic loader at run time (ldconfig on a system prefix, or LD_LIBRARY_PATH); the binaries built inside this workspace carry a run path instead. A prefix that is set but does not contain UMFPACK produces a warning and the system fallback; a missing MUMPS installation stops the build with the expected paths.

Using Intel MKL with russell_lab and OpenBLAS with russell_sparse is possible but not advantageous, since MKL is slightly faster than OpenBLAS (see this article). If MKL is already installed, Option 3 below compiles both SuiteSparse and MUMPS against it; there is no fourth option mixing the two.

Arch Linux

Option 1: OpenBLAS and SuiteSparse from the package manager

Run the following command to install OpenBLAS and SuiteSparse:

pacman -Syu rust blas-openblas suitesparse

Set Cargo.toml as follows, so that the installed libraries are used:

[dependencies]
russell_lab = { version = "*", features = ["open_blas"] }
russell_sparse = { version = "*", features = ["open_blas", "umfpack"] }

open_blas selects the packaged OpenBLAS and umfpack the packaged SuiteSparse. Drop umfpack if you only want the dense accelerator, or both features for the default Rust kernels and the Direct solver (pure Rust).

Option 2: Locally compiled SuiteSparse and MUMPS with OpenBLAS

Run the following commands to compile and install SuiteSparse and MUMPS with OpenBLAS (use these scripts at your own risk; carefully check the scripts before running them):

export RUSSELL_LOCAL_PREFIX=/usr/local   # where both scripts install
bash zscripts/arch-compile-mumps.bash 
bash zscripts/arch-compile-suitesparse.bash 

Set Cargo.toml as follows:

russell_sparse = { version = "*", features = ["open_blas", "umfpack", "mumps"] }

Option 3: Locally compiled SuiteSparse and MUMPS with Intel MKL

Run the following commands to compile and install SuiteSparse and MUMPS with Intel MKL (use these scripts at your own risk; carefully check the scripts before running them):

bash zscripts/arch-install-intel-toolkit.bash
export RUSSELL_LOCAL_PREFIX=/usr/local   # where both scripts install
bash zscripts/arch-compile-mumps.bash 1
bash zscripts/arch-compile-suitesparse.bash 1

Set Cargo.toml as follows:

russell_sparse = { version = "*", features = ["intel_mkl", "umfpack", "mumps"] }

Debian/Ubuntu Linux

Option 1: OpenBLAS and SuiteSparse from the package manager

Run the following command to install OpenBLAS and SuiteSparse:

sudo apt-get install -y --no-install-recommends \
    liblapacke-dev \
    libopenblas-dev \
    libsuitesparse-dev

Set Cargo.toml as follows, so that the installed libraries are used:

[dependencies]
russell_lab = { version = "*", features = ["open_blas"] }
russell_sparse = { version = "*", features = ["open_blas", "umfpack"] }

open_blas selects the packaged OpenBLAS and umfpack the packaged SuiteSparse. Drop umfpack if you only want the dense accelerator, or both features for the default Rust kernels and the Direct solver (pure Rust).

Option 2: Locally compiled SuiteSparse and MUMPS with OpenBLAS

Run the following commands to compile and install SuiteSparse and MUMPS with OpenBLAS (use these scripts at your own risk; carefully check the scripts before running them):

export RUSSELL_LOCAL_PREFIX=/usr/local   # where both scripts install
bash zscripts/debian-compile-mumps.bash 
bash zscripts/debian-compile-suitesparse.bash 

Set Cargo.toml as follows:

russell_sparse = { version = "*", features = ["open_blas", "umfpack", "mumps"] }

Option 3: Locally compiled SuiteSparse and MUMPS with Intel MKL

Run the following commands to compile and install SuiteSparse and MUMPS with Intel MKL (use these scripts at your own risk; carefully check the scripts before running them):

bash zscripts/debian-install-intel-toolkit.bash
export RUSSELL_LOCAL_PREFIX=/usr/local   # where both scripts install
bash zscripts/debian-compile-mumps.bash 1
bash zscripts/debian-compile-suitesparse.bash 1

Set Cargo.toml as follows:

russell_sparse = { version = "*", features = ["intel_mkl", "umfpack", "mumps"] }

Rocky Linux

Option 1: OpenBLAS and SuiteSparse from the package manager

dnf update -y
dnf install epel-release -y
crb enable
dnf install -y \
  lapack-devel \
  openblas-devel \
  suitesparse-devel

Set Cargo.toml as follows, so that the installed libraries are used:

[dependencies]
russell_lab = { version = "*", features = ["open_blas"] }
russell_sparse = { version = "*", features = ["open_blas", "umfpack"] }

The locally compiled options (2 and 3) are not provided for Rocky Linux.

macOS

First, install Homebrew.

Option 1: OpenBLAS and SuiteSparse from the package manager

brew install lapack openblas suite-sparse

Set Cargo.toml as follows, so that the installed libraries are used:

[dependencies]
russell_lab = { version = "*", features = ["open_blas"] }
russell_sparse = { version = "*", features = ["open_blas", "umfpack"] }

Intel MKL is not available for macOS (Intel discontinued it for that platform), so open_blas is the accelerator to use there.

Option 2: Locally compiled MUMPS

MUMPS is not packaged for macOS in the sequential form this project uses, so it is compiled from source with Homebrew's gfortran against Apple's Accelerate framework (use the script at your own risk; carefully check it before running it):

brew install gcc                        # provides gfortran
export RUSSELL_LOCAL_PREFIX="$HOME/local"
bash zscripts/macos-compile-mumps.bash "$RUSSELL_LOCAL_PREFIX"

Set Cargo.toml as follows; UMFPACK still comes from Homebrew, as in Option 1:

russell_sparse = { version = "*", features = ["open_blas", "umfpack", "mumps"] }

The script installs into $RUSSELL_LOCAL_PREFIX/include/mumps and lib/mumps, and rewrites the dylibs' install names to @rpath, which the run path emitted by russell_sparse resolves. Test binaries of crates that only depend on russell_sparse do not get that run path, so export DYLD_LIBRARY_PATH="$RUSSELL_LOCAL_PREFIX/lib/mumps" when testing the whole workspace.

Windows

Two toolchains work on Windows, and the features differ between them:

• MSVC, the default Rust toolchain there. The Direct solver (pure Rust) needs nothing installed; add UMFPACK with vcpkg (vcpkg install suitesparse-umfpack[core]:x64-windows, with VCPKG_ROOT set) and enable umfpack. MUMPS, open_blas and intel_mkl are not available with this toolchain.
• MSYS2 with the GNU toolchain, which provides OpenBLAS, SuiteSparse and the MinGW/gfortran build of MUMPS. It supports open_blas, umfpack and mumps; it is the only way to use MUMPS on Windows.

See windows.md for step-by-step instructions for both.

Number of threads

By default, OpenBLAS will use all available threads, including Hyper-Threads that may worsen the performance. Thus, it is recommended to set the following environment variable:

export OPENBLAS_NUM_THREADS=<real-core-number>

Substitute <real-core-number> with the correct value from your system.

Furthermore, if working on a multi-threaded application where the solver should not be multi-threaded on its own (e.g., running parallel calculations in an optimization tool), you may set:

export OPENBLAS_NUM_THREADS=1

This variable only affects builds that link OpenBLAS (open_blas). The Rust kernels, Intel MKL, and the sparse solvers do not read it; mumps_num_threads, in LinSolParams, controls the MUMPS thread count.

🌟 Examples

See also:

• russell_lab/examples
• russell_nonlin/examples
• russell_ode/examples
• russell_pde/examples
• russell_sparse/examples
• russell_stat/examples
• russell_tensor/examples

(lab) Numerical integration (quadrature)

The code below determines the perimeter P of an ellipse of length 2 and width 1:

     2π
    ⌠   ____________________
P = │ \╱ ¼ sin²(θ) + cos²(θ)  dθ
    ⌡
   0

See the code: algo_quadrature_integrate_1d.rs

(lab) Solution of PDEs using spectral collocation

This example illustrates the solution of a 1D PDE using the spectral collocation method. It employs the InterpLagrange struct.

d²u     du          x
——— - 4 —— + 4 u = e  + C
dx²     dx

    -4 e
C = ——————
    1 + e²

x ∈ [-1, 1]

Boundary conditions:

u(-1) = 0  and  u(1) = 0

Reference solution:

        x   sinh(1)  2x   C
u(x) = e  - ——————— e   + —
            sinh(2)       4

See the code: algo_lorene_1d_pde_spectral_collocation.rs

Results:

(lab) Matrix visualization

We can use the fantastic tool named vismatrix to visualize the pattern of non-zero values of a matrix. With vismatrix, we can click on each circle and investigate the numeric values as well.

The function mat_write_vismatrix writes the input data file for vismatrix.

See the code: matrix_visualization.rs

After generating the "dot-smat" file, run the following command:

vismatrix /tmp/russell_lab/matrix_visualization.smat

Output:

(lab) Singular value decomposition

See the code: matrix_singular_value_decomposition.rs

(lab) Cholesky factorization

See the code: matrix_cholesky_4x4.rs

(lab) Solution of a (dense) linear system

See the code: matvec_solve_linear_system.rs

(lab) Reading table-formatted data files

The goal is to read the following file (clay-data.txt):

# Fujinomori clay test results

     sr        ea        er   # header
1.00000  -6.00000   0.10000   
2.00000   7.00000   0.20000   
3.00000   8.00000   0.20000   # << look at this line

# comments plus new lines are OK

4.00000   9.00000   0.40000   
5.00000  10.00000   0.50000   

# bye

Each column (sr, ea, er) is accessible via the get method of the [HashMap].

See the code: base_read_table.rs

Alternatively, we can use the simpler read_data function:

See the code: base_read_data.rs

(lab) Line search for optimization

Line search is used in gradient-based optimization methods to find an appropriate step size.

See the code: algo_line_search.rs

(nonlin) Numerical continuation of a B-spline curve

This example traces a B-spline curve defined by G(u, λ) = 0 using the Pseudo-arclength continuation method.

The nonlinear problem is defined as follows:

G(u, λ) = u - C(λ)

where C(λ) is a point on a 2D B-spline curve parametrized by λ ∈ [0,1].

See the code: arclength_bspline.rs

The plot looks like this:

(sparse) Solution of a sparse linear system

See the code: doc_umfpack_quickstart_coo.rs

(sparse) Solution of a complex sparse linear system

See the code: doc_complex_umfpack_tiny.rs

(ode) Solution of the Brusselator ODE

The system is:

y0' = 1 - 4 y0 + y0² y1
y1' = 3 y0 - y0² y1

with  y0(x=0) = 3/2  and  y1(x=0) = 3

Solving with DoPri8 -- 8(5,3):

See the code: brusselator_ode_dopri8.rs

A plot of the (dense) solution is shown below:

(ode) Solution of the Brusselator PDE

This example solves the Brusselator PDE described in (Hairer E, Wanner G (2002) Solving Ordinary Differential Equations II Stiff and Differential-Algebraic Problems. Second Revised Edition. Corrected 2nd printing 2002. Springer Series in Computational Mathematics, 614p).

See the code: brusselator_pde_radau5_2nd.rs.

The results are shown below for the U field:

And below for the V field:

See the code: brusselator_pde_2nd_comparison.rs compares russell results with Mathematica results.

The figure below shows the russell (black dashed lines) and Mathematica (red solid lines) results for the U field:

The figure below shows the russell (black dashed lines) and Mathematica (red solid lines) results for the V field:

(pde) Spectral collocation in 2D with transfinite mapping

Example: Solving a 2D Poisson equation on a rotated square domain

This example employs spectral collocation with transfinite mapping to solve the Poisson equation:

  -k · ∇²u = f    on a unit square rotated by angle α
  u = g           on the boundary (Dirichlet conditions)

The analytical solution used for verification is:

  u(x,y) = sin(π·x·cos(α) + π·y·sin(α)) · exp(π·y·cos(α) - π·x·sin(α))

The domain is mapped from the reference square (r,s) ∈ [-1,1]×[-1,1] to the physical rotated square via transfinite interpolation.

See the code: doc_example_spc_map.rs

The plot looks like this:

(stat) Generate the Frechet distribution

See the code: distribution_frechet.rs

Sample output:

min = 0.11845731988882305
max = 26248.036672205748
mean = 12.268212841918867
std_dev = 312.7131690782321

[  0,0.5) | 1370 🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
[0.5,  1) | 2313 🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
[  1,1.5) | 1451 🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
[1.5,  2) |  971 🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦🟦
[  2,2.5) |  659 🟦🟦🟦🟦🟦🟦🟦🟦
[2.5,  3) |  460 🟦🟦🟦🟦🟦
[  3,3.5) |  345 🟦🟦🟦🟦
[3.5,  4) |  244 🟦🟦🟦
[  4,4.5) |  216 🟦🟦
[4.5,  5) |  184 🟦🟦
[  5,5.5) |  133 🟦
[5.5,  6) |  130 🟦
[  6,6.5) |  115 🟦
[6.5,  7) |  108 🟦
[  7,7.5) |   70 
[7.5,  8) |   75 
[  8,8.5) |   57 
[8.5,  9) |   48 
[  9,9.5) |   59 
      sum = 9008

(tensor) Allocate second-order tensors

See the code: allocating_second_order_tensors.rs

Roadmap

• [ ] Improve russell_lab
  • [x] Implement more integration tests for linear algebra
  • [x] Implement more examples
  • [ ] Implement more performance benchmarks
  • [x] Wrap more BLAS/LAPACK functions
    • [x] Implement dggev, zggev, zheev, and zgeev
  • [x] Wrap Intel MKL (alternative to OpenBLAS)
  • [x] Add more complex number functions
  • [x] Add fundamental functions to russell_lab
    • [x] Implement the Bessel functions
    • [x] Implement the modified Bessel functions
    • [x] Implement the elliptical integral functions
    • [x] Implement Beta, Gamma and Erf functions (and associated)
    • [x] Implement orthogonal polynomial functions
  • [ ] Implement some numerical methods in russell_lab
    • [x] Implement Brent's solver
    • [x] Implement a solver for the cubic equation
    • [x] Implement numerical derivation
    • [x] Implement numerical Jacobian function
    • [x] Implement line search
    • [x] Implement Newton's method for nonlinear systems
    • [x] Implement numerical quadrature
    • [ ] Implement multidimensional data interpolation
  • [ ] Add interpolation and polynomials to russell_lab
    • [x] Implement Chebyshev polynomials
    • [x] Implement Chebyshev interpolation
    • [x] Implement Orthogonal polynomials
    • [x] Implement Lagrange interpolation
    • [x] Implement Legendre polynomials
    • [ ] Implement Fourier interpolation
• [x] Improve russell_sparse
  • [x] Implement support for complex numbers
  • [x] Implement the Compressed Sparse Column format (CSC)
  • [x] Implement the Compressed Sparse Row format (CSR)
  • [x] Improve the C-interface to UMFPACK and MUMPS
  • [x] Write the conversion from COO to CSC in Rust
• [x] Improve russell_ode
  • [x] Implement explicit Runge-Kutta solvers
  • [x] Implement Radau5 for DAEs
  • [ ] Implement extrapolation methods
  • [ ] Implement multi-step methods
  • [ ] Implement general linear methods
• [x] Implement russell_pde
  • [x] Implement 1D and 2D spectral collocation methods
  • [x] Implement 1D and 2D finite difference methods
• [x] Implement russell_nonlin
  • [x] Implement natural continuation for nonlinear systems
  • [x] Implement pseudo-arclength continuation for nonlinear systems
  • [x] Study better methods for step size control in continuation methods
• [ ] Improve russell_stat
  • [x] Add probability distribution functions
  • [x] Implement drawing of ASCII histograms
  • [ ] Implement FORM (first-order reliability method)
  • [ ] Add more examples
• [ ] Improve russell_tensor
  • [x] Implement functions to calculate invariants
  • [x] Implement first and second-order derivatives of invariants
  • [x] Implement some high-order derivatives
  • [ ] Implement standard continuum mechanics tensors
• [ ] General improvements
  • [x] Compile on Linux (Arch, Debian/Ubuntu, Rocky)
  • [x] Compile on macOS
  • [x] Compile on Windows
  • [x] Study the compilation of MUMPS on Windows
  • [x] Write scripts to compile on Windows

For developers

This section summarizes the build.rs files, which compile and link the non-Rust C dependencies at build time.

Naming conventions

The code adopts the convention that double lower-case letters denote a single capital letter, matching the symbols used in the documentation and the mathematical formulas:

• aa ⇔ A
• bb ⇔ B
• pp ⇔ P
• ii ⇔ I
• jj ⇔ J

For example, the scalar coefficients A, B, and C in the second-derivative formulas of the invariants are coded as aa, bb, and cc.

russell_lab — BLAS/LAPACK

With neither accelerator feature enabled, russell_lab/build.rs compiles no C code: the kernels come from algebra_linear. When open_blas or intel_mkl is enabled, it compiles a single C shim (c_code/interface_blas.c) that wraps BLAS/LAPACK and selects one of two paths:

• intel_mkl — builds against Intel oneAPI MKL: resolves MKL_VERSION (env var, default latest), adds /opt/intel/oneapi/mkl/{version} to the include path, defines USE_INTEL_MKL, and links mkl_intel_lp64, mkl_intel_thread, mkl_core, pthread, m, dl, iomp5.
• open_blas (used only when intel_mkl is off) — split by OS:
  • Windows: locates headers/libraries via the MSYS2_PREFIX environment variable.
  • Other OS: probes pkg-config (probe_blas_lapack), trying openblas first and then the cblas + lapack pair (Nix). Before trusting a probe, it verifies the headers (cblas.h, lapack.h) actually exist — this avoids the RHEL/Rocky case where lapack.pc exists but ships no lapack.h. It falls back to hardcoded Homebrew/system paths (filtered via existing_dirs to drop non-existent directories) and links the openblas and lapack shared libraries.

Build-dependencies: cc, pkg-config.

russell_sparse — sparse solvers

russell_sparse/build.rs compiles the C shims for the sparse solvers. UMFPACK is optional and off by default (umfpack); MUMPS joins it when mumps is enabled. The features select which solvers are present, and the build selects the UMFPACK source:

• umfpack on: a local install under $RUSSELL_LOCAL_PREFIX/include/umfpack and .../lib/umfpack is used when RUSSELL_LOCAL_PREFIX is set and contains it, with no pkg-config lookup in that case; otherwise the build falls back to the package-manager library (pkg-config, trying both UMFPACK and umfpack spellings, then the built-in directory list). If neither answers, the build stops naming the package to install. A prefix that is set but incomplete prints a warning and falls back.
• umfpack off: no UMFPACK shims are compiled and nothing is linked; the Direct solver (pure Rust) remains available.
• mumps on: MUMPS from $RUSSELL_LOCAL_PREFIX/include/mumps and .../lib/mumps, independently of UMFPACK, shared on Unix and static on Windows (dmumps_cpmech, zmumps_cpmech, mumps_common_cpmech, mpiseq_cpmech, pord_cpmech, metis, gfortran, gomp). A missing prefix fails the build naming the exact path it expected.
• RUSSELL_LOCAL_PREFIX is trimmed of trailing separators.
• The selected UMFPACK is recorded with cargo:rustc-env, so get_library_versions() reports whether it is the system or the local one, or that it was not compiled in.

Build-dependencies: cc, pkg-config.

About the name

The library is named after Bertrand Russell (1872–1970), a distinguished British philosopher, logician, mathematician, and pacifist. Among his many influential works is Principia Mathematica (1910–1913), co-authored with Alfred North Whitehead—an ambitious attempt to derive mathematics from logic and widely regarded as one of the twentieth century's most important contributions to mathematical logic. The book cover shown features Introduction to Mathematical Philosophy, in which Russell explains the principal ideas of Principia Mathematica in a more accessible, less technical manner.

The photo of the stamp corresponds to India's commemorative postage stamp issued on 16 October 1972 for the birth centenary of Bertrand Russell, as part of the "Centenary Series" introduced that year by the Indian Posts and Telegraphs Department to mark the centenaries falling during the year (issue note). Four personalities were honored on that date — the Telugu poet Vemana (300th birth anniversary), T. Prakasam and Bhai Vir Singh (birth centenaries), and Russell (₹1.45) — and all four stamps were released together on a single first day cover (list of Indian stamps of 1972). India's reason for including a British philosopher was political as much as intellectual: Russell became chairman of the India League in Britain in 1932, presiding over its meetings and heading it during the delegation it sent to India that autumn, and he wrote the introduction to the delegation's report, The Condition of India (1932) (South Asian Britain). The department's own issue note puts it plainly: "Temperamentally sympathetic to the Indian struggle for liberty, Russell became Chairman of the Indian League formed in Britain to help the Indians and their claim for self-government." The stamp reproduces a photograph supplied with the courtesy of M/s Keystone Press Agency Ltd., London, and was designed and printed by photogravure at the India Security Press, Nasik Road, in a print run of three million (42 stamps per issue sheet, perforation 13½ × 14) (technical data). The portrait is accompanied by the dates 1872–1970 and the legend बर्ट्रेंड रसल / भारत INDIA. The author of this Rust project is a proud owner of the stamp featured in the photo.