Crate russell_tensor

Expand description

Russell - Rust Scientific Library

russell_tensor: Tensor analysis, calculus, and functions for continuum mechanics

Important: This crate depends on external libraries (non-Rust). Thus, please check the Installation Instructions on the GitHub Repository.

§Introduction

This library implements structures and functions for tensor analysis and calculus, with focus on applications in engineering and Continuum Mechanics. The essential functionality for the targeted applications includes first-order, second-order, third-order, and fourth-order tensors, scalar “invariants,” and derivatives.

§Capabilities

Tensor1 — First-order tensors (vectors) in R³. Includes operations such as the dot and cross products
Tensor2 — Second-order tensors in R³×R³. Allows symmetric specialization. Includes functions such as the determinant, inverse, norm, and invariants (principal, deviatoric, Lode, octahedral, …)
Tensor3 — Third-order tensors R³×R³×R³. Allows minor-symmetric specialization. Includes functions such as permutation (Levi-Civita) tensor
Tensor4 — Fourth-order tensors R³×R³×R³×R³. Allows minor-symmetric specialization. Includes functions to generate isotropic tensors.
EigenValuesT2, EigenProjsT2, EigenProjDerivsT2 — Eigenvalues, eigenprojectors, and the derivatives of the eigenprojectors for symmetric second-order tensors.
LinElasticity — The linear elasticity equations for small-strain problems (Generalized Hooke’s law)
analysis::PiezoDatabase — A database of piezoelectric materials (dielectric permittivity, piezoelectric, and stiffness tensors) loaded from JSON.
Polar decomposition — Computes the polar decomposition F = R U = V R of a general Tensor2 using the classic Eigen/SVD algorithms, the iterative Brannon algorithm, or the quaternion-based Higham & Noferini algorithm (see PolarAlgo and polar_decomp_mx).
Constants — Includes identity, transposition, and projector tensors, as well as the ADD/SET operation selectors.
Operations between tensors — Includes addition, single and double contractions (dot and ddot), and dyadic products. Most operations support both overwriting (SET) and accumulation (ADD) semantics.
Derivatives — Implements first and second derivatives of invariants and tensor functions (e.g., the inverse and squared tensors)
Display — The tensors implement the Display trait (with configurable precision) and provide a scientific method returning a scientific-notation string for printing or logging.

§Kelvin-Mandel notation

Internally, tensors are stored in the Kelvin-Mandel basis (Kelvin-Mandel notation).

In the Kelvin-Mandel basis, a second-order tensor is mapped to a column matrix (vector), a third-order tensor is mapped to a rectangular matrix, and a fourth-order tensor is mapped to a square matrix. The √2 factors make the mapping isometric; thus the tensor norm is preserved and standard matrix/vector operations can be used directly.

The dimension — the const generic N of Tensor2/Tensor4, and M/N of Tensor3 — selects the representation:

9 — all components (general): 9×1 / 9×3 / 3×9 / 9×9
6 — symmetric Tensor2 / minor-symmetric Tensor3/Tensor4: 6×1 / 6×3 / 3×6 / 6×6
4 — symmetric Tensor2 / minor-symmetric Tensor3/Tensor4 (generalized plane): 4×1 / 4×3 / 3×4 / 4×4

The dimensions above correspond to Tensor2 (vector), Tensor3 (Case A / Case B rectangular matrix), and Tensor4 (square matrix), respectively.

§Reduced dimension and truncation (chop) strategy

The N = 4 case is the four-dimensional subspace {00, 11, 22, 01} of symmetric tensors—the out-of-plane normal component T₂₂ is kept, while only the out-of-plane shears are set to zero (T₁₂ = T₀₂ = 0, Kelvin-Mandel components 4 and 5).

The tensor operators considered here (e.g., ssd_fn, qsd_fn, and the second derivatives of the invariants) are polynomial in the components, and for an input in this subspace they are block diagonal with respect to the {0,1,2,3} and {4,5} partitions: every off-diagonal block is proportional to the (zero) out-of-plane shears. Consequently, restricting both the input and the output to N components is exact — not an approximation: the reduced N × N operator is precisely the corresponding block of the full 6 × 6 operator.

