### Configuring Install Export for Example Library - CMake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/example/CMakeLists.txt

This snippet defines a documentation string and then uses `rapids_export` to configure the installation export for the 'example' library. It makes the 'example' target globally available and associates it with the `example-targets` export set, ensuring proper documentation is included for installed packages.

```CMake
set(doc_string
[=[
Provide targets for the example library.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt
mollit anim id est laborum.

]=])

 rapids_export(INSTALL example
    EXPORT_SET example-targets
    GLOBAL_TARGETS example # since we can't hook into EXPORT SETS
    NAMESPACE example::
    DOCUMENTATION doc_string
    )
```

--------------------------------

### Installing 'example' Target Library

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/example/CMakeLists.txt

This final snippet determines the appropriate installation directory for libraries using `rapids_cmake_install_lib_dir` and then installs the `example` target to that location. It also exports the target for use by other projects.

```CMake
rapids_cmake_install_lib_dir( lib_dir )
install(TARGETS example
        DESTINATION ${lib_dir}
        EXPORT example-targets
        )
```

--------------------------------

### Full CMakeLists.txt Example with CPM.cmake

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/README.md

This comprehensive CMake example illustrates setting up a project, adding an executable, including CPM.cmake, and managing dependencies. It shows how to add the Catch2 testing framework using `CPMAddPackage` and then link it to an executable, demonstrating a typical project setup.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

# create project
project(MyProject)

# add executable
add_executable(tests tests.cpp)

# add dependencies
include(cmake/CPM.cmake)
CPMAddPackage("gh:catchorg/Catch2@2.5.0")

# link dependencies
target_link_libraries(tests Catch2)
```

--------------------------------

### Setting Up CMake Project and Executable (CMake)

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/boost/CMakeLists.txt

This snippet defines the minimum required CMake version, sets the project name, creates an executable target, and specifies the C++ standard for compilation. It's the foundational setup for the project, ensuring compatibility and modern C++ features.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

project(CPMExampleBoost)

# ---- Create binary ----

add_executable(CPMExampleBoost main.cpp)
target_compile_features(CPMExampleBoost PRIVATE cxx_std_17)
```

--------------------------------

### Adding cxxopts with CPM in CMake

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/README.md

This snippet shows how to integrate the cxxopts library using CPM.cmake. It explicitly sets the install option to YES and disables examples and tests to reduce build size.

```CMake
CPMAddPackage(
  GITHUB_REPOSITORY jarro2783/cxxopts
  VERSION 2.2.1
  OPTIONS "CXXOPTS_BUILD_EXAMPLES NO" "CXXOPTS_BUILD_TESTS NO" "CXXOPTS_ENABLE_INSTALL YES"
)
```

--------------------------------

### Building Standard MatX Examples - CMake

Source: https://github.com/nvidia/matx/blob/main/examples/CMakeLists.txt

This loop iterates through the predefined `examples` list. For each example, it constructs the `.cu` filename, adds an executable target, and links it against the `example_lib` interface library.

```CMake
foreach( example ${examples} )
    string( CONCAT file ${example} ".cu" )
    add_executable( ${example} ${file} )
    target_link_libraries(${example} example_lib)
endforeach()
```

--------------------------------

### Comprehensive Dependency Tracking Example with rapids-cmake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/docs/dependency_tracking.rst

This example demonstrates the full workflow of dependency tracking using `rapids_find_package` for `Threads` and `rapids_cpm_find` for `nlohmann_json`. It shows how to link libraries, install targets, and export build and install configurations using `rapids_export` to ensure dependencies are correctly propagated for both build and install interfaces.

```CMake
rapids_find_package(Threads REQUIRED
  BUILD_EXPORT_SET example-targets
  INSTALL_EXPORT_SET example-targets
  )
rapids_cpm_find(nlohmann_json 3.9.1
  BUILD_EXPORT_SET example-targets
  )

add_library(example src.cpp)
target_link_libraries(example
  PUBLIC Threads::Threads
    $<BUILD_INTERFACE:nlohmann_json::nlohmann_json>
  )
install(TARGETS example
  DESTINATION lib
  EXPORT example-targets
  )

set(doc_string [=[Provide targets for the example library.]=])
rapids_export(INSTALL example
  EXPORT_SET example-targets
  NAMESPACE example::
  DOCUMENTATION doc_string
  )
rapids_export(BUILD example
  EXPORT_SET example-targets
  NAMESPACE example::
  DOCUMENTATION doc_string
  )
```

--------------------------------

### Custom Target for Installing Each Component Separately

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/export/export-verify-install-components/CMakeLists.txt

This custom target, `install_each_component_files`, automates the installation of different project components into distinct temporary directories. It uses `cmake --install` to install the main 'fake' project, 'c1' component, and 'c2' component, each into its own prefixed path, facilitating isolated testing of component installations.

```CMake
add_custom_target(install_each_component_files ALL
  COMMAND ${CMAKE_COMMAND} --install "${CMAKE_BINARY_DIR}" --component fake --prefix install/fake/
  COMMAND ${CMAKE_COMMAND} --install "${CMAKE_BINARY_DIR}" --component c1 --prefix install/c1/
  COMMAND ${CMAKE_COMMAND} --install "${CMAKE_BINARY_DIR}" --component c2 --prefix install/c2/
  )
```

--------------------------------

