### Install Example Dependencies

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

Install optional example dependencies for NVIDIA Warp. This command ensures all necessary libraries for running the examples are available.

```text
pip install warp-lang[examples]
```

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

### Browse Example Source Code

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

Open the directory containing the example files using the Python module runner. This command facilitates easy access to the source code of the examples.

```text
python -m warp.examples.browse
```

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

### Run Warp examples

Source: https://github.com/nvidia/warp/blob/main/docs/index.rst

Execute Warp examples by installing optional dependencies and running them as Python modules. This command structure allows you to specify example subdirectories and specific examples.

```python
python -m warp.examples.<example_subdir>.<example>
```

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

### Build and Run CUBIN Launch Example

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Builds and runs the CUBIN launch example. This demonstrates loading compiled CUDA kernels at runtime.

```bash
cd 00_cubin_launch
make && ./00_cubin_launch
```

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

### Clone and Build Warp Repository

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/01_source_include/README.md

Clone the Warp repository and install it. This sets up the necessary environment for running the C++ examples.

```bash
git clone https://github.com/NVIDIA/warp.git
cd warp

# Build and install (choose one):
uv run build_lib.py  # Option A (recommended - handles everything automatically)
# or: python build_lib.py && pip install -e .  # Option B (use a virtual environment)

cd warp/examples/cpp/01_source_include
```

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

### Navigate to C++ Examples

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Change the directory to the C++ examples folder within the Warp repository.

```bash
cd warp/examples/cpp
```

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

### Build Warp with uv

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Build and install Warp using the recommended `uv` command. This handles dependencies and environment setup automatically.

```bash
uv run build_lib.py
```

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

### Example: Using ScopedDevice with Multiple GPUs

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/devices.rst

This example shows how to allocate arrays and launch kernels on all available CUDA devices by iterating through them and using `wp.ScopedDevice` for each.

```python
import warp as wp


@wp.kernel
def inc(a: wp.array[float]):
    tid = wp.tid()
    a[tid] = a[tid] + 1.0


# get all CUDA devices
devices = wp.get_cuda_devices()
device_count = len(devices)

# number of launches
iters = 1000

# list of arrays, one per device
arrs = []

# loop over all devices
for device in devices:
    # use a ScopedDevice to set the target device
    with wp.ScopedDevice(device):
        # allocate array
        a = wp.zeros(250 * 1024 * 1024, dtype=float)
        arrs.append(a)

        # launch kernels
        for _ in range(iters):
            wp.launch(inc, dim=a.size, inputs=[a])

# synchronize all devices
wp.synchronize()

# print results
for i in range(device_count):
    print(f"{arrs[i].device} -> {arrs[i].numpy()}")
```

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

### Run CUBIN Launch Example with CMake

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/00_cubin_launch/README.md

Execute the compiled CUBIN launch example. The exact path to the executable may vary between Unix and Windows.

```bash
./build/00_cubin_launch                   # Step 4: Run (Unix) or build\Release\00_cubin_launch.exe (Windows)
```

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

### Install NVIDIA Warp from PyPI

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

Use this command to install the latest stable version of Warp from the Python Package Index. Install with '[examples]' to include dependencies for running examples and USD features.

```text
pip install warp-lang
```

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

### Install Warp with pip

Source: https://github.com/nvidia/warp/blob/main/docs/index.rst

Install the Warp framework from PyPI using pip. For other installation methods like conda or building from source, refer to the installation guide.

```sh
$ pip install warp-lang
```

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

### CPU Replay Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Example demonstrating how to load and replay a captured Warp graph using the C API for CPU replay.

```APIDOC
## CPU Replay Example (`03_apic_visualization_cpu`)

This example shows how to use the Warp C API to replay a graph on the CPU.

### Usage

```cpp
#include "apic.h"
#include "warp.h"