A Tensor3 is stored as a rectangular Kelvin-Mandel matrix with dimensions (M, N) set by const generics. Two cases are considered, where DIM (the leading dimension) is one of 4, 6, or 9:

Case A (DIM, 3) — M = DIM, N = 3: the Tensor3 acts on a Tensor1 (vector) yielding a Tensor2 (T = H · u)
Case B (3, DIM) — M = 3, N = DIM: the Tensor3 acts on a Tensor2 yielding a Tensor1 (vector) (v = M : S)

§Standard vs Kelvin-Mandel components

The tensor accessors follow a naming convention that distinguishes the standard (Cartesian) components Tᵢⱼ / Hᵢⱼₖ / Dᵢⱼₖₗ from the Kelvin-Mandel components stored internally:

Accessors dealing with standard components carry the std qualifier in their names:
Accessors dealing directly with the Kelvin-Mandel components carry no qualifier:
- Tensor2 — Tensor2::get, Tensor2::set, Tensor2::set_vector, Tensor2::set_tensor, Tensor2::update, Tensor2::clear
- Tensor3 — Tensor3::get, Tensor3::set, Tensor3::set_tensor, Tensor3::update
- Tensor4 — Tensor4::get, Tensor4::set, Tensor4::set_tensor, Tensor4::update

Note: Tensor1 stores the three standard components directly (there is no Kelvin-Mandel mapping for first-order tensors); access them with Tensor1::get and Tensor1::set.

§Optional features

The following (Rust) features are available:

intel_mkl — use Intel MKL instead of OpenBLAS

§Examples

use russell_tensor::*;

fn main() -> Result<(), StrError> {
    // Allocate a symmetric second-order tensor given the standard components
    let a = Tensor2::<6>::from_std_matrix(&[
        [1.0, 2.0, 3.0],
        [2.0, 2.0, 4.0],
        [3.0, 4.0, 3.0],
    ])?;

    // Compute the principal invariants
    let ii1 = a.invariant_ii1();
    let ii2 = a.invariant_ii2();
    let ii3 = a.invariant_ii3();

    println!("I1 = {:.6}", ii1);
    println!("I2 = {:.6}", ii2);
    println!("I3 = {:.6}", ii3);
    Ok(())
}

Modules§

analysis: This module contains auxiliary analysis tools
z_reference_loop_fns: Loop-based reference implementations of the tensor operations used by the benchmarks. These are simple, obviously-correct implementations (using the M_TO_IJ / MN_TO_IJKL index mappings) that are used in tests to cross-check the optimized (unrolled) production implementations.

Structs§

EigenProjDerivsT2: Assists in calculating the derivatives of the eigenprojectors
EigenProjsT2: Assists in calculating the eigenprojectors of a symmetric second-order tensor
EigenValuesT2: Assists in calculating the eigenvalues of a symmetric second-order tensor
LinElasticity: Implements the linear elasticity equations for small-strain problems
SampleTensor2: Collects values related to a sample Tensor2
SamplesTensor2: Holds second-order tensor samples
SamplesTensor3: Holds third-order tensor samples
SamplesTensor4: Holds fourth-order tensor samples
Tensor1: Defines a first-order tensor (vector) in R³
Tensor2: Defines a second-order tensor in R³×R³
Tensor3: Defines a third-order tensor in R³×R³×R³
Tensor4: Defines a fourth-order tensor in R³×R³×R³×R³
WorkspaceDeriv2Lode: Sets a workspace with temporary variables to calculate the second derivative of the Lode angle

Enums§

EigenValMethod: Defines the method to calculate the eigenvalues
PolarAlgo: Specifies the polar decomposition algorithm

Constants§