### Exporting CMake Targets with rapids_export (CMake)

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/docs/dependency_tracking.rst

This CMake snippet demonstrates the use of the `rapids_export` command to define export sets for an example library, covering both installation (`INSTALL`) and build (`BUILD`) configurations. It specifies the `EXPORT_SET`, `NAMESPACE`, and links to a `DOCUMENTATION` string, simplifying the generation of CMake package configuration files and ensuring proper target visibility.

```cmake
set(doc_string [=[Provide targets for the example library.]=])
rapids_export(INSTALL example
  EXPORT_SET example-targets
  NAMESPACE example::
  DOCUMENTATION doc_string
  )
rapids_export(BUILD example
  EXPORT_SET example-targets
  NAMESPACE example::
  DOCUMENTATION doc_string
  )
```

--------------------------------

### Getting Tensor Rank in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This snippet illustrates how to retrieve the rank (number of dimensions) of a MatX tensor. The `Rank()` member function, being `constexpr`, provides the compile-time known rank of the tensor.

```cpp
auto r = t.Rank();
```

--------------------------------

### Setting up Project and Managing Dependencies with CPM (CMake)

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/simple_match/CMakeLists.txt

This snippet initializes a CMake project, sets the minimum required CMake version, and manages external dependencies using the CPM.cmake module. It specifically adds 'simple_match' as a Git-based dependency, downloading it and configuring it as an interface library for inclusion.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

project(CPMSimpleMatchExample)

# ---- Dependencies ----

include(../../cmake/CPM.cmake)

CPMAddPackage(
  NAME simple_match
  GIT_REPOSITORY https://github.com/jbandela/simple_match.git
  GIT_TAG a3ab17f3d98db302de68ad85ed399a42ae41889e
  DOWNLOAD_ONLY True
)

if(simple_match_ADDED)
  add_library(simple_match INTERFACE IMPORTED)
  target_include_directories(simple_match SYSTEM INTERFACE "${simple_match_SOURCE_DIR}/include")
endif()
```

--------------------------------

### Initial CMake Project Setup with rapids-cmake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/cpm/cpm_cccl-preserve-custom-install-loc/CMakeLists.txt

This snippet initializes a CMake project, sets the minimum required CMake version, and includes essential modules from `rapids-cmake` for package management (`cpm/init.cmake`) and `cccl` integration (`cpm/cccl.cmake`). It also defines the project name and enables standard GNU install directories.

```CMake
cmake_minimum_required(VERSION 3.23)

include(${rapids-cmake-dir}/cpm/init.cmake)
include(${rapids-cmake-dir}/cpm/cccl.cmake)

project(fake LANGUAGES CXX VERSION 3.1.4)

rapids_cpm_init()

include(GNUInstallDirs)
```

--------------------------------

### C++ Example for Test-as-Documentation

Source: https://github.com/nvidia/matx/blob/main/docs_input/developer_guide/docs.rst

This C++ snippet illustrates the 'testing-as-documentation' methodology employed in MatX. It demonstrates how to embed a unit test example within documentation by wrapping it with `// example-begin <name>` and `// example-end <name>` comments, allowing the documentation to directly reference working code and ensuring accuracy through test-driven updates.

```cpp
// example-begin max-test-1
auto t0 = make_tensor<TestType>({});
auto t1o = make_tensor<TestType>({11});

t1o.SetVals({(T)1, (T)3, (T)8, (T)2, (T)9, (T)10, (T)6, (T)7, (T)4, (T)5, (T)11});

// Reduce all inputs in "t1o" into "t0" by the maximum of all elements
(t0 = max(t1o)).run(exec);
// example-end max-test-1
```

--------------------------------

### Retrieving Tensor Rank in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This snippet demonstrates how to get the number of dimensions (rank) of a MatX tensor using the `Rank()` member function. Since the rank is a compile-time constant, this function is marked `constexpr`.

```C++
auto r = t.Rank();
```

--------------------------------

### Slicing Tensors with `slice` Operator in MatX C++

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This snippet demonstrates the `slice` operator in MatX, which creates new lightweight views of a tensor without modifying the underlying data. It shows examples of extracting a sub-cube, a strided rectangle, a single column, and a single row, using start, stop, and optional stride parameters, along with `matxEnd` and `matxDropDim` keywords.

```cpp
auto tCube  = slice(t, {3, 5}, {6, 8});                      // Cube of t using rows 3-5 and cols 5-7
auto tRectS = slice(t, {0, 0}, {matxEnd, matxEnd}, {2, 2});  // Rectangle with stride of 2 in both dimensions
auto tCol   = slice<1>(t, {0, 4}, {matxEnd, matxDropDim});   // Create a 1D tensor with only column 5
auto tRow   = slice<1>(t, {4, 0}, {matxDropDim, matxEnd});   // Create a 1D tensor with only row 5
```

--------------------------------

### Slicing MatX Tensors in C++

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This snippet demonstrates the `slice` operator in MatX, which creates a new view of a tensor based on start, stop, and optional stride parameters. It shows examples of slicing a sub-cube, a strided rectangle, and extracting a single column or row to form a 1D tensor. These operations do not modify the original data but provide a lightweight view.

