Building MatX
To build all components, issue the standard cmake build commands in a cloned repo:
mkdir build && cd build
cmake -DMATX_BUILD_TESTS=ON -DMATX_BUILD_BENCHMARKS=ON -DMATX_BUILD_EXAMPLES=ON -DMATX_BUILD_DOCS=OFF ..
make -j
By default CMake will target the GPU architecture(s) of the system you’re compiling on. If you wish to target other architectures, pass the
CMAKE_CUDA_ARCHITECTURES
flag with a list of architectures to build for:
cmake .. -DCMAKE_CUDA_ARCHITECTURES="80;90"
By default nothing is compiled. If you wish to compile certain options, use the CMake flags below with ON or OFF values:
MATX_BUILD_TESTS
MATX_BUILD_BENCHMARKS
MATX_BUILD_EXAMPLES
MATX_BUILD_DOCS
For example, to enable unit test building:
mkdir build && cd build
cmake -DMATX_BUILD_TESTS=ON ..
make -j
Integrating MatX With Your Own Projects
MatX uses CMake as a first-class build generator, and therefore provides the proper config files to include into your own project. There are typically two ways to do this:
- Adding MatX as a subdirectory
- Installing MatX to the system
MatX as a Subdirectory
Adding the subdirectory is useful if you include the MatX source into the directory structure of your project. Using this method, you can simply add the MatX directory:
add_subdirectory(path/to/matx)
An example of using this method can be found in the examples/cmake_sample_project directory.
MatX Installed to the System
The other option is to install MatX and use the configuration file provided after building. This is typically done in a way similar to what is shown below:
cd /path/to/matx
mkdir build && cd build
cmake ..
make && make install
If you have the correct permissions, the headers and cmake packages will be installed on your system in the expected paths for your operating
system. With the package installed you can use find_package
as follows:
find_package(matx CONFIG REQUIRED)
MatX CMake Targets
Once either of the two methods above are done, you can use the transitive target matx::matx
in your library inside of target_link_libraries
.
MatX may add other optional targets in the future inside the matx:: namespace as well.
Documentation
Documentation for MatX can be built locally as shown above with the DBUILD_DOCS=ON
cmake flag. Building documentation requires the following to be installed:
doxygen, breathe, sphinx, sphinx-rtd-theme, libjs-mathjax, texlive-font-utils, flex, bison
- Current documentation can be found here
- A quick start guide can be found here
- Current library limitations are listed here
- A conversion from MATLAB and Python syntax is found here
- A self-guided Jupyer notebook training can be found here
MatX uses semantic versioning and reserve the right to introduce breaking API changes on major releases.
Unit Tests
MatX contains a suite of unit tests to test functionality of the primitive functions, plus end-to-end tests of example code. MatX uses pybind11 to generate some of the unit test inputs and outputs. This avoids the need to store large test vector files in git, and instead can be generated as-needed.
To run the unit tests, from the cmake build directory run:
test/matx_test
This will execute all unit tests defined. If you wish to execute a subset of tests, or run with different options, you may run test/matx_test directly with parameters defined by Google Test. To run matx_test directly, you must be inside the build/test directory for the correct paths to be set. For example, to run only tests with the name FFT:
cd build/test
./matx_test --gtest_filter="*FFT*"
Quick Start Guide
We provide a variety of training materials and examples to quickly learn the MatX API.
- A quick start guide can be found in the docs directory or from the main documentation site. The MatX quick start guide is modeled after NumPy’s and demonstrates how to manipulate and create tensors.
- A set of MatX notebooks can be found in the docs directory. These four notebooks walk through the major MatX features and allow the developer to practice writing MatX code with guided examples and questions.
- Finally, for new MatX developers, browsing the example applications can provide familarity with the API and best practices.
Discussions
We have an open discussions board here. We encourage any questions about the library to be posted here for other users to learn from and read through.
Filing Issues
We welcome and encourage the creation of issues against MatX. When creating a new issue, please use the following syntax in the title of your submission to help us prioritize responses and planned work.
- Bug Report: Append
[BUG]
to the beginning of the issue title, e.g.[BUG] MatX fails to build on P100 GPU
- Documentation Request: Append
[DOC]
to the beginning of the issue title - Feature Request: Append
[FEA]
to the beginning of the issue title - Submit a Question: Append
[QST]
to the beginning of the issue title
As with all issues, please be as verbose as possible and, if relevant, include a test script that demonstrates the bug or expected behavior. It’s also helpful if you provide environment details about your system (bare-metal, cloud GPU, etc).