// Load the graph for CPU replay. The context is NULL for CPU devices.
APICGraph* graph = wp_apic_load_graph(nullptr, "generated/wave_sim", 1);

// ... resolve CPU kernel function pointers (implementation specific) ...

// Execute the graph on the CPU.
bool success = wp_apic_cpu_replay_graph(graph);

// ... handle success or failure ...

wp_apic_destroy_graph(graph);
```

### Notes

- This example does not link against CUDA libraries.
- Replay is performed by walking the recorded operation stream directly via `wp_apic_cpu_replay_graph()`.
```

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

### Run All Example Tests with Bash

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Execute all automated example tests using the provided bash script. This is the recommended method for CI/CD regression testing.

```bash
bash test_examples.sh
```

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

### Build and Run Source Include Example

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Builds and runs the source inclusion example. This demonstrates integrating generated CUDA source code directly into the C++ project.

```bash
cd 01_source_include
make && ./01_source_include
```

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

### Install Python Packages with uv

Source: https://github.com/nvidia/warp/blob/main/AGENTS.md

Install Python packages using `uv python install`. The Python version is inferred from the `.python-version` file.

```bash
uv python install
```

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

### Example Program Output

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/01_source_include/README.md

Displays the expected output from the C++ example program, showing the convergence of a training process and the learned parameters.

```text
Iter 0: MSE=321.055, params=[2.56704, 0.813697]
Iter 10: MSE=0.0161513, params=[3.53469, 0.971546]
...
Iter 90: MSE=0.0092167, params=[3.52368, 1.04446]

Learned: y = 3.52269*x + 1.05101
True:    y = 3.5*x + 1.2
Error:   Δa=0.022687, Δb=0.148992
✓ Training converged successfully!
```

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

### Launch Kernel Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Launches a kernel with specified inputs and outputs, then prints the result. Ensure CUDA is available.

```python
wp.launch(
        count_neighbors_example,
        dim=p.shape,
        inputs=[grid.id, p, r],
        outputs=[neighbor_count],
        device="cuda:0",
    )
    print(neighbor_count.numpy())
```

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

### Install clang-format (Ubuntu/Debian)

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/contribution_guide.rst

Instructions for installing a specific version of clang-format on Ubuntu/Debian systems. This is optional as pre-commit manages the version automatically.

```bash
sudo apt-get install clang-format-21
```

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

### Build and Run C++ Viewer Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Instructions for building and running the C++ APIC visualization examples using CMake. This process involves capturing the graph, building the C++ viewer, and then running the executable.

```bash
cd warp/examples/cpp/02_apic_visualization     # or 03_apic_visualization_cpu

    # 1. Capture the graph (requires Warp + Python)
    uv run capture_wave.py

    # 2. Build the C++ viewer
    cmake -B build -DCMAKE_BUILD_TYPE=Release
    cmake --build build --config Release

    # 3. Run
    ./build/02_apic_visualization                  # or 03_apic_visualization_cpu
```

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

### CUDA Replay Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Example demonstrating how to load and launch a captured Warp graph using the C API for CUDA replay.

```APIDOC
## CUDA Replay Example (`02_apic_visualization`)

This example shows how to use the Warp C API to replay a CUDA graph.

### Usage

```cpp
#include "aot.h"
#include "warp.h"
#include "apic.h"

// Assume 'context' is a valid CUcontext and 'window' is a GLFW window.
// Assume 'stream' is a valid CUDA stream.
APICGraph* graph = wp_apic_load_graph(context, "generated/wave_sim", 0);

// Build the executable on first call.
cudaGraphExec_t exec = (cudaGraphExec_t)wp_apic_get_cuda_graph_exec(graph);