```C++
auto tCube  = slice(t, {3, 5}, {6, 8});                      // Cube of t using rows 3-5 and cols 5-7
auto tRectS = slice(t, {0, 0}, {matxEnd, matxEnd}, {2, 2});  // Rectangle with stride of 2 in both dimensions
auto tCol   = slice<1>(t, {0, 4}, {matxEnd, matxDropDim});   // Create a 1D tensor with only column 5
auto tRow   = slice<1>(t, {4, 0}, {matxDropDim, matxEnd});   // Create a 1D tensor with only row 5
```

--------------------------------

### Permuting Sliced MatX Tensor Views in C++

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example demonstrates combining `slice` and `permute` operations. It first slices a tensor `t` to create a sub-cube view and then applies the `permute` function to this view, swapping its dimensions (e.g., transposing a 2D view).

```cpp
auto tCubeP  = permute(slice(t, {3, 5}, {6, 8}), {1, 0});
```

--------------------------------

### Compiling and Running MatX Permute Example (Shell)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/01_introduction.ipynb

This shell command compiles and executes the `example1_permute` C++ program, demonstrating the `permute` operation. It uses a provided `compile_and_run.sh` script.

```Shell
!./exercises/compile_and_run.sh example1_permute
```

--------------------------------

### Initializing MatX Tensor with Initializer List (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This snippet demonstrates how to initialize a MatX tensor with a set of values using an initializer list via the `SetVals` function. This allows for convenient population of tensor data after creation, similar to array initialization in C++.

```C++
auto myT = make_tensor<float>({3, 3});
myT.SetVals({{1,2,3}, {4,5,6}, {7,8,9}});
```

--------------------------------

### Retrieving Tensor Shape in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example shows how to obtain the `tensorShape_t` object, which encapsulates the rank and dimensions of a MatX tensor view. The `Shape()` member function returns this object, providing information similar to NumPy's `shape` attribute.

```cpp
auto shape = t.Shape();
```

--------------------------------

### Executing MatX Example Compilation and Run Script (Python)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/01_introduction.ipynb

This snippet demonstrates how to execute a shell script `compile_and_run.sh` from a Python environment (e.g., Jupyter notebook) to compile and run the `example1_init` MatX example. The `!` prefix indicates a shell command execution.

```Python
!./exercises/compile_and_run.sh example1_init
```

--------------------------------

### Retrieving Individual Tensor Values in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example demonstrates how to retrieve the value of a specific element from a MatX tensor view. Similar to setting values, the `operator()` is used with the desired indices to access and copy the element's value into a variable.

```cpp
float f = t(2,2)
```

--------------------------------

### Initializing CMake Project and Adding Core Dependencies

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/asio-standalone/CMakeLists.txt

This snippet sets the minimum required CMake version, defines the project name, includes the CPM package manager, finds the `Threads` package, and adds the ASIO library as a dependency using CPM from GitHub.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

project(CPMExampleASIOStandalone)

# ---- Dependencies ----

include(../../cmake/CPM.cmake)

find_package(Threads REQUIRED)

CPMAddPackage("gh:chriskohlhoff/asio#asio-1-18-1@1.18.1")
```

--------------------------------

### Slicing MatX Operator Output in C++

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows that the `slice` operator can be applied directly to the output of another operator, such as `eye()`, which generates an identity matrix. It creates a view of a sub-region of the identity matrix generated from the shape of tensor `t`.

```C++
slice(eye(t.Shape()), {3, 5}, {6, 8});
```

--------------------------------

### Accessing Tensor Elements by Rank in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This snippet clarifies that the `operator()` used for accessing tensor elements requires a number of parameters equal to the tensor's rank. It provides examples for a rank-0 tensor (scalar) and a rank-1 tensor (vector).

```C++
auto f0 = t0();  // t0 is a rank-0 tensor (scalar)
auto f1 = t1(5); // t1 is a rank-1 tensor (scalar)
```

--------------------------------

### Enabling MatX Examples via CMake

Source: https://github.com/nvidia/matx/blob/main/docs/basics/build.html

This CMake option enables the compilation of example programs, providing practical demonstrations of how to use the MatX library's features.

```CMake
-DMATX_BUILD_EXAMPLES=ON
```

--------------------------------

### Compiling and Running MatX Simple Slice Example (Shell)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/01_introduction.ipynb

This shell command compiles and executes the `example1_simple_slice` C++ program, showcasing the basic `slice` operation. It leverages the `compile_and_run.sh` script for execution.

```Shell
!./exercises/compile_and_run.sh example1_simple_slice
```

--------------------------------

### Combining MatX Tensor Operator Definition and Execution (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example illustrates a common pattern in MatX where the definition of an operator expression and its immediate execution are combined into a single line. This approach is useful when the operator does not need to be stored for later reuse, streamlining the code.

```C++
(c = (a*a) + b / 2.0 + abs(a)).run(stream);
```

--------------------------------

### Configuring CMake Project with CPM and CXXOpts

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/cxxopts/CMakeLists.txt

This snippet defines the minimum CMake version, sets up the project, includes CPM for dependency management, adds the cxxopts library as a package, creates an executable from `main.cpp`, links it with `cxxopts`, and enforces C++17 standard features for compilation. It demonstrates a complete setup for a C++ project using external dependencies.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

project(CPMExampleCXXOpts)

# ---- Dependencies ----

include(../../cmake/CPM.cmake)

CPMAddPackage("gh:jarro2783/cxxopts@2.2.0")

# ---- Create binary ----

add_executable(CPMExampleCXXOpts main.cpp)
target_link_libraries(CPMExampleCXXOpts cxxopts)
target_compile_features(CPMExampleCXXOpts PRIVATE cxx_std_17)
```

