Amir’s Homepage

PhD Dissertation LaTeX Template

2026-01-23T00:00:00-05:00

This is an unofficial LaTeX template for PhD Dissertation (Jan 2026) at Queen’s University, ECE department, PPRL group.

You can use this template as a starting point for your own dissertation. It includes the basic structure and formatting required by the university, as well as some additional features such as a glossary and macros for common terms.

View it on Github or Overleaf.

The glossary is created automatically. See the sample to understand how to define new terms and use them in the text.
Several macros have been defined in preamble.sty to make the text more readable. Use the same format to create your own macros.
To build locally, I suggest Linux or WSL, with latexmk and makeglossaries.

Setting up Gemini CLI on WSL Ubuntu 24.04

2025-12-29T00:00:00-05:00

During the past years, I have been under heavy workload of studies and work, and I couldn’t really explore the new AI tools that are coming out these days. Today, I was searching for a pomodoro timer app to help me focus on my work, and I thought, why not building one myself?? I think it was Afshin that had an influence on me. Check out his game (brilliant idea and vibecoded!): Connect 3 Chess.

So, I finally had the motivation and time (at the same time) to explore and experiment with a vibcoding agent. I decided to start with Gemini CLI.

Setting up Gemini CLI on WSL Ubuntu 24.04

I used this guide as a reference.

Step 1: Install Node.js and npm

I used nvm: (see here for more details)

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 24

# Verify the Node.js version:
node -v # Should print "v24.12.0".

# Verify npm version:
npm -v # Should print "11.6.2".

Step 2: Install and run Gemini CLI

npm install -g @google/gemini-cli

After installation, run the following command to start the Gemini CLI setup. But before that: I believe wherever you run it, it will read the content of that path. So make sure not to run it in some confidential or private path.

$ gemini

 ███            █████████  ██████████ ██████   ██████ █████ ██████   █████ █████
░░░███         ███░░░░░███░░███░░░░░█░░██████ ██████ ░░███ ░░██████ ░░███ ░░███
  ░░░███      ███     ░░░  ░███  █ ░  ░███░█████░███  ░███  ░███░███ ░███  ░███
    ░░░███   ░███          ░██████    ░███░░███ ░███  ░███  ░███░░███░███  ░███
     ███░    ░███    █████ ░███░░█    ░███ ░░░  ░███  ░███  ░███ ░░██████  ░███
   ███░      ░░███  ░░███  ░███ ░   █ ░███      ░███  ░███  ░███  ░░█████  ░███
 ███░         ░░█████████  ██████████ █████     █████ █████ █████  ░░█████ █████
░░░            ░░░░░░░░░  ░░░░░░░░░░ ░░░░░     ░░░░░ ░░░░░ ░░░░░    ░░░░░ ░░░░░

Tips for getting started:
1. Ask questions, edit files, or run commands.
2. Be specific for the best results.
3. Create GEMINI.md files to customize your interactions with Gemini.
4. /help for more information.

After authentication, you can start using Gemini CLI! That’s it!!

Let’s try it out

I gave it a straightforward request.

Create a desktop app for me to for the purpose of setting focused 
and DoNotDisturb timers, including breaks, work, etc. I'd like it
to have a small window, with minimal and beautiful colors. 
Whenever the timer ends, I want it to make a small bell-like 
notification. I want the focused time and break time to be 
customizable but also set as default with 3-4 presets. I don't 
want the app to stay on top to distract me. Build this app for 
running from a WSL Ubuntu terminal that launches a GUI. With Python.

Well, overall, after almost an hour, it did a pretty good job for me, and after asking me to install several dependencies, and fixing several issues, it was able to run the app successfully. However, the soundbell notification did not work due to WSL issue of not being able to access the audio hardware of Windows. Other than that, the app worked fine. Also, I asked for some improvements and features, like repetitions, progress, etc., and it was able to implement them pretty well.

For my record, I had to do the following to make the app work:

sudo apt install python3.12-venv
pyenv virtualenv pomodoro
pyenv activate pomodoro
sudo apt install python3-tk
pip3 install playsound==1.2.2
sudo apt-get install libgirepository1.0-dev libgirepository2.0-dev
sudo apt install libcairo2-dev pkg-config python3-dev
pip install PyGObject

I also install aplay to test sound playing from WSL:

sudo apt install alsa-utils
aplay /path/to/sample.wav

Which didn’t work anyway.

Then, I thought why not running it from Windows, with a clickable icon? So I asked it to generate it, and it did a great job again. It created a .bat and a .vbs file to launch the app without a terminal window. I also updated the color scheme a bit to match my Windows dark/green theme.

Here is how the app looks:

The code generated by Gemini CLI can be found here.

See this summary of the session:

> /quit
╭─────────────────────────────────────────────────────────────────────────────────╮
│                                                                                 │
│  Agent powering down. Goodbye!                                                  │
│                                                                                 │
│  Interaction Summary                                                            │
│  Session ID:                 erased                                             │
│  Tool Calls:                 9 ( ✓ 8 x 1 )                                      │
│  Success Rate:               88.9%                                              │
│  User Agreement:             88.9% (9 reviewed)                                 │
│  Code Changes:               +936 -50                                           │
│                                                                                 │
│  Performance                                                                    │
│  Wall Time:                  9h 58m 3s                                          │
│  Agent Active:               8m 21s                                             │
│    » API Time:               5m 41s (68.2%)                                     │
│    » Tool Time:              2m 39s (31.8%)                                     │
│                                                                                 │
│                                                                                 │
│  Model Usage                 Reqs   Input Tokens   Cache Reads  Output Tokens   │
│  ────────────────────────────────────────────────────────────────────────────   │
│  gemini-2.5-flash-lite         16         58,787             0          1,734   │
│  gemini-2.5-pro                22        192,728       211,514         19,758   │
│  gemini-2.5-flash               3         37,601        11,406            562   │
│                                                                                 │
│  Savings Highlight: 222,920 (43.5%) of input tokens were served from the cache, │
│  reducing costs.                                                                │
╰─────────────────────────────────────────────────────────────────────────────────╯

Well, that’s it for now. I am very much excited to do more exciting things with these agents! Let’s see how it goes.

Migrate from Ubuntu 20.04 in WSL to 24.04 LTS

2025-02-12T00:00:00-05:00

I have been using Ubuntu 20.04 in WSL for a while. Recently, I decided to upgrade it to the latest LTS version, which is 24.04 LTS. I have two options to do this: a fresh installation or an in-place upgrade using the do-release-upgrade command. ALthoguh I decided to go with the messy in-place upgrade first, I later changed my mind and went for a fresh installation, especially because I had to do two major version upgrades (20.04 -> 22.04 -> 24.04). So, anyways. Here are the steps I followed. I specifically put this post here for future reference in case I need to install all the various packages I need again.

Backup

First things, first.

Either back up your entire WSL instance using:

wsl --export Ubuntu-20.04 ubuntu-20.04-backup.tar

Or back the home dir:

cd ~
tar -czvf ubuntu-home-backup.tar.gz $HOME
mv ubuntu-home-backup.tar.gz /mnt/c/Users/YourWindowsUsername/some/dir/

Fresh Installation of Ubuntu 24.04 LTS in WSL

Install Ubuntu 24.04 LTS from Microsoft store. Open the installed instance once to finish the installation.

$ cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=24.04
DISTRIB_CODENAME=noble
DISTRIB_DESCRIPTION="Ubuntu 24.04.3 LTS"

After installation, in powershell check the installed distros:

wsl --list --verbose

cd ~
mv /mnt/c/Users/YourWindowsUsername/some/dir/ubuntu-home-backup.tar.gz .
tar -xzvf ubuntu-home-backup.tar.gz

Check if everything is okay, especially hidden files like .bashrc, .vimrc, .ssh, etc.

Installing Packages

Now, you need to reinstall all the packages you need.

sudo apt update && sudo apt upgrade -y
sudo apt install build-essential cmake git vim wget curl htop net-tools unzip zip -y
# some of my frequently used packages:
sudo apt install ninja-build gdb valgrind -y
sudo apt install aspell tldr colordiff tree lolcat neofetch fastfetch -y
sudo apt install zenity evince -y

Other Configurations

CUDA

If you need CUDA:

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install cuda-toolkit
# If you need the drivers too
sudo apt install cuda-drivers

LaTeX

I use texlive for LaTeX documents. To install it:

sudo apt install texlive-latex-recommended -y
# or 
sudo apt install texlive-latex-extra -y
# For full installation (7 GB+)
sudo apt install texlive-full -y

Pyenv

Install pyenv for managing python versions:

curl https://pyenv.run | bash

LLVM

For more info, visit here.

To, install LLVM from the official apt repository, first add the repository key and source:

wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
sudo apt-add-repository "deb http://apt.llvm.org/noble/ llvm-toolchain-noble main"

Add the following lines to /etc/apt/sources.list.d/llvm-toolchain-noble.list if not already added:

deb http://apt.llvm.org/noble/ llvm-toolchain-noble main
deb-src http://apt.llvm.org/noble/ llvm-toolchain-noble main
# 20
deb http://apt.llvm.org/noble/ llvm-toolchain-noble-20 main
deb-src http://apt.llvm.org/noble/ llvm-toolchain-noble-20 main
# 21
deb http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main
deb-src http://apt.llvm.org/noble/ llvm-toolchain-noble-21 main