while (!glfwWindowShouldClose(window))
{
    // Update inputs each frame (mouse, double-buffered height fields).
    cudaMemcpyAsync(d_mouse_pos, mouse_grid, 2 * sizeof(float),
                    cudaMemcpyHostToDevice, stream);
    wp_apic_set_param(graph, "heights",      d_heights[cur],     heights_size);
    wp_apic_set_param(graph, "heights_prev", d_heights[1 - cur], heights_size);
    wp_apic_set_param(graph, "mouse_pos",    d_mouse_pos,        2 * sizeof(float));

    cudaGraphLaunch(exec, stream);
    cudaStreamSynchronize(stream);  // Must sync before reading results

    wp_apic_get_param(graph, "heights_out",      d_heights[1 - cur], heights_size);
    wp_apic_get_param(graph, "heights_prev_out", d_heights[cur],     heights_size);

    // ... render with OpenGL ...
}

wp_apic_destroy_graph(graph);
```

### Notes

- This example requires linking against the Warp native library, the CUDA Driver API (`cuda`), and the CUDA Runtime API (`cudart`).
- The `.wrp` file encapsulates kernel information, abstracting away the need for the C++ code to know kernel signatures.
```

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

### Module Reloading Output Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/generics.rst

This output demonstrates the module reloading that occurs during kernel launches in the preceding Python example.

```text
Module __main__ load on device 'cuda:0' took 155.73 ms
17
Module __main__ load on device 'cuda:0' took 164.83 ms
42
```

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

### CUDA Activity Profiling Output Example

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/profiling.rst

Example output showing CUDA timeline, activity summary, and device summary when CUDA profiling is enabled.

```text
CUDA timeline:
----------------+---------+------------------------
Time            | Device  | Activity
----------------+---------+------------------------
    0.021504 ms | cuda:0  | memset
    0.163840 ms | cuda:0  | forward kernel inc_loop
    0.306176 ms | cuda:0  | forward kernel inc_loop
    0.451584 ms | cuda:0  | forward kernel inc_loop
    2.455520 ms | cuda:0  | memcpy DtoH
    0.051200 ms | cuda:1  | memset
    0.374784 ms | cuda:1  | forward kernel inc_loop
    0.707584 ms | cuda:1  | forward kernel inc_loop
    1.042432 ms | cuda:1  | forward kernel inc_loop
    2.136096 ms | cuda:1  | memcpy DtoH

CUDA activity summary:
----------------+---------+------------------------
Total time      | Count   | Activity
----------------+---------+------------------------
    0.072704 ms |       2 | memset
    3.046400 ms |       6 | forward kernel inc_loop
    4.591616 ms |       2 | memcpy DtoH

CUDA device summary:
----------------+---------+------------------------
Total time      | Count   | Device
----------------+---------+------------------------
    3.398624 ms |       5 | cuda:0
    4.312096 ms |       5 | cuda:1
Demo took 0.92 ms
```

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

### Install Pre-commit Hooks

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/contribution_guide.rst

Install the pre-commit framework to automatically run linters and formatters at git commit time. This helps maintain code quality and consistency.

```bash
uvx pre-commit install
```

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

### Memory Allocation Report Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Example report generated by ScopedMemoryTracker, detailing allocation counts, peak usage, and live allocations by size and source.

```text
Allocation Tracking Report
  Total allocations:
    cuda:0           2 (23.44 KB)
  Peak usage:
    cuda:0           23.44 KB
  Live allocations:
    cuda:0           2 (23.44 KB)

  Live cuda:0 allocations by size (largest first) (up to 10):
    11.72 KB : cuda:0 : array[vec3f, 1000] : example.py:4 : <module>()
    11.72 KB : cuda:0 : array[vec3f, 1000] : example.py:5 : <module>()
```

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

### Clone and Build Warp

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/00_cubin_launch/README.md

Clone the Warp repository and build the library. This is a prerequisite for running the example.

```bash
git clone https://github.com/NVIDIA/warp.git
cd warp

# Build and install (choose one):
uv run build_lib.py  # Option A (recommended - handles everything automatically)
# or: python build_lib.py && pip install -e .  # Option B (use a virtual environment)

cd warp/examples/cpp/00_cubin_launch
```

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