--------------------------------

### Permuting a Multi-Dimensional MatX Tensor in C++

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example extends the `permute` function to a 4D tensor. It creates a 4D tensor `t4` and then permutes its dimensions according to the specified order `{1,3,2,0}`, creating a new view `tp4` with the reordered dimensions.

```C++
auto t4 = make_tensor<float>({10, 20, 5, 2});
auto tp4 = permute(t, {1,3,2,0});
```

--------------------------------

### Finding and Linking System and Boost Libraries (CMake)

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/boost/CMakeLists.txt

This snippet finds the required 'Threads' package and then links both 'Boost::system' and 'Threads::Threads' to the 'CPMExampleBoost' executable. This ensures the project can use functionalities provided by these essential system and third-party libraries.

```CMake
find_package(Threads REQUIRED)

target_link_libraries(CPMExampleBoost PRIVATE Boost::system Threads::Threads)
```

--------------------------------

### Combining Generators and Operators (MatX C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example demonstrates combining multiple generators (`ones`, `linspace_x`) and arithmetic operators (multiply, add) into a single fused kernel without intermediate storage. The expression calculates `ones + (linspace_x * 5.0)` and stores the result in `t1`.

```cpp
auto t1 = make_tensor<float>({100});
(t1 = ones<float>(t1.Shape()) + linspace_x(t1.Shape(), 1.0f, 100.0f) * 5.0).run();
```

--------------------------------

### Downloading CPM.cmake Script via Wget

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/README.md

This Bash command sequence demonstrates how to automatically download the latest `get_cpm.cmake` script into a `cmake` directory within your project. It first creates the directory if it doesn't exist and then uses `wget` to fetch the file, simplifying CPM.cmake integration.

```Bash
mkdir -p cmake
wget -O cmake/CPM.cmake https://github.com/cpm-cmake/CPM.cmake/releases/latest/download/get_cpm.cmake
```

--------------------------------

### Getting Individual Tensor Dimension Sizes in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This code demonstrates how to fetch the size of a specific dimension of a MatX tensor. The `Size()` function takes an index representing the dimension, allowing retrieval of individual dimension lengths, such as the size of a vector or the rows/columns of a matrix.

```cpp
auto t1size = t1.Size(0); // Size of vector t1
auto t2rows = t2.Size(0); // Rows in t2
auto t2cols = t2.Size(1); // Cols in t2
```

--------------------------------

### Compiling and Running MatX Example (Python)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/04_radar_pipeline.ipynb

This Python snippet executes a shell command to compile and run a specific MatX example, `example4_init`. It's typically used in environments like Jupyter notebooks to automate the build and execution of C++ MatX code, ensuring the example's functionality can be tested.

```python
!./exercises/compile_and_run.sh example4_init
```

--------------------------------

### Combining Generators and Operators in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows how to combine multiple MatX generators (`ones`, `linspace_x`) and arithmetic operators (`+`, `*`) into a single fused kernel. The expression is evaluated without intermediate storage, optimizing performance by reducing memory transfers.

```C++
auto t1 = make_tensor<float>({100});
(t1 = ones<float>(t1.Shape()) + linspace_x(t1.Shape(), 1.0f, 100.0f) * 5.0).run();
```

--------------------------------

### Building All MatX Components (Shell)

Source: https://github.com/nvidia/matx/blob/main/README.md

This snippet demonstrates the standard CMake commands to build all MatX components, including tests, benchmarks, and examples, while disabling documentation generation. It creates a build directory, configures CMake with specific build flags, and then compiles the project using `make`.

```sh
mkdir build && cd build
cmake -DMATX_BUILD_TESTS=ON -DMATX_BUILD_BENCHMARKS=ON -DMATX_BUILD_EXAMPLES=ON -DMATX_BUILD_DOCS=OFF ..
make -j
```

--------------------------------

### Configuring CMake Project with CPM and fmtlib

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/fmt/CMakeLists.txt

This snippet defines the minimum CMake version, sets up the project name, includes the CPM module for dependency management, and adds fmtlib as a package. It then defines an executable, sets its C++ standard, and links it against the fmt library.

```CMake
cmake_minimum_required(VERSION 3.14 FATAL_ERROR)

project(CPMJSONExample)

# ---- Dependencies ----

include(../../cmake/CPM.cmake)

CPMAddPackage("gh:fmtlib/fmt#7.1.3")

# ---- Executable ----

add_executable(CPMFmtExample main.cpp)
target_compile_features(CPMFmtExample PRIVATE cxx_std_17)
target_link_libraries(CPMFmtExample fmt)
```

--------------------------------

### Getting Individual Tensor Elements in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This snippet demonstrates retrieving the value of a specific element from a MatX tensor view using `operator()`. The returned value is of the tensor's underlying data type, allowing for direct assignment to a variable.

```C++
float f = t(2,2) // f is now 5.5
```

--------------------------------

### Initializing CPM and Project Setup in CMake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/cpm/cpm_find-restore-cpm-vars/CMakeLists.txt

This snippet includes necessary CPM modules, sets the minimum CMake version, defines the project, and specifies a mock source directory for ZLIB, followed by initializing the `rapids-cpm` system.