Then install LLVM 20:

sudo apt update
sudo apt install nstall clang-20 clang-tools-20 clang-20-doc libclang-common-20-dev \
  libclang-20-dev libclang1-20 clang-format-20 python3-clang-20 clangd-20 clang-tidy-20 \
  libllvm-20-ocaml-dev libllvm20 llvm-20 llvm-20-dev llvm-20-doc llvm-20-examples \
  llvm-20-runtime libomp-20-dev lld-20

fastfetch

At the time of writing this post, fastfetch is not available for Ubuntu 24.04 and some of its docs have inconsistencies. Here is what worked for me:

sudo apt install git cmake build-essential libpci-dev libvulkan-dev libwayland-dev libxrandr-dev libxcb-randr0-dev libdconf-dev
git clone https://github.com/LinusDierheimer/fastfetch.git
cd fastfetch
# I changed the branch to master
git checkout master
mkdir build && cd build
cmake ..
cmake --build . 
sudo cmake --install .
# Now you can run fastfetch by just typing:
fastfetch
# or 
flashfetch

How to make ll (ls -alF) show the year in the timestamp:

alias ll='ls -alF --time-style=long-iso'

Post-migration

After everything is done, you can remove the old WSL instance if you made a full backup:

wsl --unregister Ubuntu-20.04

Some tips on removing old packages and cleaning up to make the backup smaller.

sudo apt autoremove --purge
sudo apt autoclean

# Check which packages are large and remove if not needed 
# This command shows the 30 largest installed packages
dpkg-query -Wf='${Installed-Size}\t${Package}\n' \
  | sort -n | tail -n 30 \
  | awk '{printf "%10.2f MB %s\n", $1/1024, $2}'

# You can search for a group of packages like this:
dpkg-query -Wf='${Installed-Size}\t${Package}\n' | grep cuda

# You can also add the sizes of the packages from previous command to get total size
dpkg-query -Wf='${Installed-Size}\t${Package}\n' | grep cuda \
  | awk '{sum += $1} END {printf "Total size: %.2f MB\n", sum/1024}'

To remvove old log files:

sudo journalctl --vacuum-time=7d
sudo truncate -s 0 /var/log/syslog
sudo truncate -s 0 /var/log/auth.log
sudo rm -f /var/log/*.gz
sudo rm -f /var/log/*.[0-9]
sudo rm -f /var/log/*.[0-9].gz
sudo rm -f /var/log/Xorg.pid-*.log

Compact in WSL

To compact the WSL virtual disk after removing old files and packages, first exit all WSL instances and then run (in powershell with admin rights):

wsl --terminate Ubuntu-20.04
# or 
wsl --shutdown
diskpart 
# in diskpart prompt:
select vdisk file="Path\to\vdisk\file"
# For me it is:
select vdisk file="C:\Users\amirs\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu20.04LTS_79rhkp1fndgsc\LocalState\ext4.vhdx"
compact vdisk file

I also had several versions of CUDA, LLVM, ROCM, HIP, and other packages installed that I no longer needed. With these steps, I was able to reduce the size of the storage around 250 GB to about 50 GB.

For now, I haven’t encountered any compatibility issues with Ubuntu 24.04 LTS in WSL. Everything seems to be working fine so far. If some issues arise, I will update this post accordingly.

Some Tips to Release Binaries

2025-01-20T00:00:00-05:00

There are several things to consider when releasing a binary. Here are some tips that I found useful.

Best Practices

Releases are tied to tags, not branches.
Versioning - Use Semantic Versioning!
Security - Sign the binaries and verify the signatures.
Changelog - Keep a CHANGELOG.md file.
License - Include a LICENSE file.
Documentation - Include a README.md file including how to install and use the binary.
CI/CD - Automate the build, test, and the release process.

Consider Signing the Binary

Signing the binary is a good practice to ensure the integrity and authenticity of the binary. You can use GPG on Linux:

# If you don't already have a GPG key, generate one:
$ gpg --full-generate-key
# Choose RSA and a key size (e.g., 4096).
# Set an expiration date (or none for permanent).
# Enter your name and email (match your GitHub email).

Then, export the public key:

$ gpg --armor --export YOUR_EMAIL > public.key
# This will create a file named public.key.

After that, sign the binary:

$ gpg --detach-sign --armor app-linux-x86_64.tar.gz
# a file named app-linux-x86_64.tar.gz.asc will be created.

gpg --detach-sign --armor app-windows-x64.zip
# a file named app-windows-x64.zip.asc will be created.

Then, you can upload the binaries and their signatures to GitHub releases.

app-linux-x86_64.tar.gz
app-linux-x86_64.tar.gz.asc
app-windows-x64.zip
app-windows-x64.zip.asc

Then, users can verify the binaries using the public key:

$ gpg --import public.key
$ gpg --verify app-linux-x86_64.tar.gz.asc app-linux-x86_64.tar.gz
$ gpg --verify app-windows-x64.zip.asc app-windows-x64.zip
# output should be sth like: "Good signature from YOUR_NAME "

Automating the Release Process with GitHub Actions

Add a GitHub Action workflow (.github/workflows/release.yml).

name: Release Binaries

on:
  push:
    tags:
      - 'v*'  # Triggers on versioned tags like v1.0.0

jobs:
  build:
    runs-on: $
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up build environment
        run: echo "Setting up..."

      - name: Build
        run: |
          # Replace with your build commands
          echo "Building binary for $"

      - name: Upload binaries
        uses: actions/upload-artifact@v3
        with:
          name: app-$
          path: path/to/binary

  release:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v3
        with:
          path: ./artifacts

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          files: ./artifacts/**
          tag_name: $

Automating the Signing in GitHub Actions

You can automate the signing process using GitHub Actions. Here is an example workflow:

- name: Import GPG Key
  run: |
    echo "$GPG_PRIVATE_KEY" | gpg --batch --import
    echo "trusted-key $(gpg --list-keys --with-colons | grep pub | cut -d: -f5)" >> ~/.gnupg/gpg.conf

- name: Sign Binary
  run: gpg --detach-sign --armor myapp-linux-x86_64.tar.gz

Alternative to GPG

If you’re distributing via containers or want an alternative to GPG, you can use Sigstore Cosign.

Code Signing for Windows

I haven’t done this myself, but you can sign the Windows binaries using SignTool.

Utilize PTX Just-In-Time (JIT) Compilation in CUDA

2024-10-22T00:00:00-04:00

In this post I’ve written about how to utilize PTX Just-In-Time (JIT) compilation in CUDA. PTX is a low-level assembly-like language that is used to represent the GPU code. The PTX code is then compiled to the machine code by the NVIDIA driver at runtime. This process is called Just-In-Time (JIT) compilation. But before I write about how to use PTX JIT compilation, I’ll provide some background on why you might want to use it.

Background Scenario

In this scenario, you may want to load a CUDA kernel at runtime as a CUDA Module, then extract a CUDA Funtion from the kernel you wrote, and then get more information from it. Information like the number of register usage per thread, shared memory, etc. Or you may want to intelligently select the number of blocks/threads to optimize SM Occupancy in order to have valid inter-block synchronization capabilities via cooperative groups.

Furthermore, if the aforementioned kernel is defined in a separate CU file, and you are getting these information from a C or C++ code, then it makes more sense to use separate compilation to PTX or FATBIN files, and then load them at runtime.

Loading the CUDA module

To create a PTX file or a FATBIN file, you can use the following command:

# Create a PTX file
nvcc -ptx -o kernel.ptx kernel.cu
# Cre`ate a FATBIN file
nvcc -fatbin -o kernel.fatbin kernel.cu

Then you can load the CUDA module at runtime with something like this (CUDA Driver API):

#include 
#include 

int main() {
  
  cuInit(0);

  // select the first device
  CUdevice device;
  cuDeviceGet(&device, 0);

  CUcontext context;
  cuCtxCreate(&context, 0, device);

  CUmodule module;
  CUfunction function;
  CUresult result;

  result = cuModuleLoad(&module, "kernel.ptx");
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to load the module." << std::endl;
    return 1;
  }

  result = cuModuleGetFunction(&function, module, "kernel");
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to get the function." << std::endl;
    return 1;
  }

  // Do something with the function
  // ...
  return 0;
}

Then build the main source with:

nvcc -o main main.cu -lcuda

Thoughts and Improvements

All in all, it’s a straightforward process. However, there are some issues:

The build process is a bit complicated, especially if you are using CMake.
The FATBIN/PTX file should be addressed correctly, and it is not always preferable.

So, why not storing the PTX code directly in the source file itself? This way, you can avoid the build process and the file management.

Just a reminder, the JIT Process doesn’t accept the actual CUDA code, but the PTX code. So, you need to convert the CUDA code to PTX code first. (I spent 2 hours to understand this!) Here is how you can do it:

#include 
#include 

// PTX code generated by:
// nvcc -ptx -o kernel.ptx kernel.cu
const char* kernel = R"(
  .version 6.5
  .target sm_70
  .address_size 64

  .visible .entry kernel(
    .param .u64 kernel_param_0
  )
  {
    // Kernel code here
  }
)";

int main() {
  
  cuInit(0);

  // select the first device
  CUdevice device;
  cuDeviceGet(&device, 0);

  CUcontext context;
  cuCtxCreate(&context, 0, device);

  CUmodule module;
  CUfunction function;
  CUresult result;

  result = cuModuleLoadData(&module, kernel);
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to load the module." << std::endl;
    return 1;
  }

  result = cuModuleGetFunction(&function, module, "kernel");
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to get the function." << std::endl;
    return 1;
  }

  // Do something with the function
  // ...
  return 0;
}

Add Error Management

Sometimes, the PTX code may contain errors, or the process fails for some reasons. To handle this, you can use CUjit_option get more information about the error. Here is an example:

#include 
#include 

// PTX code generated by:
// nvcc -ptx -o kernel.ptx kernel.cu
const char* kernel = R"(
  .version 6.5
  .target sm_70
  .address_size 64

  .visible .entry kernel(
    .param .u64 kernel_param_0
  )
  {
    // Kernel code here
  }
)";

int main() {

  cuInit(0);

  // select the first device
  CUdevice device;
  cuDeviceGet(&device, 0);

  CUcontext context;
  cuCtxCreate(&context, 0, device);

  CUmodule module;
  CUfunction function;
  CUresult result;

  int logBufferSize = 1024;
  char infoLogBuffer[1024];
  char errorLogBuffer[1024];
  CUjit_option options[] = {CU_JIT_INFO_LOG_BUFFER_SIZE_BYTES, CU_JIT_INFO_LOG_BUFFER,
                            CU_JIT_ERROR_LOG_BUFFER_SIZE_BYTES, CU_JIT_ERROR_LOG_BUFFER};
  void* optionValues[] = {(void*)(uintptr_t)logBufferSize, infoLogBuffer,
                          (void*)(uintptr_t)logBufferSize, errorLogBuffer}; 

  result = cuModuleLoadDataEx(&module, kernel, 4, options, optionValues);
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to load the module." << std::endl;
    std::cerr << "CUDA Driver API error = " << result << std::endl;
    std::cerr << "Info Log: " << infoLogBuffer << std::endl;
    std::cerr << "Error Log: " << errorLogBuffer << std::endl;
    return 1;
  }

  result = cuModuleGetFunction(&function, module, "kernel");
  if (result != CUDA_SUCCESS) {
    std::cerr << "Failed to get the function." << std::endl;
    return 1;
  }

  // Do something with the function
  // ...
  return 0;
}

One last suggestion: If your kernel is a simple kernel not requiring any special optimization, you can create the PTX code for an old architecture like sm_50, so that it can be used on any GPU (well, most of them!).

nvcc -ptx -o kernel.ptx -arch=sm_50 kernel.cu

P.S. Pay attention to the entry .version 6.5 in the PTX code. If your target system’s PTX assembler is old, you’ll get runtime error. You may want to edit that field manually, as I didn’t find a way to set it automatically.

Collection of my dotfiles (public version)

2024-10-15T00:00:00-04:00

This is a collection of my dotfiles that I use on my Linux system. I have written about them in various posts, but I thought I can put them all in one place. You can checkout the github repository here, too.

File Tree

Click on each file to see the content.

Some notes

File	Location	Description
`.bashrc`	`~/`	Bash configuration file
`.clang-format`	`/path/to/a/project/`	Clang-format configuration file for clang-format
`.git-prompt.sh`	`~/`	Git prompt configuration file which is used in `.bashrc`
`.gitconfig`	`~/`	Git configuration file
`.inputrc`	`~/`	Inputrc configuration file
`.ssh/config`	`~/.ssh/`	SSH configuration file
`.tmux.conf`	`~/`	Tmux configuration file
`.vimrc`	`~/`	Vim configuration file
`.vscode/sftp.json`	`/usually/a/repo/.vscode/`	A configuration file for VSCode SFTP extension
`Latex/defaultSettings.yaml`	`/the/path/in/indentconfig.yaml`	Default settings for latexindent program
`Latex/indentconfig.yaml`	`~/`	Configuration file for latexindent program

Tmux Tips and Tricks

2024-09-27T00:00:00-04:00

(If you are already familiar with tmux, and you are looking for a simple .tmux.conf, go to the end of this post.)

It’s been a long time since I wanted to start using tmux to see how it could be helpful, but Honestly, I haven’t felt the need to use it until just recently, when I had to run a long-running process on a remote server, and I didn’t want to keep my terminal open all the time. So, I decided to give tmux a try. And I’m glad I did! It’s a powerful tool that can help you manage multiple terminal sessions in a single window, and more. Here are some tips and tricks that I found useful.

For getting started, you can check tmux official documentation. Also, this one is a good cheat sheet. For the aweseome list of tmux resources, you can check this.

About `tmux`

tmux is a terminal multiplexer that allows you to run multiple terminal sessions in a single window. It’s similar to screen, but it has some additional features that make it more powerful and easier to use. With tmux, you can create multiple windows and panes, detach from a session and reattach later, and share sessions with other users.

tmux handles everything by a server-client model. The server runs in the background and manages all the sessions, windows, and panes. The client is the terminal that you interact with. You can have multiple clients connected to the same server.

To install tmux on your system:

# Ubuntu
sudo apt install tmux

Using tmux basics

I have provided some basic commands in this section, but in the following sections, I have provided the shortcuts and commands that you can use inside tmux. Also, I skipped writing about tmux commands in the status bar (similar to vim commands). If you want to see those, visit the cheat sheet I mentioned above. However, you can enter tmux command mode by pressing Ctrl+b :.

One useful command is : set mouse on to enable the mouse in tmux. You can enable it for all the sessions by adding -g to the command. (tmux set -g mouse on). To disable mouse, you can use : set mouse off.

Ok, back to the basics:

List all sessions with tmux ls
Start a new session with a name: tmux new -s mySession
Attach to a session:

tmux attach -t mySession
# or short
tmux a -t mySession
# Attach to the last session
tmux a

Detach from a session running tmux detach or pressing Ctrl+b d in the session.
Kill a session with tmux kill-session -t mySession.

Inside tmux

All commands in tmux start with Ctrl+b followed by another key (Unless the prefix key is changed in the configuration file). To see the full list of commands, you can press Ctrl+b followed by ?. The documents use the format C-b to represent the Ctrl+b key combination. Also, M- represents the Alt+ combination, and S- shows the Shift+ combination.

Customizing tmux

One of the beauties of tmux is that you can customize it very easily. You can create a .tmux.conf file in your home directory and add your custom configurations, from changing the default key bindings to setting the colors of the status bar. Here is a simple .tmux.conf file:

# Set the prefix key to Ctrl+a -> people usually use this key binding
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Start windows and panes at 1, not 0
# Why you ask?! because 0 is pretty far away on the keyboard
set -g base-index 1
setw -g pane-base-index 1

# Enable mouse support
set -g mouse on

# Set the status bar colors
set -g status-bg black
set -g status-fg white

# Set the splitting commands, | for horizontal and - for vertical
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
unbind '"'
unbind %

# open new windows in the current path
bind c new-window -c "#{pane_current_path}"

# reload config file
bind r source-file ~/.tmux.conf

# Use Alt-arrow keys without prefix key to switch panes
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# set default terminal mode to 256 colors
set -g default-terminal "xterm-256color"
set -ga terminal-overrides ",xterm-256color:Tc"

# Visual bell, no sounds
set -g visual-bell on
set -g bell-action none

Managing tmux windows and sessions

After updating the .tmux.conf file, follow the table below:

Command	Description
`Ctrl+a w`	List all windows
`Ctrl+a w 0-9`	Switch to window 0-9
`Ctrl+a c`	Create a new window
`Ctrl+a &`	Close the current window
`Ctrl+a n`	Move to the next window
`Ctrl+a p`	Move to the previous window
`Ctrl+a ,`	Rename the current window
`Ctrl+a -`	Split the window vertically
`Ctrl+a \\|`	Split the window horizontally
`Ctrl+a d`	Detach from the session
`Ctrl+a s`	List all sessions
`Ctrl+a $`	Rename the current session

Moving and resizing panes

After updating the .tmux.conf file to the content above, the commands from the following table can be used:

Command	Description
`Ctrl+a o`	Move to the next pane
`Ctrl+a ;`	Move to the last active pane
`Ctrl+a q`	Show pane numbers
`Ctrl+a q`	Activate the pane with the specified number
`Ctrl+a x`	Kill the current pane
`Ctrl+a z`	Zoom in/out the current pane
`Ctrl+a !`	Move the current pane to a new window
`Ctrl+a Up`	Switch to the pane above the active pane
`Alt+Up`	Switch to the pane above the active pane (another way)
`Ctrl+a Down`	Switch to the pane below the active pane
`Alt+Down`	Switch to the pane below the active pane (another way)
`Ctrl+a Left`	Switch to the pane on the left of the active pane
`Alt+Left`	Switch to the pane on the left of the active pane (another way)
`Ctrl+a Right`	Switch to the pane on the right of the active pane
`Alt+Right`	Switch to the pane on the right of the active pane (another way)
`Ctrl+a }`	Move the current pane right
`Ctrl+a {`	Move the current pane left
`Ctrl+a Ctrl+Up`	Resize the current pane up
`Ctrl+a Ctrl+Down`	Resize the current pane down
`Ctrl+a Ctrl+Left`	Resize the current pane left
`Ctrl+a Ctrl+Right`	Resize the current pane right

Automatic Startup

You can start tmux automatically when you open a terminal. To do this, add the following line to your .bashrc file:

# Start tmux if not already running
if [ -z "$TMUX" ]; then
    tmux attach || tmux new
fi

If you want to start tmux with a specific session, you can use the following command:

# Start tmux with a specific session
if [ -z "$TMUX" ]; then
    tmux attach -t mySession || tmux new -s mySession
fi

Fun Part

Now for the fun part, I have created some aliases to make it easier to manage tmux and its sessions. You can add these aliases to the .bashrc file:

# tmux aliases
alias ta='tmux attach -t'
alias tk='tmux kill-session -t'
alias tls='tmux ls'
alias tn='tmux new -s'
alias ttop='tmux attach -t top || tmux new -s top "top"'

# managing ssh sessions to remote servers
# First check if the session exists, if not create a new one and ssh to the server
# You can then later split the window and do whatever you want with the session, then detach and reattach later
alias tpprl='tmux attach -t pprl || tmux new -s pprl "ssh pprl"'
alias tmist='tmux attach -t mist || tmux new -s mist "ssh mist"'
alias tnarval='tmux attach -t narval || tmux new -s narval "ssh narval"'
alias tbeluga='tmux attach -t beluga || tmux new -s beluga "ssh beluga"'
alias tgraham='tmux attach -t graham || tmux new -s graham "ssh graham"'

# List all tmux sessions and windows at login
echo "Available tmux sessions:"
tmux ls

Another fun usecase: You may also combine the tmux session management with ssh control path to avoid getting 2FA prompts every time you connect to a server. You can check Ali’s post to understand the process.

References

A nice tmux conf file
Tmux official guide
Tmux cheat sheet
Awesome tmux resources
Oh my tmux!

Setup LAMMPS

2024-09-09T00:00:00-04:00

Large-scale Atomic/Molecular Massively Parallel Simulator (LAMMPS) is a classical molecular dynamics code that can be used to model atoms or, more generally, as a parallel particle simulator at various scales. The complete documentation of LAMMPS can be found here. In this post, I will provide a guide on how to setup LAMMPS on a Linux machine. My setup is on a cluster with NVIDIA GPUs, UCX, and OpenMPI. Also, we have a built-in module system to load the necessary modules.

Prepare the Environment

Prerequisites:

Git
CMake
An MPI library, like OpenMPI
For NVIDIA GPU support, CUDA Toolkit is needed.

While this step maybe different in various scenarios, I have the following environment variables set:

#! /bin/bash
module --force purge
module load cuda

# If the argument is "builtin" then load the builtin modules, otherwise don't load any other modules
if [ "$#" -eq 1 ] && [ "$1" == "builtin" ]; then
  echo "using builtin modules"
  module load ucx
  module load openmpi
  module list
  echo "Built-in modules loaded"
  return
fi

echo "No additional modules loaded"
module list

# If no argument is passed, set the root dir to the current directory,
# else set it to the passed argument
if [ "$#" -eq 0 ]; then
  export ROOT_DIR=$(pwd)
else
  export ROOT_DIR=$1
fi

export BUILD_DIR=$ROOT_DIR/build

################### Some checks ###################

# Check if LDFLAGS is bound or not
if [ -z ${LDFLAGS+x} ]; then
  export LDFLAGS=""
fi

# Same with LD_RUN_PATH
if [ -z ${LD_RUN_PATH+x} ]; then
  export LD_RUN_PATH=""
fi

# Same with CXXFLAGS
if [ -z ${CXXFLAGS+x} ]; then
  export CXXFLAGS=""
fi

# Same with LIBRARY_PATH
if [ -z ${LIBRARY_PATH+x} ]; then
  export LIBRARY_PATH=""
fi

# Same with LD_LIBRARY_PATH
if [ -z ${LD_LIBRARY_PATH+x} ]; then
  export LD_LIBRARY_PATH=""
fi

################### CUDA Configurations ###################

# CUDA Configurations (mostly needed to build OpenMPI and UCX)
export NVCC=$(which nvcc)
export CUDA_LIB=$CUDA_HOME/lib64/stubs

export LD_LIBRARY_PATH=$CUDA_HOME/lib64/:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$CUDA_LIB:$LD_LIBRARY_PATH

export LIBRARY_PATH=$CUDA_HOME/lib64/:$LIBRARY_PATH
export LIBRARY_PATH=$CUDA_LIB:$LIBRARY_PATH

export LDFLAGS="-L$CUDA_LIB -L$CUDA_HOME/lib64 $LDFLAGS"
export CPATH=$CUDA_HOME/include:$CPATH
export LD_RUN_PATH=$CUDA_LIB:$LD_RUN_PATH
export CUDA_LDFLAGS="-lcuda -lcudart -lcudadevrt -lnvidia-ml -L$CUDA_LIB"

export LD_LIBRARY_PATH=$BUILD_DIR/lib:$LD_LIBRARY_PATH
export LIBRARY_PATH=$BUILD_DIR/lib:$LIBRARY_PATH
export LDFLAGS="-L$BUILD_DIR/lib $LDFLAGS"

export CPATH=$BUILD_DIR/include:$CPATH
export LD_RUN_PATH=$BUILD_DIR/lib:$LD_RUN_PATH
export PATH=$BUILD_DIR/bin/:$PATH

# Now UCX and OpenMPI can be built

I have skipped the UCX and OpenMPI configurations, but you can find them in my previous posts or in their official documentation.

Build LAMMPS

The following script clones the LAMMPS repository, builds it, and runs some benchmarks. For more information about the available packages, you can check the LAMMPS documentation.

#!/bin/bash
set -eux

export OPENMPI_DIR="/path/to/openmpi"
source "the_above_script.sh" $OPENMPI_DIR

# Check the paths of the executables
which nvcc
which mpicc
which mpirun

export LAMMPS_DIR="/path/to/lammps"

# Perform a clean clone
rm -rf $LAMMPS_DIR
git clone --depth=1 -b release https://github.com/lammps/lammps.git $LAMMPS_DIR
cd $LAMMPS_DIR

# Build LAMMPS
mkdir -p $LAMMPS_DIR/build
cd $LAMMPS_DIR/build

cmake -D CMAKE_BUILD_TYPE=Release -D CMAKE_INSTALL_PREFIX=$LAMMPS_DIR/build \
  -D PKG_KSPACE=1 -D PKG_MOLECULE=1 -D PKG_RIGID=1 -D PKG_MANYBODY=1 \
  -D CMAKE_CXX_FLAGS=-DCUDA_PROXY -D BUILD_MPI=1 -D PKG_GPU=1 -D GPU_API=CUDA \
  -D CUDA_MPS_SUPPORT=1 $LAMMPS_DIR/cmake

cmake --build . --parallel 32

# Some tests
# mpirun -n 8 --mca pml ucx -x UCX_TLS=sm,cuda_copy,cuda_ipc --mca btl ^vader,tcp,openib \
#   --mca coll ^hcoll ../lammps/build/lmp -sf gpu -pk gpu 4 -in ../lammps/bench/in.eam
# mpirun -n 8 --mca pml ucx -x UCX_TLS=sm,cuda_copy,cuda_ipc --mca btl ^vader,tcp,openib \
#   --mca coll ^hcoll ../lammps/build/lmp -sf gpu -pk gpu 1 -in ../lammps/bench/in.chain
# mpirun -n 32 --mca pml ucx -x UCX_TLS=sm,cuda_copy,cuda_ipc --mca btl ^vader,tcp,openib \
#   --mca coll ^hcoll ../lammps/build/lmp -sf gpu -pk gpu 4 -in ../lammps/bench/in.lj

MPS on Multi-Instance GPU

2024-08-28T00:00:00-04:00

In previous posts, (MPS and MIG), I have explained how to enable MPS and MIG on NVIDIA GPUs. In this post, I will explain how to use both technologies at the same time. In more detail, I would like to enable MPS on all of the MIG instances. For more information, you can refer to the NVIDIA document.

Enabling MPS on MIG

I assume that you have already enabled MIG on your GPU(s). If not, please refer to the previous posts. As stated in the NVIDIA document, the steps for configuring MPS on MIG is as follows:

Configure the desired MIG geometry on the GPU.
Setup the CUDA_MPS_PIPE_DIRECTORY variable to point to unique directories so that the multiple MPS servers and clients can communicate with each other using named pipes and Unix domain sockets.
Launch the application by specifying the MIG device using CUDA_VISIBLE_DEVICES. , <– This one might be unnecessary if you point to the correct MPS server using CUDA_MPS_PIPE_DIRECTORY.

To enable MPS on MIG, I wrote a simple script that does the above steps. The script is as follows:

#!/bin/bash

set -eux

# GPU_UUIDs=($(nvidia-smi -L | grep -oE "(GPU|MIG)-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*"))
GPU_UUIDs=($(nvidia-smi -L | grep -oE "(MIG)-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*"))

for ((index = 0; index < ${#GPU_UUIDs[@]}; index++)); do
  GPU=${GPU_UUIDs[index]}
  rm -rf /tmp/mps_${GPU}
  rm -rf /tmp/mps_log_${GPU}
  mkdir /tmp/mps_${GPU}
  mkdir /tmp/mps_log_${GPU}
  # Skip setting the GPU compute mode to Exclusive Process (not supported on MIG-enabled GPUs)
  # nvidia-smi -i $index -c EXCLUSIVE_PROCESS
  export CUDA_VISIBLE_DEVICES=${GPU}
  export CUDA_MPS_PIPE_DIRECTORY=/tmp/mps_${GPU}
  export CUDA_MPS_LOG_DIRECTORY=/tmp/mps_log_${GPU}
  nvidia-cuda-mps-control -d
done

ps -ef | grep mps

In summary, the script does the following:

getting the UUIDs of the MIG instances.
creating unique directories for each MIG instance.
setting the CUDA_VISIBLE_DEVICES to the MIG instance.
setting the CUDA_MPS_PIPE_DIRECTORY and CUDA_MPS_LOG_DIRECTORY to the unique directories.
enabling MPS server on the specified MIG instance.
repeating the steps for all the MIG instances.
And at the end, listing the MPS processes.

Disabling MPS on MIG

To disable MPS on MIG, you can use the following script:

#!/bin/bash

set -eux

# GPU_UUIDs=($(nvidia-smi -L | grep -oE "(MIG|GPU)-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*"))
GPU_UUIDs=($(nvidia-smi -L | grep -oE "(MIG)-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*-[0-9a-f]*"))

for ((index = 0; index < ${#GPU_UUIDs[@]}; index++)); do
  GPU=${GPU_UUIDs[index]}
  export CUDA_VISIBLE_DEVICES=${GPU}
  export CUDA_MPS_PIPE_DIRECTORY=/tmp/mps_${GPU}
  export CUDA_MPS_LOG_DIRECTORY=/tmp/mps_log_${GPU}
  echo "quit" | nvidia-cuda-mps-control
  rm -rf /tmp/mps_log_${GPU}
  rm -rf /tmp/mps_${GPU}
  # Reset the GPU compute mode to Default (not supported on MIG-enabled GPUs)
  # nvidia-smi -i $index -c DEFAULT
done

ps -ef | grep mps

In summary, the script does the following:

getting the UUIDs of the MIG instances.
setting the CUDA_VISIBLE_DEVICES to the MIG instance.
setting the CUDA_MPS_PIPE_DIRECTORY and CUDA_MPS_LOG_DIRECTORY to the unique directories.
disabling MPS server on the specified MIG instance.
removing the directories.
repeating the steps for all the MIG instances.
And at the end, listing the MPS processes which should be none.

Notice that the script does not destroy MIG configuration, and the GPUs will still be in MIG mode. If you want to see how to disable MIG, please refer to the previous post.

Example

I have created 2 GPU instances each with 2 compute instances on my A30 GPU. This is how it looks like:

$ nvidia-smi -L
GPU 0: NVIDIA A30 (UUID: GPU-8f8bff94-112e-9541-43da-cfd453333404)
  MIG 1c.2g.12gb  Device  0: (UUID: MIG-22f0c05f-5cf2-5ea2-8297-789695656dc0)
  MIG 1c.2g.12gb  Device  1: (UUID: MIG-d74dcafc-aad0-58b8-83d8-61bcd963d2e9)
  MIG 1c.2g.12gb  Device  2: (UUID: MIG-27be287f-e2db-5526-a2f6-0bfabcf34af9)
  MIG 1c.2g.12gb  Device  3: (UUID: MIG-235f71be-a125-5ce0-9fe6-0cd97ae57733)
GPU 1: NVIDIA A30 (UUID: GPU-0783f1eb-ab00-d6ec-92e4-8676be77de38)
GPU 2: NVIDIA A30 (UUID: GPU-a90c6e94-391e-0fc3-8fc5-e2ef46ec6d2d)
GPU 3: NVIDIA A30 (UUID: GPU-46d1eefe-dfc8-2f00-16a9-95c08e019d47)

$ nvidia-smi
Wed Aug 28 17:07:36 2024
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 545.23.08              Driver Version: 545.23.08    CUDA Version: 12.3     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA A30                     On  | 00000000:17:00.0 Off |                   On |
| N/A   28C    P0              30W / 165W |     50MiB / 24576MiB |     N/A      Default |
|                                         |                      |              Enabled |
+-----------------------------------------+----------------------+----------------------+
|   1  NVIDIA A30                     On  | 00000000:65:00.0 Off |                    0 |
| N/A   28C    P0              30W / 165W |      4MiB / 24576MiB |      0%      Default |
|                                         |                      |             Disabled |
+-----------------------------------------+----------------------+----------------------+
|   2  NVIDIA A30                     On  | 00000000:CA:00.0 Off |                    0 |
| N/A   27C    P0              31W / 165W |      4MiB / 24576MiB |      0%      Default |
|                                         |                      |             Disabled |
+-----------------------------------------+----------------------+----------------------+
|   3  NVIDIA A30                     On  | 00000000:E3:00.0 Off |                    0 |
| N/A   28C    P0              32W / 165W |      4MiB / 24576MiB |      0%      Default |
|                                         |                      |             Disabled |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| MIG devices:                                                                          |
+------------------+--------------------------------+-----------+-----------------------+
| GPU  GI  CI  MIG |                   Memory-Usage |        Vol|      Shared           |
|      ID  ID  Dev |                     BAR1-Usage | SM     Unc| CE ENC DEC OFA JPG    |
|                  |                                |        ECC|                       |
|==================+================================+===========+=======================|
|  0    1   0   0  |              25MiB / 11968MiB  | 14      0 |  2   0    2    0    0 |
|                  |               0MiB / 16383MiB  |           |                       |
+------------------+                                +-----------+-----------------------+
|  0    1   1   1  |                                | 14      0 |  2   0    2    0    0 |
|                  |                                |           |                       |
+------------------+--------------------------------+-----------+-----------------------+
|  0    2   0   2  |              25MiB / 11968MiB  | 14      0 |  2   0    2    0    0 |
|                  |               0MiB / 16383MiB  |           |                       |
+------------------+                                +-----------+-----------------------+
|  0    2   1   3  |                                | 14      0 |  2   0    2    0    0 |
|                  |                                |           |                       |
+------------------+--------------------------------+-----------+-----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+

Here is the output of ps -ef | grep mps after running the enabling MPS on MIG script (with sudo):

$ ps -ef | grep mps
root      241318       1  0 17:08 ?        00:00:00 nvidia-cuda-mps-control -d
root      241326       1  0 17:08 ?        00:00:00 nvidia-cuda-mps-control -d
root      241334       1  0 17:08 ?        00:00:00 nvidia-cuda-mps-control -d
root      241342       1  0 17:08 ?        00:00:00 nvidia-cuda-mps-control -d

# And the content of tmp directory
$ ls -l /tmp/
total 0
drwxr-xr-x 2 root   root   120 Aug 28 17:08 mps_MIG-22f0c05f-5cf2-5ea2-8297-789695656dc0
drwxr-xr-x 2 root   root   120 Aug 28 17:08 mps_MIG-235f71be-a125-5ce0-9fe6-0cd97ae57733
drwxr-xr-x 2 root   root   120 Aug 28 17:08 mps_MIG-27be287f-e2db-5526-a2f6-0bfabcf34af9
drwxr-xr-x 2 root   root   120 Aug 28 17:08 mps_MIG-d74dcafc-aad0-58b8-83d8-61bcd963d2e9
drwxr-xr-x 2 root   root    80 Aug 28 17:08 mps_log_MIG-22f0c05f-5cf2-5ea2-8297-789695656dc0
drwxr-xr-x 2 root   root    80 Aug 28 17:08 mps_log_MIG-235f71be-a125-5ce0-9fe6-0cd97ae57733
drwxr-xr-x 2 root   root    80 Aug 28 17:08 mps_log_MIG-27be287f-e2db-5526-a2f6-0bfabcf34af9
drwxr-xr-x 2 root   root    80 Aug 28 17:08 mps_log_MIG-d74dcafc-aad0-58b8-83d8-61bcd963d2e9

Now, you can run your application on the MIG instances with MPS enabled. For example, you can run the following command to run the deviceQuery:

  CUDA_MPS_PIPE_DIRECTORY=/tmp/mps_MIG-22f0c05f-5cf2-5ea2-8297-789695656dc0 \
  CUDA_MPS_LOG_DIRECTORY=/tmp/mps_log_MIG-22f0c05f-5cf2-5ea2-8297-789695656dc0 \
  ./deviceQuery

After I ran the deviceQuery on all the MIG isntances with the correct PIPE and LOG directories, this is the output of nvidia-smi:

$ nvidia-smi
...
+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|    0    1    0     241923      C   nvidia-cuda-mps-server                       30MiB |
|    0    1    1     254870      C   nvidia-cuda-mps-server                       30MiB |
|    0    2    0     249932      C   nvidia-cuda-mps-server                       30MiB |
|    0    2    1     242189      C   nvidia-cuda-mps-server                       30MiB |
+---------------------------------------------------------------------------------------+

Notice the GI IDs and CI IDs, and how each of them has its own MPS server. It’s worth mentioning that MPS servers are started in a lazy fashion. So if you don’t run any application, the MPS server will not be started.

Btw, I didn’t see any difference in the behaviour of the application when passing CUDA_VISIBLE_DEVICES to the command. It seems that the CUDA_MPS_PIPE_DIRECTORY is enough to point to the correct MPS server. However, setting CUDA_VISIBLE_DEVICES is a good practice to avoid any confusion, as setting it to a wrong value will cause the application to return an error.

Wasm + WebGPU example on DCP

2024-06-20T00:00:00-04:00

This example is a follow-up to my previous post on how to write a cross-platform WebGPU example. In this one, I’ll demonstrate how to deploy a matmult example written in C/C++ and WebGPU in a DCP worker using WASM. Note that for verification purposes, I provide dawn-based native test, too, but this example doesn’t need to build/install dawn in order to work.

What is DCP?

DCP is a secure, and powerful parallel computing platform built on the web technology. For more information, take a look at here.

This example

We will experiment with a matrix multiplication in C/C++ using WebGPU. The matrices are stored in a 1D array, with their dimensions as their first and second elements, and their data stored afterwards. For this example to work, we have three options:

Build to run natively using dawn
Build to run as a web worker using emscripten
Build to run as a DCP workload using emscripten <– we are interested in this one!

Code structure

By the end of the build process, the directory structure should look like this:

.
├── clean-and-build.sh
├── deployJob.js
├── node_modules
│   └── ...
├── package
│   ├── build-web
│   │   ├── wasm-webgpu-matmult.js
│   │   └── ...
│   ├── CMakeLists.txt
│   ├── package.dcp
│   └── src
│       ├── closebravo.js
│       ├── index.html
│       ├── openbravo.js
│       └── wasm-webgpu-matmult.cpp
├── package.json
├── package-lock.json
├── README.md
└── updateVersion.js

The source ./package/src/wasm-webgpu-matmult.cpp is similar to the source from the previous post:

#include 
#include 
#include 
#include 
#include 

#ifdef __EMSCRIPTEN__
#include 
#endif

wgpu::Instance instance;
wgpu::Adapter adapter;
wgpu::Device device;

wgpu::Buffer gpuReadBuffer;
size_t resultMatrixSize;
bool work_done = false;

// GetAdapter gets a callback function that it's get called
// after the RequestAdapter resolves.
void GetAdapter(void (*callback)()) {
  instance.RequestAdapter(
      nullptr,
      [](WGPURequestAdapterStatus status, WGPUAdapter cAdapter,
         const char *message, void *userdata) {
        if (message) {
          std::cout << "RequestAdapter message: " << message << std::endl;
        }
        if (status != WGPURequestAdapterStatus_Success) {
          std::cout << "AdapterRequest was not successfull" << std::endl;
          exit(0);
        }
        adapter = wgpu::Adapter::Acquire(cAdapter);
        // (2) Cast userdata back to the callback and then call it
        reinterpret_cast<void (*)()>(userdata)();
      },
      // (1) Cast the call back to void pointer and pass it in
      reinterpret_cast<void *>(callback));
}

// Similar to GetAdapter, the callback is called when RequestDevice resolves
void GetDevice(void (*callback)()) {
  adapter.RequestDevice(
      nullptr,
      [](WGPURequestDeviceStatus status, WGPUDevice cDevice,
         const char *message, void *userdata) {
        if (message) {
          std::cout << "RequestDevice message: " << message << std::endl;
        }
        if (status != WGPURequestDeviceStatus_Success) {
          std::cout << "AdapterRequest was not successfull" << std::endl;
          exit(0);
        }
        device = wgpu::Device::Acquire(cDevice);
        device.SetUncapturedErrorCallback(
            [](WGPUErrorType type, const char *message, void *userdata) {
              std::cout << "Error: " << type << " - message: " << message;
            },
            nullptr);
        // (2) Cast userdata back to the callback and then call it
        reinterpret_cast<void (*)()>(userdata)();
      },
      // (1) Cast the call back to void pointer and pass it in
      reinterpret_cast<void *>(callback));
}

const char shaderCode[] = R"(
    struct Matrix {
        size : vec2,
        numbers: array,
    };

    @group(0) @binding(0) var firstMatrix : Matrix;
    @group(0) @binding(1) var secondMatrix : Matrix;
    @group(0) @binding(2) var resultMatrix : Matrix;

    @compute @workgroup_size(8, 8)
    fn main(@builtin(global_invocation_id) global_id : vec3) {
        // Guard against out-of-bounds work group sizes
        if (global_id.x >= u32(firstMatrix.size.x) || global_id.y >= u32(secondMatrix.size.y)) {
            return;
        }

        resultMatrix.size = vec2(firstMatrix.size.x, secondMatrix.size.y);

        let resultCell = vec2(global_id.x, global_id.y);
        var result = 0.0;
        for (var i = 0u; i < u32(firstMatrix.size.y); i = i + 1u) {
            let a = i + resultCell.x * u32(firstMatrix.size.y);
            let b = resultCell.y + i * u32(secondMatrix.size.y);
            result = result + firstMatrix.numbers[a] * secondMatrix.numbers[b];
        }

        let index = resultCell.y + resultCell.x * u32(secondMatrix.size.y);
        resultMatrix.numbers[index] = result;
    }
)";

// This callback is called when the last mapAsync is resolved
void BufferMapCallbackFunction(WGPUBufferMapAsyncStatus status,
                               void *userdata) {

  std::cout << "In Buffer async call back, status: " << status << std::endl;

  if (status == WGPUBufferMapAsyncStatus_Success) {
    const float *resultData = static_cast<const float *>(
        gpuReadBuffer.GetConstMappedRange(0, resultMatrixSize));

    std::cout << "Result Matrix: " << std::endl;
    for (int i = 0; i < resultMatrixSize / sizeof(float); i++) {
      std::cout << resultData[i] << " ";
    }
    std::cout << std::endl;

    gpuReadBuffer.Unmap();
  } else {
    std::cout << "Failed to map result buffer" << std::endl;
  }
  *reinterpret_cast<bool *>(userdata) = true;
}

void RunMatMult() {
  // First Matrix
  const std::vector<float> firstMatrix = {2, 4, 1, 2, 3, 4, 5, 6, 7, 8};
  size_t firstMatrixSize = firstMatrix.size() * sizeof(float);

  wgpu::Buffer gpuBufferFirstMatrix =
      device.CreateBuffer(new wgpu::BufferDescriptor{
          .usage = wgpu::BufferUsage::Storage,
          .size = firstMatrixSize,
          .mappedAtCreation = true,
      });
  std::memcpy(gpuBufferFirstMatrix.GetMappedRange(), firstMatrix.data(),
              firstMatrixSize);
  gpuBufferFirstMatrix.Unmap();

  std::cout << "First Matrix: " << std::endl;
  std::copy(firstMatrix.begin(), firstMatrix.end(),
            std::ostream_iterator<float>(std::cout, " "));
  std::cout << std::endl;

  // Second Matrix
  const std::vector<float> secondMatrix = {4, 2, 1, 2, 3, 4, 5, 6, 7, 8};
  size_t secondMatrixSize = secondMatrix.size() * sizeof(float);

  wgpu::Buffer gpuBufferSecondMatrix =
      device.CreateBuffer(new wgpu::BufferDescriptor{
          .usage = wgpu::BufferUsage::Storage,
          .size = secondMatrixSize,
          .mappedAtCreation = true,
      });
  std::memcpy(gpuBufferSecondMatrix.GetMappedRange(), secondMatrix.data(),
              secondMatrixSize);
  gpuBufferSecondMatrix.Unmap();

  std::cout << "Second Matrix: " << std::endl;
  std::copy(secondMatrix.begin(), secondMatrix.end(),
            std::ostream_iterator<float>(std::cout, " "));
  std::cout << std::endl;

  // Result Matrix
  resultMatrixSize =
      sizeof(float) * (2 + static_cast<size_t>(firstMatrix[0]) *
                               static_cast<size_t>(secondMatrix[1]));

  wgpu::Buffer resultMatrixBuffer =
      device.CreateBuffer(new wgpu::BufferDescriptor{
          .usage = wgpu::BufferUsage::Storage | wgpu::BufferUsage::CopySrc,
          .size = resultMatrixSize,
      });

  // Compute shader code
  wgpu::ShaderModuleWGSLDescriptor shaderModuleDesc = {};
  shaderModuleDesc.code = shaderCode;
  wgpu::ShaderModuleDescriptor shaderModuleDescriptor{.nextInChain =
                                                          &shaderModuleDesc};
  wgpu::ShaderModule shaderModule =
      device.CreateShaderModule(&shaderModuleDescriptor);
  // Pipeline setup
  wgpu::ComputePipelineDescriptor pipelineDesc = {};
  pipelineDesc.compute.module = shaderModule;
  pipelineDesc.compute.entryPoint = "main";

  wgpu::ComputePipeline computePipeline =
      device.CreateComputePipeline(&pipelineDesc);

  // Bind group
  wgpu::BindGroupDescriptor bindGroupDesc = {};
  wgpu::BindGroupEntry entries[3] = {};
  entries[0].binding = 0;
  entries[0].buffer = gpuBufferFirstMatrix;
  entries[1].binding = 1;
  entries[1].buffer = gpuBufferSecondMatrix;
  entries[2].binding = 2;
  entries[2].buffer = resultMatrixBuffer;
  bindGroupDesc.entryCount = 3;
  bindGroupDesc.entries = entries;
  bindGroupDesc.layout = computePipeline.GetBindGroupLayout(0);

  wgpu::BindGroup bindGroup = device.CreateBindGroup(&bindGroupDesc);

  // Commands submission
  wgpu::CommandEncoder commandEncoder = device.CreateCommandEncoder();

  wgpu::ComputePassEncoder passEncoder = commandEncoder.BeginComputePass();
  passEncoder.SetPipeline(computePipeline);
  passEncoder.SetBindGroup(0, bindGroup);
  uint32_t workgroupCountX =
      static_cast<uint32_t>(std::ceil(firstMatrix[0] / 8.0f));
  uint32_t workgroupCountY =
      static_cast<uint32_t>(std::ceil(secondMatrix[1] / 8.0f));
  passEncoder.DispatchWorkgroups(workgroupCountX, workgroupCountY);
  passEncoder.End();

  // Get a GPU buffer for reading in an unmapped state
  gpuReadBuffer = device.CreateBuffer(new wgpu::BufferDescriptor{
      .usage = wgpu::BufferUsage::CopyDst | wgpu::BufferUsage::MapRead,
      .size = resultMatrixSize,
  });

  // Encode commands for copying buffer to buffer
  commandEncoder.CopyBufferToBuffer(resultMatrixBuffer, 0, gpuReadBuffer, 0,
                                    resultMatrixSize);

  // Submit GPU commands
  wgpu::CommandBuffer commands = commandEncoder.Finish();
  device.GetQueue().Submit(1, &commands);

  std::cout << "Commands submitted to the GPU Queue" << std::endl;

  gpuReadBuffer.MapAsync(wgpu::MapMode::Read, (size_t)0, resultMatrixSize,
                         BufferMapCallbackFunction,
                         reinterpret_cast<void *>(&work_done));
}

// The content of this function could be in the main()
// I wrote it like this to show how the function export works in emscripten 
// Also, we can pass necessary arguements easier from JS side. 
extern "C" {
void RunMatMultWrapper() {
  instance = wgpu::CreateInstance();

  GetAdapter([]() {
    std::cout << "GPU Adapter acquired." << std::endl;
    GetDevice([]() {
      std::cout << "GPU Device acquired." << std::endl;
      RunMatMult();
    });
  });

  // https://eliemichel.github.io/LearnWebGPU/getting-started/the-command-queue.html#device-polling
#ifdef __EMSCRIPTEN__
  while (!work_done) {
    emscripten_sleep(100);
  }
#else
  while (!work_done) {
    instance.ProcessEvents();
  }
#endif
}
}

int main() {
  RunMatMultWrapper();
  return 0;
}

Requirements

CMake
Emscripten
DCP setup

You can use Emscripten SDK to install all the required tools. Make sure to set environment variables (either in bash or everytime you want to use WASM toolchain)

emsdk install latest
emsdk activate latest
source "/path/to/emsdk/emsdk_env.sh"

To start your DCP journey, go to here.

Build and Run

The current example is tested with Emscripten 3.1.61 (for DCP) and dawn chrome/6562 (as standalone).

Build

You can build the project using ./clean-and-build.sh script with these options:

DCP (to build and deploy the package)
web (to test the the code as a standalone web example)
native (to run the binary file natively, again standalone)

For DCP and web options, the script uses emscripten cmake:

emcmake cmake -B build-web && cmake --build build-web

For native builds, make sure to set the correct address to the dawn directory in the CMakeLists.txt and the script has CMake taking care of building it with:

cmake -B build && cmake --build build -j4

# For debugging, you can add the following option
cmake -DCMAKE_BUILD_TYPE=Debug -B build && cmake --build build -j4

This is the content of the ./clean-and-build.sh script:

#!/bin/bash

set -eux

# Arg could be DCP (default), web, or native
# Default to DCP if no argument is passed
MODE="${1:-DCP}"

BUILD_DIR=package/build
BUILD_WEB_DIR=package/build-web

# Function to prompt the user for confirmation
confirm() {
  local dir="$1"
  read -r -p "Are you sure you want to remove ${dir}? [y/N] " response
  case "$response" in
  [yY][eE][sS] | [yY])
    true
    ;;
  *)
    false
    ;;
  esac
}
# Set CMake options based on the MODE
if [ "$MODE" == "DCP" ]; then
  CMAKE_OPTIONS="-DBUILD_FOR_DCP=ON"
elif [ "$MODE" == "web" ]; then
  echo "Standalone web mode is enabled. Setting DCP to off."
  CMAKE_OPTIONS="-DBUILD_FOR_DCP=OFF"
elif [ "$MODE" == "native" ]; then
  echo "Standalone native mode is enabled. Setting DCP to off."
  CMAKE_OPTIONS="-DBUILD_FOR_DCP=OFF"
else
  echo "No valid option is passed. Options are DCP (default) or local."
  CMAKE_OPTIONS="-DBUILD_FOR_DCP=ON"
  MODE="DCP"
fi

if [ "$MODE" == "native" ]; then
  if confirm "$BUILD_DIR"; then
    echo "Doing a clean build!"
    rm -rf "$BUILD_DIR"
  fi
  cmake -B build -S package -B package/build && cmake --build package/build -j4
else
  if confirm "$BUILD_WEB_DIR"; then
    echo "Doing a clean build!"
    rm -rf "$BUILD_WEB_DIR"
  fi
  emcmake cmake -S package -B package/build-web $CMAKE_OPTIONS &&
    cmake --build package/build-web -- VERBOSE=1
fi

# Run additional commands only if MODE is DCP
if [ "$MODE" == "DCP" ]; then
  node ./updateVersion.js
  npm i -g dcp-client
  publish package package/package.dcp
fi

The ./package/CMakelists.txt file:

cmake_minimum_required(VERSION 3.13)
project(wasm-webgpu-matmult LANGUAGES C CXX)
set(CMAKE_CXX_STANDARD 20)

add_executable(wasm-webgpu-matmult "src/wasm-webgpu-matmult.cpp")

if(EMSCRIPTEN)
  # Create a JS file only, and not the html template file
  set_target_properties(wasm-webgpu-matmult PROPERTIES SUFFIX ".js")

  target_link_options(wasm-webgpu-matmult PRIVATE "-sSINGLE_FILE=1")

  # Enable WebGPU through (webgpu/webgpu.h)
  target_link_options(wasm-webgpu-matmult PRIVATE "-sUSE_WEBGPU=1")

  # Help with printing stack trace, error prevention
  target_link_options(wasm-webgpu-matmult PRIVATE "-sASSERTIONS=1")

  # Enable memory growth at runtime and refrain from throwing exception
  target_link_options(wasm-webgpu-matmult PRIVATE "-sALLOW_MEMORY_GROWTH=1")

  # Disable WASM module generation. (Everything will be in a JS file)
  # So far, passing -sWASM=0 or -sWASM=1 doesn't make any difference :-?
  target_link_options(wasm-webgpu-matmult PRIVATE "-sWASM=1")

  # Whether to support async operations in the compiled code. This makes it
  # possible to call JS functions from synchronous-looking code in C/C++.
  target_link_options(wasm-webgpu-matmult PRIVATE "-sASYNCIFY=1")

  # Enable optimization in code speed and size
  target_link_options(wasm-webgpu-matmult PRIVATE "-O3")

  target_link_options(
    wasm-webgpu-matmult PRIVATE
    "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','callMain']"
  )

  # Symbols that are explicitly exported. These symbols are kept alive through
  # LLVM dead code elimination, and also made accessible outside of the
  # generated code even after running closure compiler (on "Module").  Native
  # symbols listed here require an ``_`` prefix. By default if this setting is
  # not specified on the command line the ``_main`` function will be implicitly
  # exported.  In STANDALONE_WASM mode the default export is ``__start`` (or
  # ``__initialize`` if --no-entry is specified). JS Library symbols can also be
  # added to this list (without the leading `$`). var EXPORTED_FUNCTIONS = [];
  target_link_options(
    wasm-webgpu-matmult PRIVATE
    "-sEXPORTED_FUNCTIONS=['_RunMatMultWrapper','_main']"
  )

  # Whether we will run the main() function. Disable if you embed the generated
  # code in your own, and will call main() yourself at the right time (which you
  # can do with Module.callMain()
  if(BUILD_FOR_DCP)
    target_link_options(wasm-webgpu-matmult PRIVATE "-sINVOKE_RUN=0")
  else()
    target_link_options(wasm-webgpu-matmult PRIVATE "-sINVOKE_RUN=1")
  endif()

  # Specify which runtime environments the JS output will be capable of running
  # in.  For maximum portability this can configured to support all environments
  # or it can be limited to reduce overall code size.
  # var ENVIRONMENT = 'web,webview,worker,node';
  target_link_options(wasm-webgpu-matmult PRIVATE "-sENVIRONMENT=worker")

  # If set to 0, does not build in any filesystem support. Useful if you are
  # just doing pure computation, but not reading files or using any streams
  # (including fprintf, and other stdio.h things) or anything related.
  target_link_options(wasm-webgpu-matmult PRIVATE "-sFILESYSTEM=1")

  if(BUILD_FOR_DCP)
    target_link_options(
      wasm-webgpu-matmult PUBLIC
      "--extern-pre-js=${PROJECT_SOURCE_DIR}/src/openbravo.js"
    )

    target_link_options(
      wasm-webgpu-matmult PUBLIC
      "--extern-post-js=${PROJECT_SOURCE_DIR}/src/closebravo.js"
    )
  endif()
  
else()
  set(DAWN_FETCH_DEPENDENCIES ON)
  add_subdirectory("../../dawn" "build" EXCLUDE_FROM_ALL)
  target_link_libraries(wasm-webgpu-matmult PRIVATE webgpu_cpp webgpu_dawn)
endif()

Test in the browser without DCP

To test the example in the browser without DCP, simply open the file index.html under package/src in the browser.

Make sure to enable WebGPU in your browser first! For instance, if you are on Linux, and your browser is chrome-unstable, pass the necessary options:

google-chrome-unstable --enable-unsafe-webgpu --enable-features=Vulkan \ 
  --disable-dawn-features=disallow_unsafe_apis &

This is the ./package/src/index.html file:

 lang="en">
  
     charset="UTF-8" />
    </span>WASM + WebGPU<span class="nt">
    
    Open the console!

Test the binary natively

It is unnecessary, but if you could build the standalone native binary, the result should be something like this:

$ ./package/build/wasm-webgpu-matmult

GPU Adapter acquired.
Warning: SetUncapturedErrorCallback is deprecated. Pass the callback in the device descriptor instead.
GPU Device acquired.
First Matrix: 
2 4 1 2 3 4 5 6 7 8 
Second Matrix: 
4 2 1 2 3 4 5 6 7 8 
Commands submitted to the GPU Queue
Warning: Old MapAsync APIs are deprecated. If using C please pass a CallbackInfo struct that has two userdatas. Otherwise, if using C++, please use templated helpers.
In Buffer async call back, status: 1
Result Matrix: 
2 2 50 60 114 140 
Warning: No Dawn device lost callback was set. This is probably not intended. If you really want to ignore device lost and suppress this message, set the callback explicitly.

Deploying the job on DCP

Again, the script ./clean-and-build.sh DCP performs the necessary preparation steps. More specifically:

The code gets built and wrapped between openbravo.js and closebravo.js under the package/src/ directory to make it a DCP-friendly module.
The version number under package/package.dcp will be update
The npm package dcp-client will be installed
The source wasm-webgpu-matmult.js under package/build-web/ will be deployed.

After that, the job can be deployed to the scheduler specified in the environment variable DCP_SCHEDULER_LOCATION. Make sure you have valid authentication keys. Also, note that the current deploy function in deployJob.js deploys the job to the default compute group.

The ./updateVersion.js script which is used to update the version number in the ./package/package.dcp file:

const fs = require('node:fs');
const content = JSON.parse(
  fs.readFileSync('./package/package.dcp', { encoding: 'utf8' }),
);

const version = content.version.split('.');
version[2] = +version[2] + 1;
content.version = version.join('.');

fs.writeFileSync('./package/package.dcp', JSON.stringify(content), {
  encoding: 'utf8',
});

The ./package/src/package.dcp file:

{
  "name": "wasm-webgpu-matmult",
  "version": "0.0.19",
  "files": {
    "./build-web/wasm-webgpu-matmult.js": "wasm-webgpu-matmult.js"
  }
}

The ./package/src/openbravo.js file:

// file name: openbravo.js

// This is a BravoJS module definition, generated for DCP
module.declare([], function(require, exports, module) {

The ./package/src/closebravo.js file:

// file name: closebravo.js

exports.Module = Module;
exports.ccall = ccall;
exports.cwrap = cwrap;
});

// This concludes the BravoJS module definition

This is the content of the ./deployJob.js script:

#!/usr/bin/env node

async function workFn(sliceNumber, arg) {
  progress();
  const { Module } = require('wasm-webgpu-matmult.js');

  async function matmult() {
    // cwrap(function name, return type, args type); null means void here
    RunMatMultWrapper = Module.cwrap('RunMatMultWrapper', 'null', ['null'], {
      async: true,
    });
    await RunMatMultWrapper();
  }

  return new Promise((res) => {
    if (Module.onRuntimeInitialized) {
      const result = matmult();
      res(result);
    } else {
      Module.onRuntimeInitialized = () => {
        const result = matmult();
        res(result);
      };
    }
  });
}

async function deployJob() {
  await require('dcp-client').init();

  let startTime;

  const compute = require('dcp/compute');
  const wallet = require('dcp/wallet');

  const job = compute.for([1], workFn, [0]);

  // Get the stringified message from the worker and log
  job.on('console', (message) => console.log(message));

  // job.requirements.discrete = true;
  job.on('accepted', () => {
    console.log(' - Job accepted by scheduler, waiting for results');
    console.log(` - Job has id ${job.id}`);
    startTime = Date.now();
  });

  job.on('readystatechange', (arg) => {
    console.log(`new ready state: ${arg}`);
  });

  job.on('result', (ev) => {
    console.log(
      ` - Received result for slice ${ev.sliceNumber} at ${
        Math.round((Date.now() - startTime) / 100) / 10
      }s`,
    );
  });

  job.on('status', (ev) => {
    console.log('Got status update: ', ev);
  });

  job.on('error', (message) => console.log(message));

  const ks = await wallet.get(); /* usually loads ~/.dcp/default.keystore */
  job.requires(['wasm-webgpu-matmult/wasm-webgpu-matmult.js']);
  job.public.name = 'wasm-webgpu-matmult';
  job.requirements.environment = { webgpu: true };
  job.setPaymentAccountKeystore(ks);

  const results = await job.exec();
  console.log('results=', Array.from(results));
}