### Manually Run Example Tests with CMake and CTest

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/README.md

Manually compile and run example tests using CMake and CTest. This method allows for more granular control over the testing process.

```bash
cmake -B build && ctest --test-dir build --output-on-failure
```

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

### Warp Kernel Compilation and Caching Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/basics.rst

Illustrates the kernel cache functionality by running an example twice. The first run shows compilation, while the second demonstrates a much faster load time due to caching.

```bat
Warp 1.10.0.dev0 initialized:
CUDA Toolkit 13.0, Driver 13.0
Devices:
    "cpu"      : "x86_64"
    "cuda:0"   : "NVIDIA RTX PRO 6000 Blackwell Max-Q Workstation Edition" (95 GiB, sm_120, mempool enabled)
Kernel cache:
    /home/nvidia/.cache/warp/1.10.0.dev0
Module __main__ 0b0ecab load on device 'cuda:0' took 4136.19 ms  (compiled)
```

```bat
Warp 1.10.0.dev0 initialized:
CUDA Toolkit 13.0, Driver 13.0
Devices:
    "cpu"      : "x86_64"
    "cuda:0"   : "NVIDIA RTX PRO 6000 Blackwell Max-Q Workstation Edition" (95 GiB, sm_120, mempool enabled)
Kernel cache:
    /home/nvidia/.cache/warp/1.10.0.dev0
Module __main__ 0b0ecab load on device 'cuda:0' took 30.98 ms  (cached)
```

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

### Build and Run with Make

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/00_cubin_launch/README.md

Build the CUBIN launch example using Make and then run the executable. Assumes Make is available on Unix/Linux systems.

```bash
make              # Build everything (auto-compiles kernel if needed)
./00_cubin_launch # Run
```

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

### Console Output for Grid Build Timer

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Example console output showing the time taken by a ScopedTimer block.

```console
grid build took 0.06 ms
```

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

### Install libstdcxx-ng for Conda Environment Compatibility

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

When encountering C++ runtime library version mismatches in Conda environments, install a compatible libstdcxx-ng version. This example installs version 12.1 or newer.

```sh
conda install -c conda-forge libstdcxx-ng=12.1
```

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

### Build and Run with Make

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/README.md

Build the C++ example using Make and then run the executable. The 'make' command automatically captures the graph if needed.

```bash
make              # Build everything (auto-captures graph if needed)
./02_apic_visualization  # Run
```

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

### Build Warp with Existing LLVM Installation

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Configure the CMake build to use an existing LLVM installation for warp-clang by specifying the LLVM path. This is useful if you have a custom LLVM setup.

```console
$ cmake -S . -B _build/cmake -G Ninja -DWARP_LLVM_PATH=/opt/llvm
$ cmake --build _build/cmake --parallel
```

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

### Build Documentation

Source: https://github.com/nvidia/warp/blob/main/AGENTS.md

Build the project documentation and log output to a file for inspection.

```bash
uv run --extra docs build_docs.py 2>&1 | tee /tmp/build_docs.log
```

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

### Dockerfile for Building Custom Warp Image

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

A starting Dockerfile to build a custom Warp image from a local repository. It installs dependencies, copies Warp source files, and builds the package.

```dockerfile
FROM nvidia/cuda:13.0.0-devel-ubuntu24.04

# Install dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    python3 \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

COPY warp /warp/warp
COPY deps /warp/deps
COPY tools/packman /warp/tools/packman
COPY build_lib.py build_llvm.py pyproject.toml setup.py VERSION.md /warp/

WORKDIR /warp

RUN python3 -m pip install --break-system-packages numpy && \
    python3 build_lib.py && \
    python3 -m pip install --break-system-packages .

```

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

### Downgrade C++ Toolchain in Conda Environment

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Alternatively, downgrade the build environment's C++ toolchain to resolve runtime library version conflicts. This example installs libstdcxx-ng version 8.5.

