Tensor — arbitrary-rank tensor

Overview

Tensor<T> is sangi's arbitrary-rank, arbitrary-shape dynamic tensor class. It unifies the treatment of matrices, vectors, and higher-dimensional arrays, and is used for multi-dimensional array representation in machine learning and physical simulation. Header-only; no library linking required.

• Dynamic rank and shape — any number of dimensions specified at runtime, e.g. Tensor<T>({3, 4, 5})
• Stride-based views — transpose and reshape return views without copying data
• shared_ptr storage — multiple tensors can safely share the underlying buffer; writes through views trigger an independent copy when necessary (copy-on-write style)
• Matrix / Vector interop — rank-2 ↔ Matrix<T>, rank-1 ↔ Vector<T>, rank-0 ↔ scalar
• C++23 concepts — element type constrained by TensorScalar

For the mathematical background, see Tensors (Linear Algebra, intermediate) / Matrix and tensor calculus.

Header

#include <math/core/Tensor.hpp>

Header-only. All names live in namespace sangi.

TensorScalar concept

The element type T of Tensor<T> must satisfy:

template<typename T>
concept TensorScalar = requires(T a, T b) {
    { a + b } -> std::convertible_to<T>;
    { a - b } -> std::convertible_to<T>;
    { a * b } -> std::convertible_to<T>;
    { -a }    -> std::convertible_to<T>;
    { T(0) };
};

That is, types that support addition, subtraction, multiplication, unary minus, and zero initialization. Built-in float, double, std::complex<T> satisfy this, as do sangi's arbitrary-precision types Int, Float, Rational, Complex.

Tensor<T> class

template<TensorScalar T>
class Tensor;

Constructors

Tensor<double> t0;                       // rank-0 scalar (value 0)
Tensor<double> t1({3, 4, 5});            // rank-3, zero-initialized (60 entries)
Tensor<double> t2({2, 3}, 1.0);          // rank-2, all entries 1.0
Tensor<double> t3({2, 3}, {1,2,3,4,5,6}); // from flat data (row-major)
Tensor<double> s(3.14);                  // rank-0 scalar

Element access

Tensor<double> t({2, 3}, {1,2,3,4,5,6});
double x = t(1, 2);                       // 6 (row 1, col 2)
double y = t.at({0, 1});                  // 2 (bounds-checked)
double z = t.flat(3);                     // 4 (flat index)
double* p = t.data();                     // raw pointer

Properties

Mutation

Shape operations

Tensor<double> t({2, 3, 4});
auto r  = t.reshape({6, 4});             // view (shared storage)
auto tT = t.transpose({2, 1, 0});        // axis (0,1,2) → (2,1,0), view
auto m  = t.transpose();                 // reverse all axes (rank-3 → {2,1,0})
auto c  = tT.contiguous();               // physically row-major independent copy

Arithmetic (compound assignment)

Matrix / Vector / scalar conversion

Output

A non-member operator<< is provided as well (it calls to_string()).

Free functions

Arithmetic operators

Tensor operations

// Hadamard product (element-wise)
Tensor<double> a({2,3}, {1,2,3,4,5,6});
Tensor<double> b({2,3}, {6,5,4,3,2,1});
auto h = hadamard(a, b);   // shape = {2,3}, data = {6, 10, 12, 12, 10, 6}

// Matrix product (rank-2 x rank-2, contract axis 1 of a with axis 0 of b)
Tensor<double> M({3,4}, 1.0);
Tensor<double> N({4,5}, 2.0);
auto C = contract(M, N, {{1, 0}});   // shape = {3, 5}, every entry = 8 (= 4×1×2)

// Outer product (rank-1 x rank-1 = rank-2)
Tensor<double> u({3}, {1,2,3});
Tensor<double> v({2}, {10,20});
auto K = outerProduct(u, v);   // shape = {3,2}, data = {10,20,20,40,30,60}
                               // = {{10,20},{20,40},{30,60}}
// Run output (build & run verified):
//   h shape=[2,3] data=[6,10,12,12,10,6]
//   C shape=[3,5] data=[8,8,8,8,8, 8,8,8,8,8, 8,8,8,8,8]
//   K shape=[3,2] data=[10,20,20,40,30,60]

Factory functions

Provided in namespace sangi::tensor.

Type traits

template<typename T> struct is_tensor;
template<typename T> inline constexpr bool is_tensor_v = is_tensor<T>::value;

is_tensor_v<X> is true when X is an instance of Tensor<T>. Useful for SFINAE / concept dispatch.

Example

#include <math/core/Tensor.hpp>
using namespace sangi;

int main() {
    // Build a rank-3 tensor and take a reshape view
    Tensor<double> t({2, 3, 4}, 1.0);
    auto t_flat = t.reshape({24});           // view
    t_flat(0) = 42.0;                        // t(0,0,0) is now 42.0 (shared storage)

    // Axis permutation (transpose) is a view; contiguous() copies
    auto t_perm = t.transpose({2, 0, 1});    // shape {4,2,3}, no copy
    auto t_copy = t_perm.contiguous();       // physically row-major independent copy

    // Hadamard product
    Tensor<double> a({2,2}, {1,2,3,4});
    Tensor<double> b({2,2}, {5,6,7,8});
    auto c = hadamard(a, b);                 // {5, 12, 21, 32}

    // Contraction (used as matrix product)
    Tensor<double> X({3, 4}, 1.0);
    Tensor<double> Y({4, 5}, 2.0);
    auto Z = contract(X, Y, {{1, 0}});       // shape {3,5}, each entry 8.0

    // Matrix / Vector interop
    Matrix<double> M(3, 3, 1.0);
    Tensor<double> tM(M);                    // to rank-2 tensor
    Matrix<double> M2 = tM.toMatrix();       // back to Matrix
    // Run output (build & run verified):
    //   t_perm  rank=3, shape={4,2,3}, isContiguous=false
    //   c       shape=[2,2], data=[5,12,21,32]
    //   Z       shape=[3,5], every entry 8.0
    //   tM.rank=2, size=9; M2(0,0)=1, M2(2,2)=1
}

See also: Matrix / Vector / FFT (Tensor3D) / Matrix arithmetic — Hadamard product.