English | 한국어

mdtensor — A Modern C++ Tensor Library with a NumPy-like Interface

mdtensor is a header-only Modern C++ tensor computation library built around non-owning views based on C++23's std::mdspan and owning containers based on kokkos::mdarray. It aims to provide an interface similar to NumPy while actively leveraging Modern C++ features to maximize compile-time evaluation and optimize runtime performance.

mdtensor is under active development. Both the internal framework and the public APIs may change substantially. At this stage, please consider it an experimental repository for high-performance tensor computation with std::mdspan, rather than a production-ready library.

---

Why Build Another Numerical Computing Library?

NumPy has evolved around vectorized operations and broadcasting to reduce the overhead of Python-level loops and function calls. Expressing multidimensional computations as array operations moves loops into the library and makes memory access patterns more predictable, making it easier to achieve high performance on modern CPUs. In contrast, function-call overhead is comparatively low in C++, and matrix-oriented libraries such as Eigen have long been widely used in production. As a result, demand for a general-purpose, NumPy-style N-dimensional tensor library has historically been lower.

C++23's std::mdspan is an important step toward representing multidimensional views in a standardized way in C++. std::linalg is also expected to be introduced in C++26. Although the rank of a std::mdspan must be known at compile time, it is designed as a zero-overhead abstraction and is therefore well suited to expressing multidimensional computations efficiently in C++.

While researching robotics algorithms, the author has spent many years porting algorithms written in Python to C++ or C to accelerate them on PCs and MCUs. Python provides several acceleration tools, including PyPy and Numba, but performance and deployment constraints often make it necessary to reimplement algorithms in C++ and repeatedly verify that their results match the Python implementation. Applying SIMD and CPU/GPU parallelism then requires additional, separate optimization work.

Research on executing high-performance algorithms on microsecond timescales through SIMD-based computation has also become increasingly active. For example, Motions in Microseconds via Vectorized Sampling-Based Planning demonstrates how vectorized computation can improve the performance of robotics algorithms. mdtensor targets precisely this area: implementing NumPy-like multidimensional broadcasting operations in C++ as efficiently as possible.

Because std::mdspan is relatively new, established libraries may find it difficult to adopt it quickly while preserving backward compatibility. Initial tests also indicate that algorithms built on std::mdspan can be optimized aggressively by compilers when combined with loop unrolling. mdtensor is being developed to apply this potential first to robotics software, where real-time computational performance is critical. More mathematical libraries are expected to emerge around the capabilities of std::mdspan; accordingly, mdtensor's implementations of fundamental NumPy-equivalent functionality are released under the Apache License 2.0.

mdtensor provides the following features:

• NumPy-like API: Familiar APIs for element-wise mathematics, logic, array manipulation, and broadcasting.
• Views based on std::mdspan: Lightweight multidimensional views that refer to external memory without owning it.
• Containers based on kokkos::mdarray: Owning multidimensional containers developed within the std::mdspan ecosystem.
• constexpr-oriented implementation: Designed so that as many operations as possible can be used for compile-time evaluation and testing. Every currently implemented API can be evaluated in a constexpr context.
• Zero-copy broadcasting and manipulation views: Uses stride-based view transformations rather than eager copies whenever possible.

---

Quick Example (Run on Godbolt 😃)

1. Compile-time Addition with Broadcasting

#include <iostream>

#include "mdtensor/mdtensor.hpp"

namespace md = mdtensor;

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

    constexpr auto c_expect =
        md::full<int>(md::extents<std::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);
}

Result:

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]]]

---

Currently Implemented API Groups

---

Installation

mdtensor is a header-only library. Add the repository to your compiler's include path and include the following header. A compiler with C++20 or later support is required.

#include "mdtensor/mdtensor.hpp"

---

Tests and Benchmarks

This repository uses the Bazel build system. After installing Bazel, you can run the tests and benchmarks with the commands below. The development environment defined by .devcontainer/dockerfile can run them without additional setup.

1. Run All Tests

bazel test tests/...

2. Run a Benchmark

bazel run benchmarks/math/add:main

---

Roadmap

• Expand NumPy API coverage
• Strengthen generalized broadcasting rules
• Introduce lazy computation
• Select the optimal backend based on compile-time and runtime workload analysis, including SIMD, Eigen, and CPU/GPU multiprocessor backends

---

Contributing

This project is actively maintained, although new APIs and framework changes are currently driven primarily by the author's needs. Feel free to open an issue or pull request if you are interested in developing new APIs, improving the framework, or extending backend support.

---

License

mdtensor is distributed under the Apache License 2.0. See LICENSE for details.

mdtensor contains some code derived from CTMD v0.16.1, released on August 19, 2025. CTMD is an Apache License 2.0 library developed by the author of this project at Uon Robotics. Since then, mdtensor has been substantially modified through API extensions and framework improvements.

The original copyright for CTMD is held by Uon Robotics. The modifications and extensions in mdtensor are maintained by Chan-Soon Lim.