```sh
conda install -c conda-forge libstdcxx-ng=8.5
```

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

### Build and Run with Make (Unix/Linux)

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/03_apic_visualization_cpu/README.md

Builds the example and automatically runs the Python capture script. Then, it executes the interactive C++ program.

```bash
cd warp/examples/cpp/03_apic_visualization_cpu
make                            # auto-runs capture_wave.py and fetches glad v2
./03_apic_visualization_cpu     # interactive run
```

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

### Interactive Development with GPU Access

Source: https://github.com/nvidia/warp/blob/main/docker/warp-builder/README.md

Start an interactive Docker container with GPU access for development and testing. Ensure NVIDIA Container Toolkit is installed on your host. Inside the container, you can build, test, and package Warp.

```bash
# Prerequisites: Install NVIDIA Container Toolkit on your host
# See: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

# Start a shell with GPU access
docker run --rm -it \
  --gpus all \
  -v $(pwd):/workspace \
  -w /workspace \
  ghcr.io/nvidia/warp-builder:cuda13 \
  bash

# Inside container:
# uv run build_lib.py --llvm-path /opt/llvm       # Build
# uv run --extra dev -m warp.tests -s autodetect  # Test (GPU tests will be skipped without --gpus)
# uv build --wheel                                 # Package
```

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

### APIC Visualization Smoke Test Setup

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/CMakeLists.txt

Configures a headless smoke test for the APIC visualization example. It uses the --smoke argument to skip the GUI and asserts that the test ran successfully by checking for a specific output pattern.

```cmake
add_test(NAME apic_visualization_smoke
    COMMAND $<TARGET_FILE:02_apic_visualization> --smoke
    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
set_tests_properties(apic_visualization_smoke PROPERTIES
    LABELS "cpp_example"
    PASS_REGULAR_EXPRESSION "smoke OK \(10 graph launches\)"
    TIMEOUT 60)
```

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

### Allocate and Launch Kernel

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/allocators.rst

Demonstrates a basic loop that allocates a new array and launches a kernel in each iteration. This can lead to significant allocation/deallocation overhead.

```python
for i in range(100):
    a = wp.zeros(n, dtype=float, device="cuda:0")
    wp.launch(kernel, dim=a.size, inputs=[a], device="cuda:0")
```

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

### Optimized Kernel Creation and Launch Sequence

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/codegen.rst

Demonstrates an optimized approach where all kernels are created first, followed by their launches. This avoids repeated module reloading and improves efficiency.

```python
def create_kernel_with_constant(constant):
    @wp.kernel
    def k(a: wp.array[float]):
        tid = wp.tid()
        a[tid] += constant
    return k

k1 = create_kernel_with_constant(17.0)
k2 = create_kernel_with_constant(42.0)
k3 = create_kernel_with_constant(-9.0)

a = wp.zeros(5, dtype=float)

wp.launch(k1, dim=a.shape, inputs=[a])
print(a)

wp.launch(k2, dim=a.shape, inputs=[a])
print(a)

wp.launch(k3, dim=a.shape, inputs=[a])
print(a)
```

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

### Install Warp package after building

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install the Warp package in editable mode after building from source. This ensures that changes to the library are immediately reflected in the installed package.

```console
$ pip install -e .
```

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

### Install Warp using Conda

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install the default CUDA variant of Warp from the conda-forge channel.

```sh
$ conda install conda-forge::warp-lang
```

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

### Kernel Creation with Runtime Constants (Interspersed Launches)

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/codegen.rst

Illustrates creating kernels dynamically with different constants and launching them immediately. This approach forces module reloading on each launch, impacting performance.