```CMake
include(${rapids-cmake-dir}/cpm/init.cmake)
include(${rapids-cmake-dir}/cpm/find.cmake)

cmake_minimum_required(VERSION 3.26.4)
project(rapids-cpm-find-add-pkg-source LANGUAGES CXX)

set(CPM_ZLIB_SOURCE "${CMAKE_CURRENT_SOURCE_DIR}/mock_zlib_source_dir")

rapids_cpm_init()
```

--------------------------------

### Combining Generators and Operators (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This example shows how to combine multiple generators and arithmetic operators into a single expression without intermediate storage. It initializes `t1` by adding a vector of ones (from `ones` generator) to a scaled linearly-spaced sequence (from `linspace_x`), all fused into a single kernel.

```C++
auto t1 = make_tensor<float>({100});
(t1 = ones<float>(t1.Shape()) + linspace_x(t1.Shape(), 1.0f, 100.0f) * 5.0).run();
```

--------------------------------

### Initializing Documentation Theme and Mode in JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/api/polynomials/legendre.html

This JavaScript snippet initializes the documentation page's theme and mode settings. It retrieves user preferences from `localStorage` for 'mode' and 'theme', applying them to the `documentElement.dataset`. If no preference is found, 'mode' defaults to an empty string and 'theme' defaults to 'light'. This script ensures the documentation viewer's appearance persists across sessions.

```JavaScript
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
```

--------------------------------

### Executing Conditional Deferred Assignments (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This example illustrates a more complex conditional expression where assignments are deferred. The `IFELSE` construct conditionally assigns `A` to `B` or `B` to `C`. None of these assignments occur until the `A > 5` condition is evaluated on the device, ensuring only one branch is executed.

```C++
IFELSE(A > 5, B = A, C = B).run()
```

--------------------------------

### Fusing Operator Expressions with Transforms (MatX C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows how to fuse an operator expression directly into a transform call in MatX, eliminating the need for an intermediate tensor. The expression `b + 2` is computed and its result is immediately used as an input to the `matmul` transform.

```C++
(c = matmul(b + 2, d)).run(stream);
```

--------------------------------

### Initializing rapids-cmake and Project Setup in CMake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/cpm/cpm_find-existing-target-to-export-sets/CMakeLists.txt

This snippet initializes the `rapids-cmake` CPM (CMake Package Manager) and sets up the basic project structure. It includes necessary `rapids-cmake` modules, defines a mock project, creates a fake build directory for testing, and prepares the `CMAKE_PREFIX_PATH` for dependency discovery. It also defines an imported interface library to represent the found dependency.

```CMake
cmake_minimum_required(VERSION 3.26.4)

include(${rapids-cmake-dir}/cpm/init.cmake)
include(${rapids-cmake-dir}/cpm/find.cmake)
include(${rapids-cmake-dir}/export/write_dependencies.cmake)

project(rapids-existing-target LANGUAGES CXX)

include("${rapids-cmake-testing-dir}/cpm/make_fake_project_build_dir_with_config.cmake")

make_fake_project_build_dir_with_config(RapidsTestFind 2021.01.02
    RapidsTestFindConfig.cmake
    RapidsTestFindConfigVersion.cmake)

rapids_cpm_init()

set(CMAKE_PREFIX_PATH
  "${CMAKE_CURRENT_BINARY_DIR}/RapidsTestFind-build/"
  )


add_library(RapidsTest::RapidsTest IMPORTED INTERFACE)
```

--------------------------------

### Retrieving Individual Dimension Sizes in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example illustrates how to fetch the size of a specific dimension of a MatX tensor using the `Size()` method. It takes an integer parameter representing the index of the desired dimension (0 for rows, 1 for columns, etc.).

```C++
auto t1size = t1.Size(0); // Size of vector t1
auto t2rows = t2.Size(0); // Rows in t2
auto t2cols = t2.Size(1); // Cols in t2
```

--------------------------------

### Initializing Documentation Theme and Page Name in JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/basics/basics.html

This JavaScript snippet initializes the documentation's display mode and theme preferences from local storage, defaulting to an empty string for mode and 'light' for theme if not found. It also sets a global variable `DOCUMENTATION_OPTIONS.pagename` to identify the current page.

```JavaScript
document.documentElement.dataset.mode = localStorage.getItem("mode") || ""; document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";             DOCUMENTATION_OPTIONS.pagename = 'basics/basics';
```

--------------------------------

### Combining MatX Operator Definition and Immediate Execution (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This example illustrates a common pattern where a complex MatX operator expression is defined and immediately executed on a CUDA stream without the need to store the operator in an intermediate variable. This streamlines the code for immediate, one-off computations.

```cpp
(c = (a*a) + b / 2.0 + abs(a)).run(stream);
```

--------------------------------

### Defining MatX Examples List - CMake

Source: https://github.com/nvidia/matx/blob/main/examples/CMakeLists.txt

This snippet defines a list of example names that will be built as executables. Each name corresponds to a `.cu` source file in the project.

```CMake
set(examples
    simple_radar_pipeline
    recursive_filter
    channelize_poly_bench
    convolution
    conv2d
    cgsolve
    eigenExample
    fft_conv
    interpolate
    resample
    mvdr_beamformer
    pwelch
    resample_poly_bench
    sparse_tensor
    spectrogram
    spectrogram_graph
    spherical_harmonics
    svd_power
    qr
    black_scholes
    print_styles)
```

--------------------------------