exports.deployJob = deployJob;
deployJob();

To deploy the job, simply run:

node deployJob.js

The current code has a lot of logging messages, so you should see something like the following as the output:

$ node deployJob.js
new ready state: exec
new ready state: init
new ready state: preauth
new ready state: deploying
new ready state: listeners
new ready state: compute-groups
new ready state: uploading
new ready state: deployed
 - Job accepted by scheduler, waiting for results

{
  level: 'log',
  message: [ 'GPU Adapter acquired.' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'GPU Device acquired.' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'First Matrix: ' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ '2 4 1 2 3 4 5 6 7 8 ' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'Second Matrix: ' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ '4 2 1 2 3 4 5 6 7 8 ' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'Commands submitted to the GPU Queue' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'In Buffer async call back, status: 0' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ 'Result Matrix: ' ],
  sliceNumber: 1
}
{
  level: 'log',
  message: [ '2 2 50 60 114 140 ' ],
  sliceNumber: 1
}
 - Received result for slice 1 at 5.2s
Got status update:  {
  runStatus: 'finished',
  total: 1,
  distributed: 1,
  computed: 1,
}

Some points:

The deployJob script, deploys the one-slice job with the entry point workFn. When a worker picks up a job slice, it starts to execute this function.
Before we can call any function from the generated WASM module we should wait for the runtime to be initialized. This is done like this:

  const { Module } = require('wasm-webgpu-matmult.js');

  if (Module.onRuntimeInitialized) {
    // the module is already initialized
    // ...
  } else {
    // the module is not initialized, we will set a callback  
    Module.onRuntimeInitialized = () => {
      // ..
    };
  }