```python
def create_kernel_with_constant(constant):
    @wp.kernel
    def k(a: wp.array[float]):
        tid = wp.tid()
        a[tid] += constant
    return k

a = wp.zeros(5, dtype=float)

k1 = create_kernel_with_constant(17.0)
wp.launch(k1, dim=a.shape, inputs=[a])
print(a)

k2 = create_kernel_with_constant(42.0)
wp.launch(k2, dim=a.shape, inputs=[a])
print(a)

k3 = create_kernel_with_constant(-9.0)
wp.launch(k3, dim=a.shape, inputs=[a])
print(a)
```

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

### Build and Run with CMake

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/README.md

Build the C++ example using CMake. This involves capturing the graph, configuring the build, building the executable, and then running it.

```bash
python capture_wave.py                        # Step 1: Capture the graph
cmake -B build -DCMAKE_BUILD_TYPE=Release     # Step 2: Configure
cmake --build build --config Release          # Step 3: Build
./build/02_apic_visualization                 # Step 4: Run
```

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

### Install NVTX Python Package

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/profiling.rst

Install the NVIDIA NVTX Python package to enable NVTX integration with ScopedTimer.

```bash
pip install nvtx
```

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

### Usage Example: Prefetching Data for GPU and CPU Operations

Source: https://github.com/nvidia/warp/blob/main/design/hardware-coherent-memory-access.md

Demonstrates prefetching data to a GPU before a kernel launch and then back to the CPU for post-processing.

```python
# On DGX Spark / GB10 (host-page-table ATS system):
data = wp.array(np.random.randn(1000000), dtype=wp.float32, device="cpu")

# Prefetch to GPU before a compute-heavy kernel
wp.prefetch(data, device="cuda:0")
wp.launch(heavy_compute_kernel, dim=data.size, inputs=[data], device="cuda:0")

# Prefetch back to CPU before CPU-side post-processing
wp.prefetch(data, device="cpu")
result = data.numpy()
```

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

### Temporarily Install a Scoped Logger

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/debugging.rst

Use ScopedLogger to temporarily install a logger for diagnostics. It restores the previous logger on context exit.

```python
with wp.ScopedLogger(my_capture_logger):
    wp.launch(my_kernel, ...)
```

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

### Build and Run with Make

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/01_source_include/README.md

Build the C++ program using Make and then execute it. This is the default build method on Unix/Linux systems.

```bash
make
./01_source_include
```

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

### Equivalent Kernel Launches: launch_tiled vs. launch

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/tiles.rst

Demonstrates the equivalence between wp.launch_tiled and wp.launch for launching kernels with tile dimensions. Assumes 'kernel', 'M', 'N', 'inputs', and 'block_dim' are defined.

```python
# These are equivalent:
wp.launch_tiled(kernel, dim=[M, N],     inputs=[...], block_dim=64)
wp.launch(      kernel, dim=[M, N, 64], inputs=[...], block_dim=64)
```

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

### Install CUDA 12.9 Warp using Conda

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install a specific CUDA 12.9 variant of Warp using a build string filter.

```sh
# CUDA 12.9
$ conda install conda-forge::warp-lang=*=*cuda129*
```

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

### Install CPU-only Warp using Conda

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install a CPU-only version of Warp, which has no CUDA dependencies, using a specific build string filter.

```sh
# CPU-only (no CUDA dependencies)
$ conda install conda-forge::warp-lang=*=*cpu*
```

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

### Install Latest Nightly Build

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install the most recent nightly build from the NVIDIA Package Index. Note: Nightly builds are not available for macOS.

```sh
$ pip install -U --pre warp-lang --extra-index-url=https://pypi.nvidia.com/
```

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

### Run in Headless Smoke Mode

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/README.md

Execute the example in a headless mode for a sanity check. This mode loads the graph, queries parameters, and replays the graph multiple times without opening a graphical window.

```bash
./02_apic_visualization --smoke    # exits 0 with "smoke OK (10 graph launches)"
```

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

### Build Warp from Source

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/compatibility.rst

Execute these commands to build and install Warp from its source code. Use --help for available build options.