### Retrieving Tensor Rank in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This code shows how to get the compile-time known rank (number of dimensions) of a MatX tensor using the `Rank()` member function. Since the rank is known at compile time, this function uses the `constexpr` modifier for potential optimization.

```C++
auto r = t.Rank();
```

--------------------------------

### Expected Output of MatX Tensor Initialization Example (Shell)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/01_introduction.ipynb

This snippet shows the expected standard output after successfully running the `example1_init` MatX program. It displays the 5x4 integer matrix, confirming the successful creation and initialization of the tensor with the specified values.

```Shell
000000:    1    2    3    4 
000001:    5    6    7    8 
000002:    9   10   11   12 
000003:   13   14   15   16 
000004:   17   18   19   20 
```

--------------------------------

### Initializing Tensor with Initializer List in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows how to initialize a 2D tensor with predefined values using an initializer list via the `SetVals` function. First, a 3x3 float tensor is created, then its elements are populated with the specified nested list of values.

```C++
auto myT = make_tensor<float>({3, 3});
myT.SetVals({{1,2,3}, {4,5,6}, {7,8,9}});
```

--------------------------------

### Setting Individual Tensor Elements in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows how to assign values to specific elements within a MatX tensor view using the `operator()`. The indices provided correspond to the tensor's dimensions, allowing direct modification of individual data points.

```C++
t(2,2) = 5.5;
t(4,6) = -10f;
```

--------------------------------

### Configuring MatX Example Interface Library - CMake

Source: https://github.com/nvidia/matx/blob/main/examples/CMakeLists.txt

This code block defines an interface library `example_lib` for common properties shared by all examples. It includes necessary directories for CUTLASS, Pybind11, and Python, links against the core `matx::matx` library, and enables exports.

```CMake
add_library(example_lib INTERFACE)
target_include_directories(example_lib SYSTEM INTERFACE ${CUTLASS_INC} ${pybind11_INCLUDE_DIR} ${PYTHON_INCLUDE_DIRS})

target_link_libraries(example_lib INTERFACE matx::matx) # Transitive properties

set_property(TARGET example_lib PROPERTY ENABLE_EXPORTS 1)
```

--------------------------------

### Combining Slice and Permute for Tensor Views in C++

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This C++ example demonstrates chaining `slice` and `permute` operations. It first creates a sub-view (slice) of a tensor `t` and then applies a permutation to that sliced view, effectively swapping its dimensions. This highlights the ability to apply view functions on existing views.

```C++
auto tCubeP  = permute(slice(t, {3, 5}, {6, 8}), {1, 0});
```

--------------------------------

### Defining Executable and Linking Libraries (CMake)

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/simple_match/CMakeLists.txt

This snippet defines an executable named 'CPMSimpleMatchExample' from 'main.cpp', sets its C++ standard to C++17, and links it against the 'simple_match' library, making its headers available for compilation.

```CMake
# ---- Executable ----

add_executable(CPMSimpleMatchExample main.cpp)
target_compile_features(CPMSimpleMatchExample PRIVATE cxx_std_17)
target_link_libraries(CPMSimpleMatchExample simple_match)
```

--------------------------------

### Performing Element-wise Tensor Addition with MatX Operator Expression (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example illustrates a fundamental MatX operator expression for element-wise tensor addition. It shows the creation of three 2D tensors and then uses a deferred assignment operator (`=`) combined with the `.run()` method to execute the computation as a GPU kernel.

```C++
auto a = make_tensor<float>({10, 20});
auto b = make_tensor<float>({10, 20});
auto c = make_tensor<float>({10, 20});
(c = a + b).run();
```

--------------------------------

### Installing MatX to System (Shell)

Source: https://github.com/nvidia/matx/blob/main/README.md

This sequence of shell commands builds and installs the MatX library to the system's standard paths. It navigates to the MatX source, creates a build directory, configures CMake, and then compiles and installs the library.

```sh
cd /path/to/matx
mkdir build && cd build
cmake ..
make && make install
```

--------------------------------

### Conditional Deferred Assignment with MatX IFELSE in C++

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This example shows a more complex deferred expression using `IFELSE` for conditional assignment. Similar to simpler assignments, neither `B = A` nor `C = B` will execute until `A > 5` is evaluated on the device, at which point only one of the assignments will occur based on the condition.

```C++
IFELSE(A > 5, B = A, C = B).run()
```

--------------------------------

### Initializing Documentation Theme Setting - JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/api/stats/avgvar/stdd.html

This snippet fetches the user's chosen theme from localStorage and sets it on the document's root element. If no theme is stored, it defaults to 'light', ensuring a consistent initial appearance.

```JavaScript
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
```

--------------------------------

### Adding a Dependency with CPM.cmake (Full Syntax)

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/README.md

This snippet shows the full syntax for the `CPMAddPackage` function in CMake. It allows fetching and configuring a dependency by specifying its unique `NAME`, an optional minimum `VERSION`, `OPTIONS` for configuration, and a `DOWNLOAD_ONLY` flag. Additional origin parameters are forwarded to `FetchContent_Declare`.

```CMake
CPMAddPackage(
  NAME          # The unique name of the dependency (should be the exported target's name)
  VERSION       # The minimum version of the dependency (optional, defaults to 0)
  OPTIONS       # Configuration options passed to the dependency (optional)
  DOWNLOAD_ONLY # If set, the project is downloaded, but not configured (optional)
  [...]         # Origin parameters forwarded to FetchContent_Declare, see below
)
```

