From 24dcdd10341554a0e03fb7345804f7e94fb0a97e Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:24:00 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 147 ------------------------------------------------ README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 147 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 1ed85fc..0000000 --- a/README.adoc +++ /dev/null @@ -1,147 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Futharkiser -Jonathan D.A. Jewell -:toc: left -:icons: font - -== What Is This? - -Futharkiser identifies array-parallel patterns in your code, extracts them, -generates https://futhark-lang.org[Futhark] programs, and compiles those programs -to **GPU kernels** (OpenCL, CUDA, or multicore CPU) -- all without requiring the -user to know anything about GPU programming. - -https://futhark-lang.org[Futhark] (by Troels Henriksen et al., DIKU Copenhagen) is -a purely functional array language that compiles to highly optimised GPU code. It -guarantees no data races and achieves near-hand-tuned performance on parallel -array operations. Almost nobody knows it exists. Futharkiser democratises GPU -computing by putting Futhark behind a simple manifest. - -== How It Works - -Annotate array operations in your code with `#[futharkise]` (or describe them -in `futharkiser.toml`). Futharkiser then: - -1. **Analyses** your source code for parallelisable array patterns -2. **Extracts** operations that map to Futhark's second-order array combinators (SOACs): - `map`, `reduce`, `scan`, `scatter`, `flatten`/`unflatten` -3. **Proves** parallelism safety via the Idris2 ABI layer (no data races, correct - memory layouts, valid GPU buffer descriptors) -4. **Generates** Futhark programs with optimal data layouts and memory transfers -5. **Compiles** via `futhark opencl`, `futhark cuda`, `futhark multicore`, or - `futhark c` (sequential, for debugging) -6. **Creates** a Zig FFI bridge so the compiled GPU kernels are callable from your - application with zero ceremony - -== Key Value - -* **GPU computing for everyone** -- no CUDA/OpenCL expertise needed -* **10-1000x speedups** on array-heavy workloads, with Futhark's compiler - performing fusion, tiling, and memory coalescing automatically -* **Automatic memory management** across the CPU/GPU boundary (host/device/shared - memory spaces are tracked by the ABI layer) -* **Safety guarantees** -- Futhark is purely functional with no data races; - Idris2 proofs verify the interface contracts at compile time -* **Multiple GPU backends** -- OpenCL (widest hardware support), CUDA (NVIDIA), - multicore CPU (no GPU required), sequential C (debugging) - -== Use Cases - -* **Scientific computing** -- matrix operations, PDE solvers, linear algebra -* **Image processing** -- convolutions, filters, histograms on pixel arrays -* **Monte Carlo simulation** -- massively parallel random sampling -* **Neural network primitives** -- custom forward/backward passes on tensors -* **Financial modelling** -- option pricing, risk calculations over large portfolios -* **Signal processing** -- FFT, spectral analysis on array data - -== Architecture - -Follows the hyperpolymath -iser pattern: - -[source] ----- -futharkiser.toml User describes WHAT they want - | - v - Source Analysis Identifies map/reduce/scan/scatter patterns - | - v - Idris2 ABI Layer Proves parallelism safety, validates GPU buffer layouts - (src/interface/abi/) Types: SOAC, GPUBackend, ArrayShape, ParallelPattern, MemorySpace - | - v - Futhark Codegen Generates .fut programs with SOACs - (src/codegen/) - | - v - GPU Compilation futhark opencl | futhark cuda | futhark multicore | futhark c - | - v - Zig FFI Bridge C-ABI callable GPU kernels - (src/interface/ffi/) - | - v - Your Application Calls GPU kernels as normal functions ----- - -=== Futhark SOACs (Second-Order Array Combinators) - -Futharkiser maps source patterns to these Futhark primitives: - -[cols="1,2,2"] -|=== -| SOAC | Description | Example pattern - -| `map` | Apply function to every element | `items.iter().map(\|x\| x * 2)` -| `reduce` | Fold array with associative operator | `items.iter().sum()` -| `scan` | Inclusive prefix scan | Running totals, prefix sums -| `scatter` | Irregular write to array positions | Histogram binning, sparse updates -| `flatten`/`unflatten` | Reshape nested arrays | Matrix operations, batch processing -|=== - -=== GPU Backends - -[cols="1,2,1"] -|=== -| Backend | Use case | Flag - -| OpenCL | Widest hardware support (AMD, Intel, NVIDIA) | `--backend opencl` -| CUDA | NVIDIA GPUs (best NVIDIA performance) | `--backend cuda` -| Multicore CPU | No GPU available; still parallel | `--backend multicore` -| Sequential C | Debugging, correctness testing | `--backend c` -|=== - -Part of the https://github.com/hyperpolymath/iseriser[-iser family] of -acceleration frameworks. - -== Status - -**Codebase in progress.** Architecture defined, CLI scaffolded, RSR template -complete, Idris2 ABI types stubbed. Futhark codegen and GPU compilation pipeline -are the next milestones. - -== Quick Start - -[source,bash] ----- -# Initialise a manifest in your project -futharkiser init - -# Edit futharkiser.toml to describe your array operations -# Then generate, build, and run: -futharkiser generate -futharkiser build --backend opencl -futharkiser run ----- - -== Building from Source - -[source,bash] ----- -cargo build --release ----- - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md new file mode 100644 index 0000000..b35e6fd --- /dev/null +++ b/README.md @@ -0,0 +1,157 @@ + + +# What Is This? + +Futharkiser identifies array-parallel patterns in your code, extracts +them, generates [Futhark](https://futhark-lang.org) programs, and +compiles those programs to **GPU kernels** (OpenCL, CUDA, or multicore +CPU) — all without requiring the user to know anything about GPU +programming. + +[Futhark](https://futhark-lang.org) (by Troels Henriksen et al., DIKU +Copenhagen) is a purely functional array language that compiles to +highly optimised GPU code. It guarantees no data races and achieves +near-hand-tuned performance on parallel array operations. Almost nobody +knows it exists. Futharkiser democratises GPU computing by putting +Futhark behind a simple manifest. + +# How It Works + +Annotate array operations in your code with `#[futharkise]` (or describe +them in `futharkiser.toml`). Futharkiser then: + +1. **Analyses** your source code for parallelisable array patterns + +2. **Extracts** operations that map to Futhark’s second-order array + combinators (SOACs): `map`, `reduce`, `scan`, `scatter`, + `flatten`/`unflatten` + +3. **Proves** parallelism safety via the Idris2 ABI layer (no data + races, correct memory layouts, valid GPU buffer descriptors) + +4. **Generates** Futhark programs with optimal data layouts and memory + transfers + +5. **Compiles** via `futhark` `opencl`, `futhark` `cuda`, `futhark` + `multicore`, or `futhark` `c` (sequential, for debugging) + +6. **Creates** a Zig FFI bridge so the compiled GPU kernels are + callable from your application with zero ceremony + +# Key Value + +- **GPU computing for everyone** — no CUDA/OpenCL expertise needed + +- **10-1000x speedups** on array-heavy workloads, with Futhark’s + compiler performing fusion, tiling, and memory coalescing + automatically + +- **Automatic memory management** across the CPU/GPU boundary + (host/device/shared memory spaces are tracked by the ABI layer) + +- **Safety guarantees** — Futhark is purely functional with no data + races; Idris2 proofs verify the interface contracts at compile time + +- **Multiple GPU backends** — OpenCL (widest hardware support), CUDA + (NVIDIA), multicore CPU (no GPU required), sequential C (debugging) + +# Use Cases + +- **Scientific computing** — matrix operations, PDE solvers, linear + algebra + +- **Image processing** — convolutions, filters, histograms on pixel + arrays + +- **Monte Carlo simulation** — massively parallel random sampling + +- **Neural network primitives** — custom forward/backward passes on + tensors + +- **Financial modelling** — option pricing, risk calculations over large + portfolios + +- **Signal processing** — FFT, spectral analysis on array data + +# Architecture + +Follows the hyperpolymath -iser pattern: + + futharkiser.toml User describes WHAT they want + | + v + Source Analysis Identifies map/reduce/scan/scatter patterns + | + v + Idris2 ABI Layer Proves parallelism safety, validates GPU buffer layouts + (src/interface/abi/) Types: SOAC, GPUBackend, ArrayShape, ParallelPattern, MemorySpace + | + v + Futhark Codegen Generates .fut programs with SOACs + (src/codegen/) + | + v + GPU Compilation futhark opencl | futhark cuda | futhark multicore | futhark c + | + v + Zig FFI Bridge C-ABI callable GPU kernels + (src/interface/ffi/) + | + v + Your Application Calls GPU kernels as normal functions + +## Futhark SOACs (Second-Order Array Combinators) + +Futharkiser maps source patterns to these Futhark primitives: + +| SOAC | Description | Example pattern | +|----|----|----| +| `map` | Apply function to every element | `items.iter().map(|x|` `x` `*` `2)` | +| `reduce` | Fold array with associative operator | `items.iter().sum()` | +| `scan` | Inclusive prefix scan | Running totals, prefix sums | +| `scatter` | Irregular write to array positions | Histogram binning, sparse updates | +| `flatten`/`unflatten` | Reshape nested arrays | Matrix operations, batch processing | + +## GPU Backends + +| Backend | Use case | Flag | +|----|----|----| +| OpenCL | Widest hardware support (AMD, Intel, NVIDIA) | `--backend` `opencl` | +| CUDA | NVIDIA GPUs (best NVIDIA performance) | `--backend` `cuda` | +| Multicore CPU | No GPU available; still parallel | `--backend` `multicore` | +| Sequential C | Debugging, correctness testing | `--backend` `c` | + +Part of the [-iser family](https://github.com/hyperpolymath/iseriser) of +acceleration frameworks. + +# Status + +**Codebase in progress.** Architecture defined, CLI scaffolded, RSR +template complete, Idris2 ABI types stubbed. Futhark codegen and GPU +compilation pipeline are the next milestones. + +# Quick Start + +```bash +# Initialise a manifest in your project +futharkiser init + +# Edit futharkiser.toml to describe your array operations +# Then generate, build, and run: +futharkiser generate +futharkiser build --backend opencl +futharkiser run +``` + +# Building from Source + +```bash +cargo build --release +``` + +# License + +SPDX-License-Identifier: CC-BY-SA-4.0