```console
$ python build_lib.py
$ pip install -e .
```

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

### CPU Replay of a Warp Graph in C++

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/runtime.rst

Example of loading a .wrp file for CPU replay. The graph is executed by walking the recorded operation stream directly.

```cpp
#include "apic.h"  // APIC graph loading and execution
#include "warp.h"  // Warp C API

APICGraph* graph = wp_apic_load_graph(nullptr, "generated/wave_sim", 1);

// ... resolve CPU kernel function pointers (see below) ...

```

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

### FEM Workflow Example

Source: https://github.com/nvidia/warp/blob/main/docs/domain_modules/fem.rst

Demonstrates the typical workflow for solving a PDE using FEM in Warp, including defining geometry, function spaces, integrating linear and bilinear forms, applying boundary conditions, and solving the resulting linear system.

```python
# Grid geometry
geo = Grid2D(res=wp.vec2i(resolution))

# Scalar function space
scalar_space = make_polynomial_space(geo, degree=degree)

# Right-hand-side (forcing term)
domain = Cells(geometry=geo)
test = make_test(space=scalar_space, domain=domain)
rhs = integrate(linear_form, fields={"v": test})

# Diffusion form
trial = make_trial(space=scalar_space, domain=domain)
matrix = integrate(diffusion_form, fields={"u": trial, "v": test}, values={"nu": viscosity})

# Boundary conditions on Y sides
boundary = BoundarySides(geo)
bd_test = make_test(space=scalar_space, domain=boundary)
bd_trial = make_trial(space=scalar_space, domain=boundary)
bd_matrix = integrate(
    y_boundary_projector_form, fields={"u": bd_trial, "v": bd_test}, assembly="nodal"
)

# Assemble linear system (add diffusion and boundary condition matrices)
matrix += bd_matrix * boundary_strength

# Solve linear system using Conjugate Gradient
x = wp.zeros_like(rhs)
bsr_cg(matrix, b=rhs, x=x)
```

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

### JAX Gradient Calculation Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/differentiability.rst

Demonstrates gradient calculation in JAX for a simple quadratic function using `vmap` and `grad`.

```python
import jax
import jax.numpy as jnp

def func(x):
    return x ** 2 + 3 * x + 1

x = jnp.array([1.0, 2.0, 3.0])
grad_func = jax.vmap(jax.grad(func))
x_grad = grad_func(x)

print(x_grad)
```

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

### Install GLFW Development Package

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/README.md

Install the GLFW development package if you encounter 'GLFW not found' errors. This is required for applications using GLFW for windowing and input.

```bash
sudo apt install libglfw3-dev  # Ubuntu/Debian
```

```bash
sudo dnf install glfw-devel    # Fedora
```

```bash
brew install glfw              # macOS (note: CUDA still not supported)
```

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

### Basic CMake Project Setup

Source: https://github.com/nvidia/warp/blob/main/warp/examples/cpp/02_apic_visualization/CMakeLists.txt

Sets the minimum CMake version and defines the project name with supported languages (CUDA, CXX, C).

```cmake
cmake_minimum_required(VERSION 3.20)
project(apic_visualization CUDA CXX C)
```

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

### RMM Installation (Linux)

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/allocators.rst

Install the RAPIDS Memory Manager (RMM) library, which provides high-performance pooled allocators for CUDA. This command is specific to Linux environments.

```bash
pip install rmm-cu12
```

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

### Launch Kernels with Different Floating Point Precisions

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/codegen.rst

Demonstrates launching a kernel with varying floating-point precisions (16, 32, 64-bit) to observe the impact on output. Ensure the kernel 'k' and input arrays are defined prior to launching.

```python
wp.launch(k, dim=a16.shape, inputs=[s16, a16])
wp.launch(k, dim=a32.shape, inputs=[s32, a32])
wp.launch(k, dim=a64.shape, inputs=[s64, a64])
```

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