--------------------------------

### Performing Element-wise Tensor Addition with MatX Operator Expression (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This example illustrates the basic usage of MatX operator expressions to perform an element-wise addition of two tensors, `a` and `b`, storing the result in `c`. The assignment is deferred, and the `run()` method explicitly launches the generated CUDA kernel for execution.

```cpp
auto a = make_tensor<float>({10, 20});
auto b = make_tensor<float>({10, 20});
auto c = make_tensor<float>({10, 20});
(c = a + b).run();
```

--------------------------------

### Adding Executable Target

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/range-v3/CMakeLists.txt

This command defines an executable target named 'CPMRangev3Example' from the source file 'main.cpp'. This is a standard CMake command to create a buildable program.

```CMake
add_executable(CPMRangev3Example main.cpp)
```

--------------------------------

### Copying a Permuted Tensor View to Contiguous Memory in C++

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This C++ example demonstrates how to explicitly copy a permuted tensor view (`t4p`) into a new tensor (`t4pc`) with contiguous memory layout. This is recommended when a permuted view will be accessed repeatedly, as it can significantly improve performance by optimizing memory access patterns.

```C++
auto t4pc = make_tensor<float>(tp4.Shape());
copy(t4pc, t4p);
```

--------------------------------

### Assigning Lazy Expression to Temporary Variable (MatX C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example shows assigning a lazy MatX expression to a temporary variable `op`. The right-hand side `(A = B + C)` represents a deferred assignment, while the left-hand side `auto op = ...` executes the copy constructor on `op`. This pattern is typically used for debugging.

```cpp
auto op = (A = B + C);
```

--------------------------------

### Defining and Installing an Interface Library - CMake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/cpm/cpm_find-options-escaped/CMakeLists.txt

This snippet defines an interface library named `exampleLib`. Interface libraries do not compile source code but are used to propagate usage requirements (like include directories or link libraries) to other targets. The library is then installed and associated with the `example_export_set` for later export.

```CMake
add_library(exampleLib INTERFACE)
install(TARGETS exampleLib EXPORT example_export_set)
```

--------------------------------

### Reshaping 1D Tensor to 2D View in MatX C++

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example illustrates how to reshape a 1D tensor into a 2D view using the `View` method. It creates a 1D tensor `t1` of size 16 and then creates a new view `t2` that interprets the same underlying memory as a 4x4 2D tensor, without copying any data.

```cpp
auto t1 = make_tensor<float>({16});
auto t2 = t1.View({4,4});
```

--------------------------------

### Initializing Documentation Page Theme in JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/api/manipulation/selecting/at.html

This JavaScript snippet retrieves user preferences for 'mode' and 'theme' from `localStorage` and applies them to the `documentElement`'s `dataset` attributes. If no preference is found, it defaults to an empty string for 'mode' and 'light' for 'theme', ensuring consistent UI presentation across sessions.

```javascript
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
```

--------------------------------

### Creating a Static Tensor View in MatX (C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This example illustrates the creation of a compile-time sized static tensor view using `make_static_tensor`. For static tensors, the shape (10, 20) is provided as template parameters, which can offer performance improvements when accessing elements. Note that static tensors may have limitations with certain library functions.

```cpp
auto t = make_static_tensor<float, 10, 20>();
```

--------------------------------

### Initializing UI Theme and Search Buttons in JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/api/viz/line.html

This JavaScript snippet dynamically adds HTML buttons for theme switching (light/dark/auto mode) and a search functionality to the webpage. It uses `document.write` to inject the button HTML directly into the document, leveraging Font Awesome icons and Bootstrap tooltips for styling and interactivity.

```JavaScript
document.write(" <button class=\"theme-switch-button btn btn-sm btn-outline-primary navbar-btn rounded-circle\" title=\"light/dark\" aria-label=\"light/dark\" data-bs-placement=\"bottom\" data-bs-toggle=\"tooltip\"> <span class=\"theme-switch\" data-mode=\"light\"><i class=\"fa-solid fa-sun\"></i></span> <span class=\"theme-switch\" data-mode=\"dark\"><i class=\"fa-solid fa-moon\"></i></span> <span class=\"theme-switch\" data-mode=\"auto\"><i class=\"fa-solid fa-circle-half-stroke\"></i></span> </button> "); document.write(" <button class=\"btn btn-sm navbar-btn search-button search-button__button\" title=\"Search\" aria-label=\"Search\" data-bs-placement=\"bottom\" data-bs-toggle=\"tooltip\"> <i class=\"fa-solid fa-magnifying-glass\"></i> </button> ");
```

--------------------------------

### Example MatX Tensor Sliced Print (C++)

Source: https://github.com/nvidia/matx/blob/main/docs/fundamentals/tensor.html

This C++ example demonstrates how to use the Print method on a MatX tensor a with specific start, end, and stride indices. It prints a 2D tensor a where the first dimension starts at index 2 and goes to the end with a stride of 1, and the second dimension starts at index 3, ends at index 5 (exclusive), with a stride of 2. This usage is equivalent to first slicing the tensor and then printing the resulting view.

```C++
a.Print({2, 3}, {matxEnd, 5}, {1, 2});
```

--------------------------------

### Example Usage of matx::logspace for Tensor Assignment in C++

