From 981d0e2b6eaba6459e4da15c64a63db3e465c984 Mon Sep 17 00:00:00 2001
From: kaj dijkstra <kajdijkstra@protonmail.com>
Date: Tue, 30 Dec 2025 20:59:06 +0100
Subject: [PATCH] Readme

---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0bb9aa2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+
+# WebGPU Bitonic Sort (Unsigned Integers)
+
+This project implements a **GPU-accelerated bitonic sort** for unsigned integers using **WebGPU compute shaders**. It performs a local per-workgroup sort followed by a multi-pass global bitonic merge and measures execution time in the browser.
+
+## Overview
+
+* Sorting algorithm: **Bitonic sort**
+* Execution model: **WebGPU compute pipelines**
+* Data type: `Uint32`
+* Element count: `131,072`
+* Workgroup size: `256`
+* Execution environment: **Modern browser with WebGPU enabled**
+
+The implementation splits sorting into two stages:
+
+1. **Local sort**
+   Each workgroup sorts its local block of data.
+
+2. **Global bitonic merge**
+   Multiple compute passes perform the bitonic merge across all workgroups using precomputed `j` and `k` pass parameters.
+
+## Structure
+
+* `WebGpu.js`
+  Abstraction layer for creating pipelines, bind groups, and buffers.
+
+* `Measure.js`
+  Simple performance measurement utility with optional DOM output.
+
+* `shaders/localSort.wgsl`
+  Compute shader for local (per-workgroup) sorting.
+
+* `shaders/bitonicSortUIntMultiPass.wgsl`
+  Compute shader for multi-pass global bitonic merging.
+
+## How It Works
+
+1. Request a WebGPU adapter and device.
+2. Initialize index buffers and bitonic pass parameters (`jArray`, `kArray`).
+3. Run a local compute pass to partially sort data.
+4. Run a global bitonic merge with repeated dispatches.
+5. Measure execution time for multiple iterations.
+6. Read back the result buffer and verify correctness.
+
+After completion, the result is validated on the CPU to ensure that all values are sorted correctly.
+
+## Requirements
+
+* A browser with **WebGPU support** enabled
+  (for example Chromium-based browsers with the appropriate flags).
+* A GPU and driver that support WebGPU compute shaders.
+* A static file server (due to module imports and shader loading).
+
+## Running
+
+Serve the project directory via a local web server and open the page that loads this script.
+
+Example:
+
+```
+python3 -m http.server
+```
+
+Then open:
+
+```
+http://localhost:8000
+```
+
+## Output
+
+* Timing results are written to the page via `Measure`.
+* Final verification logs to the console:
+
+```
+There is error? false 131072
+```
+
+If `true`, the GPU sort produced incorrect results.
+
+## Purpose
+
+This project serves as:
+
+* A WebGPU compute benchmark
+* A reference implementation of GPU-based bitonic sorting
+* A foundation for GPU-accelerated data processing pipelines
+
+## License
+
+MIT