From 3bf1d6158786dbf025fa713d9062a3cfd5fc9ce2 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:27:49 +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 | 148 ----------------------------------------- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 187 insertions(+), 148 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 459acf9..0000000 --- a/README.adoc +++ /dev/null @@ -1,148 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Halideiser -Jonathan D.A. Jewell -:toc: left -:icons: font - -== What Is This? - -Halideiser compiles image and video processing pipelines to optimised -https://halide-lang.org[Halide] schedules. You describe your pipeline -stages in `halideiser.toml` — blur, sharpen, resize, edge detect, -colour transform, convolution — and Halideiser generates the Halide -algorithm definitions, auto-tunes the schedule for your target hardware, -and produces optimised native code. - -Halide (by Jonathan Ragan-Kelley et al., MIT/Google) separates the -_algorithm_ (what to compute) from the _schedule_ (how to compute it on -hardware). This separation enables 10–100x speedups over hand-tuned C -by letting the compiler explore tiling, vectorisation, parallelism, and -memory layout choices automatically. Halideiser makes this power -accessible without Halide expertise. - -== How It Works - -[source,text] ----- -halideiser.toml (pipeline description) - │ - ▼ - Pipeline Parser (validate stages, data flow, dimensions) - │ - ▼ - Idris2 ABI Proofs (prove pipeline correctness, buffer safety) - │ - ▼ - Halide Algorithm (Func definitions, Var bindings, Expr trees) - Codegen (from pipeline stages) - │ - ▼ - Schedule Generation (tile, vectorize, parallelize, compute_at, - + Auto-Tuning store_at, reorder — search over schedule space) - │ - ▼ - Compiled Pipeline (native code for target hardware) ----- - -1. **Describe** your pipeline in `halideiser.toml` — stages, buffer - dimensions, data types, target hardware -2. **Validate** — the Idris2 ABI layer formally proves buffer bounds, - dimension compatibility, and stage connectivity -3. **Generate** — Halide algorithm code is emitted with `Func`, `Var`, - and scheduling primitives -4. **Tune** — the auto-tuner searches the schedule space (tile sizes, - loop orders, parallelism) for optimal performance -5. **Compile** — the tuned schedule is compiled to native code via LLVM - -== Halide Concepts - -Halideiser works with core Halide abstractions: - -* **Func** — a pure function defining what to compute at each pixel -* **Var** — a dimension variable (x, y, channel, frame) -* **Scheduling primitives** — control _how_ to execute: -** `tile(x, y, xi, yi, tx, ty)` — break loops into tiles for cache locality -** `vectorize(xi, width)` — use SIMD instructions (SSE, AVX, NEON) -** `parallelize(y)` — distribute rows across CPU cores -** `compute_at(consumer, var)` — fuse producer into consumer loop -** `store_at(consumer, var)` — control where intermediate buffers live -** `reorder(vars...)` — change loop nesting order -** `unroll(var, factor)` — unroll inner loops -** `gpu_blocks / gpu_threads` — map to GPU compute grids - -== Hardware Targets - -|=== -| Target | Instructions / Backend - -| x86 SSE/AVX | 128–512-bit SIMD, auto-vectorisation -| ARM NEON/SVE | Mobile and embedded SIMD -| CUDA | NVIDIA GPU kernels -| OpenCL | Cross-vendor GPU compute -| WebAssembly | Browser-based image processing -| Metal | Apple GPU compute -| Vulkan | Cross-platform GPU compute -|=== - -== Key Value - -* **10–100x faster** image and video processing without writing Halide by hand -* **Automatic hardware scheduling** — SIMD, GPU, multi-core, all derived from one pipeline description -* **No Halide expertise needed** — describe the pipeline, get the speed -* **Formally verified** — Idris2 proofs guarantee buffer bounds and dimension safety before codegen -* **Multi-target** — one pipeline compiles to x86, ARM, CUDA, OpenCL, WebAssembly - -== Use Cases - -* **Real-time video filters** — blur, sharpen, colour grade at 60fps+ -* **Batch image processing** — resize, watermark, convert millions of images -* **Medical imaging** — CT/MRI reconstruction, denoising, segmentation -* **Computational photography** — HDR merge, demosaicing, lens correction -* **Computer vision preprocessing** — edge detection, histogram equalisation, feature extraction - -== Architecture - -Follows the hyperpolymath -iser pattern (same as https://github.com/hyperpolymath/chapeliser[Chapeliser]): - -* **Manifest** (`halideiser.toml`) — describe WHAT pipeline stages you need -* **Pipeline Parser** (`src/manifest/`) — validate stage connectivity and buffer dimensions -* **Idris2 ABI** (`src/interface/abi/`) — formal proofs of pipeline correctness, buffer layout, and scheduling safety -* **Halide Codegen** (`src/codegen/`) — emit Halide `Func` / `Var` definitions and scheduling calls -* **Zig FFI** (`src/interface/ffi/`) — C-ABI bridge for calling compiled pipelines from any language -* **Rust CLI** (`src/main.rs`) — orchestrates parse, validate, generate, tune, and build - -User writes zero Halide code. Halideiser generates everything. - -Part of the https://github.com/hyperpolymath/iseriser[-iser family] of acceleration frameworks. - -== Status - -**Pre-alpha.** Architecture defined, scaffolding in place, codegen pending. -Codebase in progress — pipeline parser and Halide codegen are next. - -== Quick Start - -[source,bash] ----- -# Initialise a manifest in the current directory -halideiser init - -# Edit halideiser.toml to describe your pipeline stages - -# Validate the manifest -halideiser validate - -# Generate Halide code and schedule -halideiser generate - -# Build the compiled pipeline -halideiser build --release - -# Run the pipeline -halideiser run -- input.png output.png ----- - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8b8730e --- /dev/null +++ b/README.md @@ -0,0 +1,187 @@ + + +# What Is This? + +Halideiser compiles image and video processing pipelines to optimised +[Halide](https://halide-lang.org) schedules. You describe your pipeline +stages in `halideiser.toml` — blur, sharpen, resize, edge detect, colour +transform, convolution — and Halideiser generates the Halide algorithm +definitions, auto-tunes the schedule for your target hardware, and +produces optimised native code. + +Halide (by Jonathan Ragan-Kelley et al., MIT/Google) separates the +*algorithm* (what to compute) from the *schedule* (how to compute it on +hardware). This separation enables 10–100x speedups over hand-tuned C by +letting the compiler explore tiling, vectorisation, parallelism, and +memory layout choices automatically. Halideiser makes this power +accessible without Halide expertise. + +# How It Works + +```text +halideiser.toml (pipeline description) + │ + ▼ + Pipeline Parser (validate stages, data flow, dimensions) + │ + ▼ + Idris2 ABI Proofs (prove pipeline correctness, buffer safety) + │ + ▼ + Halide Algorithm (Func definitions, Var bindings, Expr trees) + Codegen (from pipeline stages) + │ + ▼ + Schedule Generation (tile, vectorize, parallelize, compute_at, + + Auto-Tuning store_at, reorder — search over schedule space) + │ + ▼ + Compiled Pipeline (native code for target hardware) +``` + +1. **Describe** your pipeline in `halideiser.toml` — stages, buffer + dimensions, data types, target hardware + +2. **Validate** — the Idris2 ABI layer formally proves buffer bounds, + dimension compatibility, and stage connectivity + +3. **Generate** — Halide algorithm code is emitted with `Func`, `Var`, + and scheduling primitives + +4. **Tune** — the auto-tuner searches the schedule space (tile sizes, + loop orders, parallelism) for optimal performance + +5. **Compile** — the tuned schedule is compiled to native code via LLVM + +# Halide Concepts + +Halideiser works with core Halide abstractions: + +- **Func** — a pure function defining what to compute at each pixel + +- **Var** — a dimension variable (x, y, channel, frame) + +- **Scheduling primitives** — control *how* to execute: + + - `tile(x,` `y,` `xi,` `yi,` `tx,` `ty)` — break loops into tiles for + cache locality + + - `vectorize(xi,` `width)` — use SIMD instructions (SSE, AVX, NEON) + + - `parallelize(y)` — distribute rows across CPU cores + + - `compute_at(consumer,` `var)` — fuse producer into consumer loop + + - `store_at(consumer,` `var)` — control where intermediate buffers + live + + - `reorder(vars…)` — change loop nesting order + + - `unroll(var,` `factor)` — unroll inner loops + + - `gpu_blocks` `/` `gpu_threads` — map to GPU compute grids + +# Hardware Targets + +| Target | Instructions / Backend | +|--------------|--------------------------------------| +| x86 SSE/AVX | 128–512-bit SIMD, auto-vectorisation | +| ARM NEON/SVE | Mobile and embedded SIMD | +| CUDA | NVIDIA GPU kernels | +| OpenCL | Cross-vendor GPU compute | +| WebAssembly | Browser-based image processing | +| Metal | Apple GPU compute | +| Vulkan | Cross-platform GPU compute | + +# Key Value + +- **10–100x faster** image and video processing without writing Halide + by hand + +- **Automatic hardware scheduling** — SIMD, GPU, multi-core, all derived + from one pipeline description + +- **No Halide expertise needed** — describe the pipeline, get the speed + +- **Formally verified** — Idris2 proofs guarantee buffer bounds and + dimension safety before codegen + +- **Multi-target** — one pipeline compiles to x86, ARM, CUDA, OpenCL, + WebAssembly + +# Use Cases + +- **Real-time video filters** — blur, sharpen, colour grade at 60fps+ + +- **Batch image processing** — resize, watermark, convert millions of + images + +- **Medical imaging** — CT/MRI reconstruction, denoising, segmentation + +- **Computational photography** — HDR merge, demosaicing, lens + correction + +- **Computer vision preprocessing** — edge detection, histogram + equalisation, feature extraction + +# Architecture + +Follows the hyperpolymath -iser pattern (same as +[Chapeliser](https://github.com/hyperpolymath/chapeliser)): + +- **Manifest** (`halideiser.toml`) — describe WHAT pipeline stages you + need + +- **Pipeline Parser** (`src/manifest/`) — validate stage connectivity + and buffer dimensions + +- **Idris2 ABI** (`src/interface/abi/`) — formal proofs of pipeline + correctness, buffer layout, and scheduling safety + +- **Halide Codegen** (`src/codegen/`) — emit Halide `Func` / `Var` + definitions and scheduling calls + +- **Zig FFI** (`src/interface/ffi/`) — C-ABI bridge for calling compiled + pipelines from any language + +- **Rust CLI** (`src/main.rs`) — orchestrates parse, validate, generate, + tune, and build + +User writes zero Halide code. Halideiser generates everything. + +Part of the [-iser family](https://github.com/hyperpolymath/iseriser) of +acceleration frameworks. + +# Status + +**Pre-alpha.** Architecture defined, scaffolding in place, codegen +pending. Codebase in progress — pipeline parser and Halide codegen are +next. + +# Quick Start + +```bash +# Initialise a manifest in the current directory +halideiser init + +# Edit halideiser.toml to describe your pipeline stages + +# Validate the manifest +halideiser validate + +# Generate Halide code and schedule +halideiser generate + +# Build the compiled pipeline +halideiser build --release + +# Run the pipeline +halideiser run -- input.png output.png +``` + +# License + +SPDX-License-Identifier: CC-BY-SA-4.0