mdtensor — Modern C++ Tensor Library with Numpy-like Syntax

Overview

mdtensor is a header-only C++ library providing multi-dimensional tensor operations with NumPy-like broadcasting semantics.

It is built on modern C++ standard facilities including:

• C++23 std::mdspan.
• Upcoming C++26 std::mdarray and std::submdspan.

Try it on Godbolt:

• Matrix Addition example.
• Zero-cost Abstraction test.

Key Features

• NumPy-like Syntax: Familiar tensor programming model inspired by NumPy.
• Flexibility: Supports diverse data types compatible with std::mdspan.
• Zero-Cost Abstraction: Broadcasting and tensor operations are implemented with minimal runtime overhead.
• Compile-Time Computation Support: Most operations are usable in constexpr contexts.
• Optional High-Performance Backends: Eigen and OpenMP acceleration available when enabled.
• Header-only & Lightweight: No build system required — just include the headers.

Important Notes

• C++ Version Compatibility:

  • mdtensor requires at least C++20 for full functionality.
  • std::mdspan (C++23), std::mdarray (C++26), std::submdspan (C++26) are sourced from the Reference mdspan implementation.

• Data conventions:

  • Arguments:

    • Scalar: 0D mdspan or arithmetic type (e.g., int, float, double).
    • Vector: 1D mdspan or 1D mdarray.
    • Matrix: 2D mdspan or 2D mdarray.
    • Tensor: ND mdspan or ND mdarray.

  • Return Values:

    • Scalar: arithmetic type (e.g., int, float, double).
    • Vector: 1D mdarray.
    • Matrix: 2D mdarray.
    • Tensor: ND mdarray.

• Acceleration:

  • Using Eigen: define the macro MDTENSOR_USE_EIGEN.
  • Using OpenMP: compile with -fopenmp and link with -lgomp.

Available Functions

• Array creation routines: empty, empty_like, eye, ones, ones_like, zeros, zeros_like, full, full_like, copy, arange, linspace.
• Array manipulation routines: reshape, expand_dims, concatenate.
• Linear algebra: matmul, matvec, vecmat, norm, inv.
• Logic functions: all, any, allclose, isclose, array_equal, array_equiv, greater, greater_equal, less, less_equal, equal, not_equal.
• Mathematical functions: sin, cos, tan, atan2, deg2rad, rad2deg, sum, add, negative, multiply, divide, subtract, maximum, max, minimum, min, clip, sqrt, absolute, sign.
• Random sampling: rand, uniform.

Installation

mdtensor is a header-only library, so you can start using it by simply including:

#include "mdtensor/mdtensor.hpp"

Examples

Matrix Addition with Broadcasting

Code:

#include "mdtensor/mdtensor.hpp"

namespace md = mdtensor;

constexpr auto a = md::full<int, md::extents<size_t, 3, 1, 2>>(1);
constexpr auto b = md::full<int, md::extents<size_t, 2, 1>>(2);
constexpr auto c = md::add(a, b);

constexpr auto c_expect = md::full<int, md::extents<size_t, 3, 2, 2>>(3);

constexpr bool is_allclose = md::allclose(c, c_expect);

std::cout << "a extents: " << md::to_string(a.extents()) << std::endl;
std::cout << "a: " << md::to_string(a) << std::endl << std::endl;

std::cout << "b extents: " << md::to_string(b.extents()) << std::endl;
std::cout << "b: " << md::to_string(b) << std::endl << std::endl;

std::cout << "c extents: " << md::to_string(c.extents()) << std::endl;
std::cout << "c: " << md::to_string(c) << std::endl;

static_assert(is_allclose);

Output:

a extents: (3, 1, 2)
a: [[[1, 1]], [[1, 1]], [[1, 1]]]

b extents: (2, 1)
b: [[2], [2]]

c extents: (3, 2, 2)
c: [[[3, 3], [3, 3]], [[3, 3], [3, 3]], [[3, 3], [3, 3]]]

Tests and Benchmarks

mdtensor uses GoogleTest for unit tests:

bazel test tests/...

Benchmarks use GoogleBenchmark. For example:

bazel run benchmarks/add/none:ps

About

This project includes derivative works based on:

• CTMD (Compile-Time Multi-Dimensional) library v0.16.1
• Copyright (c) 2025 Uon Robotics, South Korea
• Licensed under the Apache License 2.0.

CTMD was originally developed at Uon Robotics by Chan-Soon Lim, and later modified and extended as part of the mdtensor project. All original rights to CTMD remain with Uon Robotics, while modifications and extensions in mdtensor are maintained by Chan-Soon Lim.

Contributing

mdtensor is in active development, and contributions are welcome! Feel free to open issues or pull requests — whether for bug reports, feature ideas, or improvements.

License

mdtensor is licensed under the Apache 2.0 License. See the LICENSE file for full details.