### Install Warp from GitHub Releases (Windows x86-64)

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install Warp using a specific wheel file URL for Windows x86-64, built with the CUDA 13.0 runtime.

```sh
pip install https://github.com/NVIDIA/warp/releases/download/v1.12.1/warp_lang-1.12.1+cu13-py3-none-win_amd64.whl
```

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

### Implicit Kernel Instantiation Example

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/generics.rst

Demonstrates implicit kernel instantiation where Warp automatically generates new kernel instances for each unique set of argument types encountered during `wp.launch` calls. This can lead to performance overhead due to repeated module reloads.

```python
wp.launch(scale, dim=n, inputs=[x16, wp.float16(3)])
wp.launch(scale, dim=n, inputs=[x32, wp.float32(3)])
wp.launch(scale, dim=n, inputs=[x64, wp.float64(3)])
```

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

### Install Warp from GitHub Releases (Linux x86-64)

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install Warp using a specific wheel file URL for Linux x86-64, built with the CUDA 13.0 runtime.

```sh
pip install https://github.com/NVIDIA/warp/releases/download/v1.12.1/warp_lang-1.12.1+cu13-py3-none-manylinux_2_28_x86_64.whl
```

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

### Using Default and Explicit Devices

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/devices.rst

Illustrates setting a default device and then using both the default and explicitly specified devices for different operations within the same code block.

```python
# set default device
wp.set_device("cuda:0")

# use default device
a = wp.zeros(n)

# use explicit devices
b = wp.empty(n, device="cpu")
c = wp.empty(n, device="cuda:1")

# use default device
wp.launch(kernel, dim=a.size, inputs=[a])

wp.copy(b, a)
wp.copy(c, a)
```

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

### Install Warp from GitHub Releases (Linux aarch64)

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Install Warp using a specific wheel file URL for Linux aarch64, built with the CUDA 13.0 runtime.

```sh
pip install https://github.com/NVIDIA/warp/releases/download/v1.12.1/warp_lang-1.12.1+cu13-py3-none-manylinux_2_34_aarch64.whl
```

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

### Profile First 20 Kernel Launches

Source: https://github.com/nvidia/warp/blob/main/docs/deep_dive/profiling.rst

Use the -c option to specify the number of kernel launches to profile when you want to analyze the initial launches without selecting specific kernels.

```bash
ncu --open-in-ui -f -o example_sph --set full -c 20 python example_sph.py --stage-path None --num-frames 10
```

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

### Build Warp with Existing libmathdx Installation

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/installation.rst

Point the CMake build to an existing libmathdx installation using the DWARP_LIBMATHDX_PATH option. This ensures Warp can find and link against the specified libmathdx.

```console
$ cmake -S . -B _build/cmake -G Ninja -DWARP_LIBMATHDX_PATH=/path/to/libmathdx
$ cmake --build _build/cmake --parallel
```

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

### Run All Benchmarks with ASV in Bash

Source: https://github.com/nvidia/warp/blob/main/docs/user_guide/contribution_guide.rst

Execute all benchmarks against the current commit using ASV. The `--launch-method spawn` flag is recommended on Linux to prevent temporary file accumulation.

```bash
uvx --python 3.12 asv run -e --launch-method spawn HEAD^!
```

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

### Build and Push Docker Image

Source: https://github.com/nvidia/warp/blob/main/docker/warp-cpp-test-env/README.md

Builds the Docker image and pushes it to a specified registry. Replace 'your-registry.com' with your actual registry URL.

```bash
# Build the image
cd docker/warp-cpp-test-env
./build.sh

# Push to registry (replace with your registry URL)
docker tag warp-cpp-test-env:12.9.1-ubuntu24.04 your-registry.com/project/warp-cpp-test-env:12.9.1-ubuntu24.04
docker push your-registry.com/project/warp-cpp-test-env:12.9.1-ubuntu24.04
```