ADD: Identifies an operation as an addition (update)
IDENTITY2: Second-order identity tensor in Kelvin-Mandel basis (I)
IDENTITY4: Fourth-order identity tensor in Kelvin-Mandel basis (II)
IJKL_TO_MN: Maps (i,j,k,l) of Tensor4 to the (m,n)-th position in the matrix representation
IJKL_TO_MN_SYM: Maps (i,j,k,l) of Tensor4 to the (m,n)-th position in the matrix representation (minor-symmetric version)
IJK_TO_MN_CASE_A: Maps (i,j,k) of Tensor3 to the (m,n)-th position in the matrix representation (Case A)
IJK_TO_MN_CASE_B: Maps (i,j,k) of Tensor3 to the (m,n)-th position in the matrix representation (Case B)
IJK_TO_MN_SYM_CASE_A: Maps (i,j,k) of Tensor3 to the (m,n)-th position in the matrix representation (minor-symmetric; Case A)
IJK_TO_MN_SYM_CASE_B: Maps (i,j,k) of Tensor3 to the (m,n)-th position in the matrix representation (minor-symmetric; Case B)
IJ_TO_M: Maps (i,j) of Tensor2 to the m-th position in the vector representation
IJ_TO_M_SYM: Maps (i,j) of Tensor2 to the m-th position in the vector representation (symmetric version)
MN_TO_IJKL: Maps the (m,n)-th position in the matrix representation to (i,j,k,l) of Tensor4
MN_TO_IJK_CASE_A: Maps the (m,n)-th position in the matrix representation to (i,j,k) of Tensor3 (Case A)
MN_TO_IJK_CASE_B: Maps the (m,n)-th position in the matrix representation to (i,j,k) of Tensor3 (Case B)
M_TO_IJ: Maps the m-th position in the vector representation to the index (i,j) of Tensor2
OK_EIGENPROJ_RULES: Indicates that a set of three Tensor2 satisfy the eigenprojectors rules
ONE_BY_3: 1/3
P_DEV: Fourth-order deviatoric making projector (Pdev)
P_ISO: Fourth-order isotropic making projector (Piso)
P_SKEW: Fourth-order skew making projector (Pskew)
P_SYM: Fourth-order symmetric making projector (Psym)
P_SYMDEV: Fourth-order symmetric-deviatoric projector in Kelvin-Mandel basis
SET: Identifies an operation as a setting
SQRT_2: sqrt(2) https://oeis.org/A002193
SQRT_3: sqrt(3) https://oeis.org/A002194
SQRT_6: sqrt(6) https://oeis.org/A010464
SQRT_2_BY_3: sqrt(2/3) https://oeis.org/A157697
SQRT_3_BY_2: sqrt(3/2) https://oeis.org/A115754
TOL_J2: Tolerance to avoid zero division with the J2 invariant
TRACE_PROJECTION: Fourth-order trace-projection tensor (JJ)
TRANSPOSITION: Fourth-order transposition tensor in Kelvin-Mandel basis (TT)
TWO_BY_3: 2/3

Functions§

