Run the examples on your desktop

Choose what you want to run

The book still runs in your browser with no installation or GPU required. This appendix is an optional next step: download the source, run it on your desktop and compare the actual output.

A code excerpt needs its surrounding setup. The downloads below provide complete programs. The browser’s deliberately broken kernels remain diagnostic exercises; repair invalid accesses and races before downloading. Documentation-question snippets are excerpts for reading, with links to the complete examples.

Run a PyTorch example first

Install Python and use the official PyTorch installation selector (new tab) for your operating system. In a terminal, create a separate environment in a new working folder:

python -m venv .venv
# Linux, macOS or a WSL2 shell:
source .venv/bin/activate
# Windows PowerShell instead:
# .venv\Scripts\Activate.ps1

Run the installation command supplied by the selector inside that environment. If your system names Python python3, use that name for the first command. CPU execution needs no NVIDIA hardware; CUDA execution needs a compatible NVIDIA GPU, driver and PyTorch build.

Download hello.py into this folder, then run:

python hello.py --device cpu

Expect y: tensor([ 2., 4., 6., 8., 10.]); spacing may vary. CPU mode preserves values and layouts but performs no CPU–GPU transfers. To request the CUDA device used by the chapter:

python hello.py --device cuda

The download is generated from the displayed snippet. A small wrapper adds the device selector and prints a result when the snippet has no print call. Explicit CPU-only arithmetic, such as the precision accumulation explanation, remains on CPU. The Download Python button beside a complete snippet saves its current settings. GPGPU-Sim does not run these PyTorch files.

Set up GPGPU-Sim without a GPU

GPGPU-Sim supplies a simulated CUDA runtime. Our functional mode checks what the program computes; it does not measure a physical GPU’s speed. The desktop and CI commands use the same container definition.

Use an x86-64 machine with Docker, Git and a terminal. Linux is the tested CI platform. Windows users can use Docker Desktop with Linux containers and a WSL2 shell. Other desktop setups have not been validated. ARM machines would need amd64 emulation and are outside the tested configuration.

The first build downloads a large CUDA toolchain and compiles the simulator. Plan for tens of GB of free space, including temporary Docker layers; 20 GB may be insufficient. Check both host free space and Docker Desktop’s disk allocation. Allow time for the download and build; later runs reuse the image. No NVIDIA GPU, driver or host CUDA installation is needed for this path.

docker --version
docker info
git clone https://github.com/snowch/gpu-lab.git
cd gpu-lab
docker build -f docker/cuda-sim.Dockerfile -t gpu-lab-cuda-sim .

Compile, simulate and check one CUDA program

Download hello.cu into a separate folder. Open a terminal in that folder; $PWD below means its absolute path. Keep the filename hello.cu.

docker run --rm --network none \
  --mount "type=bind,src=$PWD,dst=/input,readonly" \
  gpu-lab-cuda-sim /input/hello.cu '[2,4,6,8,10]'

The runner compiles the source, confirms that the program links to the simulator’s runtime, runs it, then checks every printed output against the supplied JSON array. Look for:

Output: [2, 4, 6, 8, 10]
PASS: verified 5 output values against the CPU reference

A compiler error, runtime failure, missing output, non-finite value or mismatched result makes the command fail. Omitting the expected array runs without that external output comparison. If you edit the calculation, predict and update the expected array yourself; the runner does not derive an answer from the kernel it is testing.

The source folder is read-only inside the container. Compilation and simulator files use a temporary directory; --rm removes the container afterward. Execution needs no network once the image and source are available. To keep a log, append > hello-run.log 2>&1 to the command.

Run the same CUDA checks as CI

From the repository folder, install Node.js 22 to generate the browser’s CUDA downloads. Then run the suite using the image already built:

node scripts/generate-cuda-cases.mjs
docker run --rm --network none --entrypoint bash \
  --mount "type=bind,src=$PWD,dst=/course" \
  gpu-lab-cuda-sim /course/scripts/cuda-sim.sh

This suite writes logs and provenance under test-results/cuda-sim/. It checks four chapter-1 multipliers, twelve safe workshop variants, five gather configurations, naive/tiled matrix products, a block sum and the padded shared-memory read. The CUDA workflow also checks the documented desktop entry point. Its public workflow results and artifacts (new tab) record the exact revision checked.

To regenerate the downloadable PyTorch files from a checkout:

node scripts/export-desktop.mjs
python test-results/desktop-examples/hello.py --device cpu

In a Python environment with PyTorch installed, python tests/chapter_examples.py checks the displayed source templates and their download wrappers against references. These checks do not benchmark a GPU.

Optional: use a real NVIDIA GPU

Install a compatible NVIDIA driver, CUDA Toolkit and host C++ compiler. From a GPU Lab checkout, the same runner can check the downloaded five-input program on hardware:

bash scripts/run-cuda.sh native /absolute/path/to/hello.cu '[2,4,6,8,10]'

Or compile directly with nvcc -std=c++17 hello.cu -o hello, then run ./hello. That direct command does not perform the runner’s external JSON comparison. The supplied examples have simulator/CPU checks; hardware execution remains unvalidated here. Warm-up, synchronisation, repetition and a stated timing scope are needed before making a performance comparison.

Troubleshooting

Docker cannot connect

Start Docker and confirm docker info succeeds. Use Linux containers; check your account’s Docker access.

No space left during build

Check host space and Docker’s disk allocation. Temporary unpacked layers can be much larger than the download. Remove only images/cache you recognise and no longer need, or increase the allocation.

The source file cannot be found

Run from the folder containing the file. The container sees the mounted folder as /input; use /input/hello.cu inside it. Keep the quoted mount argument when paths contain spaces.

Compilation or runtime-link check fails

Start with the unedited supplied example and pinned image. The simulator needs the shared CUDA runtime and supported PTX target; a normal host CUDA installation alone does not select GPGPU-Sim. Keep the complete log.

Output verification fails or the run times out

Compare all values, the number of outputs and the selected multiplier. Small examples have a 180-second run limit. A changed kernel may be wrong or use unsupported behaviour; increasing the timeout does not establish correctness.

PyTorch reports no CUDA device

Use --device cpu for value/layout practice, or check the NVIDIA driver and installed PyTorch CUDA build. Building the GPGPU-Sim container does not give ordinary PyTorch a CUDA device.