MatX For MATLAB/NumPy/Eigen Users — matx 0.9.4 documentation (original) (raw)

MatX For MATLAB/NumPy/Eigen Users#

MatX has many features directly inspired by MATLAB and Python (Numpy/Scipy) for translating these high-level languages into C++. The table below aims to give users of either of those tools a translation guide to writing efficient MatX code by learning the syntax mapping between the tools. Most of these conversions can also be found inside either the unit tests or the source code as well.

Due to its popularity in linear algebra applications, examples of common Eigen operations have been added to the below table. An example file is provided at examples/eigenExample.cu with examples of common operations in Eigen and their MatX equivalent. If you have Eigen installed on your system, you can build the examples with Eigen by setting the cmake variable eigen_DIR=/path/to/eigen/.

A few key notes to be aware of when using MatX and Eigen in the same environment:

  1. The below example are only valid for 2D data. Eigen and its API is primarily targeting 2D problems (without the unsupported/tensor library), so there is not a single pattern to follow for porting code with rank > 2 tensors from Eigen to MatX; each user’s solution for higher rank data will result in a unique mapping to MatX tensor memory.
  2. When copying data between Eigen and MatX structures (most likely Eigen::MatrixXd to MatX tensors) keep in mind that the underlying data structure may or may not be available on the CPU. use the accessor functions () or a cudaMemcpy when applicable.
  3. Eigen has column-major storage by default, so ensure you transpose any raw data copies between structures.

Overview#

Some general rules to keep in mind about these three tools:

  1. The Python column assumes both Numpy and Scipy are being used for certain library calls.
  2. Both Python and MATLAB use the term “multi-dimensional array”. MatX calls these tensors.
  3. MATLAB uses 1-based indexing while Python and MatX use 0-based indexing.
  4. MATLAB uses inclusive ranges on indexing, while Python and MatX use exclusive ranges.
  5. MATLAB and Python may or may not make a copy of a tensor behind-the-scenes to improve performance. MatX makes this explicit. by never making a copy unless the function call mentions that it copies.
  6. MATLAB uses column-major (FORTRAN) memory order, while Python and MatX use row-major (C). When converting optimized MATLAB scripts, it may be beneficial to transpose the dimension so the fastest changing dimension is the inner-most dimension.

Conversion Table#