deriv1_invariant_d: Calculates the first derivative of d w.r.t. the symmetric tensor
deriv1_invariant_ii2: Calculates the first derivative of the I2 invariant w.r.t. its defining tensor
deriv1_invariant_ii3: Calculates the first derivative of the I3 invariant w.r.t. its defining tensor
deriv1_invariant_jj2: Calculates the first derivative of the J2 invariant w.r.t. the symmetric tensor
deriv1_invariant_jj3: Calculates the first derivative of the J3 invariant w.r.t. the symmetric tensor
deriv1_invariant_lode: Calculates the first derivative of the Lode invariant w.r.t. the symmetric tensor
deriv1_invariant_p: Calculates the first derivative of p w.r.t. the symmetric tensor
deriv1_invariant_q: Calculates the first derivative of q (von Mises) w.r.t. the symmetric tensor
deriv1_invariant_r: Calculates the first derivative of r w.r.t. the symmetric tensor
deriv1_norm: Calculates the first derivative of the norm w.r.t. the defining Tensor2
deriv2_invariant_ii2: Calculates the second derivative of the I2 invariant w.r.t. its defining tensor
deriv2_invariant_ii3: Calculates the second derivative of the I3 invariant w.r.t. its defining tensor
deriv2_invariant_jj2: Calculates the second derivative of the J2 invariant w.r.t. the symmetric tensor
deriv2_invariant_jj3: Calculates the second derivative of the J3 invariant w.r.t. the symmetric tensor
deriv2_invariant_lode: Calculates the second derivative of the Lode invariant w.r.t. the symmetric tensor
deriv2_invariant_q: Calculates the second derivative of the deviatoric invariant (von Mises) w.r.t. the symmetric tensor
deriv2_invariant_r: Calculates the second derivative of r w.r.t. the symmetric tensor
deriv_inverse_tensor: Calculates the derivative of the inverse tensor w.r.t. the defining Tensor2
deriv_inverse_tensor_sym: Calculates the derivative of the inverse tensor w.r.t. a symmetric Tensor2
deriv_squared_tensor: Calculates the derivative of the squared tensor w.r.t. a Tensor2
deriv_squared_tensor_sym: Calculates the derivative of the squared tensor w.r.t. a symmetric Tensor2
dsd_fn: Performs the duo-sum-dyadic (dsd) operation with two Tensor2 yielding a minor-symmetric Tensor4
eigen_octahedral: Rotates the eigenvalues to the principal values space
eigenprojector_rules: Checks the properties (rules) of a set of candidate eigenprojectors
polar_decomp: Performs the polar decomposition F = R U = V R (using the default method)
polar_decomp_mx: Performs the polar decomposition F = R U = V R (selectable method version)
qsd_fn: Performs the quad-sum-dyadic (qsd) operation with two Tensor2 yielding a minor-symmetric Tensor4
ssd_fn: Performs the self-sum-dyadic (ssd) operation with a Tensor2 yielding a minor-symmetric Tensor4
t1_dot_t2: Performs the single dot operation between a vector and a Tensor2
t1_dot_t3: Performs the single-dot operation between a Tensor3 and a vector resulting in a Tensor2 (Case B)
t1_dyad_t1: Performs the dyadic product between two vectors resulting in a second-order tensor
t2_add: Adds two second-order tensors
t2_ddot_t2: Performs the double-dot (ddot) operation between two Tensor2 (inner product)
t2_ddot_t3: Performs the double-dot operation between a Tensor2 and a Tensor3 resulting in a Tensor1 (Case A)
t2_ddot_t4: Performs the double-dot (ddot) operation between a Tensor2 and a Tensor4
t2_ddot_t4_ddot_t2: Computes Tensor2 double-dot Tensor4 double-dot Tensor2
t2_dot_t1: Performs the single dot operation between a Tensor2 and a vector
t2_dyad_t2: Performs the dyadic product between two Tensor2 resulting a Tensor4
t2_matmul: Performs the matrix multiplication between two Tensor2
t2_matmulx: Performs a triple matrix multiplication: C = α A · B · Aᵀ or C = α Aᵀ · B · A
t2_odyad_t2: Performs the overbar dyadic product between two Tensor2 resulting in a (general) Tensor4
t2_udyad_t2: Performs the underbar dyadic product between two Tensor2 resulting in a (general) Tensor4
t3_add: Adds two third-order tensors
t3_ddot_t2: Performs the double-dot operation between a Tensor3 and a Tensor2 resulting in a vector (Case B)
t3_dot_t1: Performs the single-dot operation between a Tensor3 and a Tensor1 resulting in a Tensor2 (Case A)
t4_add: Adds two fourth-order tensors
t4_ddot_t2: Performs the double-dot (ddot) operation between a Tensor4 and a Tensor2
t4_ddot_t4: Performs the double-dot (ddot) operation between two Tensor4
t4_ddot_t2_dyad_t2_ddot_t4: Computes Tensor4 double-dot Tensor2 dyadic Tensor2 double-dot Tensor4

Type Aliases§

StrError: Defines the error type as a static string