Boost.Multi

Alfredo A. Correa (last modified: 2026-01-10 09:22:14 UTC)

Introduction

Multi is a modern C++ library that provides manipulation and access of data in multidimensional arrays for both CPU and GPU memory.

Multidimensional array data structures are fundamental to several branches of computing, such as data analysis, image processing, and scientific simulations, and, in combination with GPUs, to Artificial Intelligence and Machine Learning. This library offers array containers and subarrays in arbitrary dimensions with well-behaved value semantics,

 1D ┌─0──┬─1──┬─2──┐   2D  ┌─0──┬─1──┬─2──┐   3D  ┌─0──┬─1──┬─2──┐       4D, ... ND
    │  a │  b │  c │       0  f │  g │  h │       0  m │  n │  o │2──┐
    └────┴────┴────┘       ├────┼────┼────┤       ├────┼────┼────┤ u │
                           1  i │  j │  k │       1  p │  q │  r │───┤
                           └────┴────┴────┘       └────┴────┴────┘ x │
                                                     └────┴─────┴────┘

These depicted 1D, 2D, and 3D arrays containing letters and can be represented, within this library, as C++ objects declared as:

#include <boost/multi.hpp>
multi::array<char, 1> A1D = {'a', 'b', 'c'};
multi::array<char, 2> A2D = { {'f', 'g', 'h'}, {'i', 'j', 'k'} };
multi::array<char, 3> A3D = /*... nested list of letters (chars) */ ;

and their elements, when retrived by their coordinates (indices) are such that, for example: A1D[1] == 'b', A2D[1][0] == 'i' and A3D[1][0][2] == 'u' Note that the depicted 3D case has only two planes, the first index (e.g. 1) selects the plane (e.g. bottom).

The library features logical access recursively across dimensions and to elements through indices and iterators. The internal data structure layout (when mapped to computer memory) is stride-based, which makes it compatible with low-level C libraries.

The library interface is designed to be compatible with standard algorithms and ranges (STL) and special memory (including GPUs) and follows modern C++ design principles.

Features of this library that aim to facilitate the manipulation of multidimensional arrays include:

  • Value semantics of multidimensional array containers and well-defined referential semantics of subarrays to avoid unnecessary copies if possible.

  • Availability of different access patterns to the elements in the multidimensional structure, as nested sequences or as a single sequence of elements. A D-dimensional array can be interpreted either as an (STL-compatible) sequence of (D-1)-dimensional subarrays or as a flattened one-dimensional (also STL-compatible) sequence of elements.

  • Interoperability with both legacy C and modern C++ libraries (e.g., STL, ranges, Thrust --CUDA and AMD GPUs--, Boost).

  • Memory management and allocation to exploit modern memory spaces, including GPU memory, mapped memory, and fancy pointers.

  • Lazy arrays and evaluation of array expressions well integrated with the rest of the library.

Do not confuse this library with Boost.MultiArray or with the standard MDSpan proposal std::mdspan. This library shares some of their goals and is compatible and complementary to them; but it is designed at a different level of generality and with other priorities (such as the features listed above). The code is entirely independent and has fundamental implementation and semantics differences.

The library’s primary concern is with the storage and logic structure of data. It doesn’t make algebraic or geometric assumptions about the arrays and their elements. (althoug they are still good building blocks for implementing mathematical algorithms, such as representing algebraic dense matrices in the 2D case, or tensors in the general case.)

The library does not throw exceptions and provides basic exception guarantees (such as no memory leaks) in their presence (e.g., thrown from allocations). Indexing and other logical errors result in undefined behavior, which this library attempts to reflect via assertions.

Multi is a header-only library and C++17 or later is required.