Next, the function RunMatMultWrapper gets called, and as we need its return value, the function should behave synchronously. However, the example in C++ wasm-webgpu-matmult.cpp uses callbacks everywhere (to hanle device and adapter initialization, etc.). According to here, on the C/C++ side, we need to wait a little bit, and importantly to call tick/poll the device so that it updates its awaiting tasks. This is a part of the API that is not standard yet, so we must adapt our implementation to the backend.
All the optinos in CMakeLists.txt is explained to some extent. Note that we need the -sASYNCIFY option, specifically, so that we can await on the cwraped function from our workFn in JS.

RunMatMultWrapper = Module.cwrap('RunMatMultWrapper', 'null', ['null'], {async: true});
await RunMatMultWrapper();

There you go! An example of how to deploy a WebGPU example on DCP using WASM. You can find the complete source of this post here

Amir’s Homepage

PhD Dissertation LaTeX Template

Setting up Gemini CLI on WSL Ubuntu 24.04

Setting up Gemini CLI on WSL Ubuntu 24.04

Step 1: Install Node.js and npm

Step 2: Install and run Gemini CLI

Let’s try it out

Migrate from Ubuntu 20.04 in WSL to 24.04 LTS

Backup

Fresh Installation of Ubuntu 24.04 LTS in WSL

Installing Packages

Other Configurations

CUDA

LaTeX

Pyenv

LLVM

fastfetch

Post-migration

Compact in WSL

Some Tips to Release Binaries

Best Practices

Consider Signing the Binary

Automating the Release Process with GitHub Actions

Automating the Signing in GitHub Actions

Alternative to GPG

Code Signing for Windows

Utilize PTX Just-In-Time (JIT) Compilation in CUDA

Background Scenario

Loading the CUDA module

Thoughts and Improvements

Add Error Management

Collection of my dotfiles (public version)

File Tree

Some notes

Tmux Tips and Tricks

About tmux

Using tmux basics

Inside tmux

Customizing tmux

Managing tmux windows and sessions

Moving and resizing panes

Automatic Startup

Fun Part

References

Setup LAMMPS

Prepare the Environment

Build LAMMPS

MPS on Multi-Instance GPU

Enabling MPS on MIG

Disabling MPS on MIG

Example

Wasm + WebGPU example on DCP

What is DCP?

This example

Code structure

Requirements

Build and Run

Build

Test in the browser without DCP

Test the binary natively

Deploying the job on DCP

About `tmux`