Source: https://github.com/nvidia/matx/blob/main/docs/api/creation/operators/logspace.html

This example demonstrates how to use `matx::logspace` to create a logarithmically-spaced sequence of numbers and assign them to a 1D tensor. It initializes a tensor, defines start and stop values, and then applies `logspace` to populate the tensor.

```C++
index_t count = 20;
tensor_t<TypeParam, 1> t1{{count}};
TypeParam start = 1.0f;
TypeParam stop = 2.0f;
auto s = t1.Shape();

// Create a logarithmically-spaced sequence of numbers and assign to tensor "t1"
(t1 = logspace<0>(s, start, stop)).run();
```

--------------------------------

### Dynamically Adding UI Buttons with JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/quickstart.html

This JavaScript snippet uses `document.write` to dynamically inject HTML content into the document. It adds two interactive buttons: a theme switch button with light/dark/auto modes and a search button. Both buttons utilize Bootstrap classes for styling and Font Awesome icons for visual representation, along with tooltips for user guidance.

```javascript
document.write(" <button class=\"theme-switch-button btn btn-sm btn-outline-primary navbar-btn rounded-circle\" title=\"light/dark\" aria-label=\"light/dark\" data-bs-placement=\"bottom\" data-bs-toggle=\"tooltip\"> <span class=\"theme-switch\" data-mode=\"light\"><i class=\"fa-solid fa-sun\"></i></span> <span class=\"theme-switch\" data-mode=\"dark\"><i class=\"fa-solid fa-moon\"></i></span> <span class=\"theme-switch\" data-mode=\"auto\"><i class=\"fa-solid fa-circle-half-stroke\"></i></span> </button> "); document.write(" <button class=\"btn btn-sm navbar-btn search-button search-button__button\" title=\"Search\" aria-label=\"Search\" data-bs-placement=\"bottom\" data-bs-toggle=\"tooltip\"> <i class=\"fa-solid fa-magnifying-glass\"></i> </button> ");
```

--------------------------------

### Creating Executable and Linking linenoise

Source: https://github.com/nvidia/matx/blob/main/public/cpm-cmake/examples/linenoise/CMakeLists.txt

This snippet defines an executable target named 'CPMlinenoiseExample' from 'main.cpp'. It sets the C++ standard to C++17 for this target and links it against the 'linenoise' library, making linenoise's functionality available to the executable.

```CMake
add_executable(CPMlinenoiseExample main.cpp)
target_compile_features(CPMlinenoiseExample PRIVATE cxx_std_17)
target_link_libraries(CPMlinenoiseExample linenoise)
```

--------------------------------

### Slicing a MatX Tensor View in C++

Source: https://github.com/nvidia/matx/blob/main/docs/_sources/quickstart.rst

This snippet demonstrates how to create a sub-view (slice) of an existing MatX tensor using the `slice` operator. It allows specifying start and end indices for each dimension to extract a contiguous block of the underlying data, creating a new tensor view.

```C++
auto tCube  = slice(t, {3, 5}, {6, 8});                      // Cube of t using rows 3-5 and cols 5-7
```

--------------------------------

### Executing Pulse Compression Example (Shell/Python)

Source: https://github.com/nvidia/matx/blob/main/docs_input/notebooks/04_radar_pipeline.ipynb

This command-line snippet compiles and runs the 'example4_pc' demonstration for pulse compression. It is typically executed from a shell or within a Python environment that supports shell commands, allowing users to observe the final pulse compression results.

```python
!./exercises/compile_and_run.sh example4_pc
```

--------------------------------

### Initializing CMake Project and Including RAPIDS.cmake

Source: https://github.com/nvidia/matx/blob/main/cmake/rapids-cmake/testing/other/rapids_cmake-fetch-via-zip/CMakeLists.txt

This snippet sets the minimum required CMake version, defines the project "rapids-test-project" with CXX language support, and then constructs the path to `RAPIDS.cmake` using `cmake_path` before including it. This is a foundational setup for a RAPIDS-enabled CMake project.

```CMake
cmake_minimum_required(VERSION 3.26.4)
project(rapids-test-project LANGUAGES CXX)

cmake_path(GET rapids-cmake-dir PARENT_PATH rapids.cmake-location)
cmake_path(APPEND rapids.cmake-location "RAPIDS.cmake")

include("${rapids.cmake-location}")
```

--------------------------------

### Initializing Tensor with linspace_x Generator (MatX C++)

Source: https://github.com/nvidia/matx/blob/main/docs_input/quickstart.rst

This code initializes a MatX tensor `t1` with linearly-spaced values using the `linspace_x` generator. `linspace_x` takes the tensor's shape, a start value, and a stop value, generating a sequence that is then stored into `t1` upon `run()` execution.

```cpp
auto t1 = make_tensor<float>({100});
(t1 = linspace_x(t1.Shape(), 1.0f, 100.0f)).run();
```

--------------------------------

### Initialize Documentation Page Theme and Options - JavaScript

Source: https://github.com/nvidia/matx/blob/main/docs/api/math/trig/asin.html

This JavaScript code initializes the visual theme and mode of the documentation page from local storage, applying default values if none are found. It also sets a global variable `DOCUMENTATION_OPTIONS.pagename` to identify the current page within the documentation structure.

```JavaScript
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
DOCUMENTATION_OPTIONS.pagename = 'api/math/trig/asin';
```