From 33fad3bf86ad8fb94c20c2f58a773a6a14241d53 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:10:50 +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 | 170 ------------------------------------------------ README.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+), 170 deletions(-) delete mode 100644 README.adoc create mode 100644 README.md diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 4ca9197..0000000 --- a/README.adoc +++ /dev/null @@ -1,170 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -= Chapeliser -Jonathan D.A. Jewell -:toc: left -:toclevels: 3 -:icons: font -:source-highlighter: rouge - -image:https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github[Sponsor,link=https://github.com/sponsors/hyperpolymath] - -== What Is This? - -Chapeliser is a **general-purpose Chapel acceleration framework** that lets -developers scale single-machine applications to distributed clusters without -learning Chapel. - -You describe your workload in a manifest (`chapeliser.toml`), point Chapeliser -at your code, and it generates the distributed scaffolding — Chapel `coforall` -loops, data partitioning, result gathering, and the ABI/FFI bridge between your -application and the Chapel runtime. - -== The Problem - -Chapel is one of the most powerful parallel programming languages ever built. -It can distribute computation across thousands of nodes with elegant syntax. -But almost nobody uses it because: - -1. **Steep learning curve** — you must rewrite your application in Chapel or - deeply understand its interop model -2. **No incremental adoption path** — it's all-or-nothing -3. **Build system complexity** — integrating Chapel with existing Rust/C/Zig - projects is non-trivial - -Chapeliser solves all three. - -== How It Works - -[source] ----- -Your application (Rust, C, Zig) - │ - ▼ -chapeliser.toml ──► Chapeliser CLI - │ │ - │ ┌───────────┴───────────┐ - │ │ │ - ▼ ▼ ▼ - Idris2 ABI Zig FFI Chapel wrapper - (formal proof of (C-ABI bridge (coforall + data - data layout + to Chapel distribution + - partition safety) runtime) gather/reduce) - │ │ │ - └────────┬───────┘ │ - ▼ │ - generated/abi/*.h ◄───────────────────┘ - │ - ▼ - Your app, now distributed ----- - -=== The Manifest - -[source,toml] ----- -[workload] -name = "my-scanner" -entry = "src/batch.rs::scan_all" # function to distribute -partition = "per-item" # split strategy -gather = "merge" # combine strategy - -[data] -input-type = "Vec" # what gets distributed -output-type = "Vec" # what comes back -serialization = "bincode" # wire format - -[scaling] -min-nodes = 1 # runs locally if alone -max-nodes = 256 # scales to cluster -grain-size = 50 # items per Chapel task ----- - -You write **zero Chapel code**. Chapeliser generates everything. - -=== Partition Strategies - -|=== -| Strategy | Description | Best For - -| `per-item` | One item per task | File scanning, image processing -| `chunk` | Fixed-size chunks | Data pipelines, ETL -| `adaptive` | Dynamic load balancing | Heterogeneous workloads -| `spatial` | Domain decomposition | Simulation, matrices -| `keyed` | Group by key | Map-reduce, aggregation -|=== - -=== Gather Strategies - -|=== -| Strategy | Description - -| `merge` | Concatenate all results -| `reduce` | Apply reduction function (sum, max, min, custom) -| `tree-reduce` | Logarithmic reduction for associative ops -| `stream` | Results stream back as they complete -| `first` | Return first successful result (search) -|=== - -== Architecture - -Chapeliser follows the hyperpolymath ABI-FFI standard: - -* **Idris2 ABI** (`src/interface/abi/`) — Dependent-type *proof obligations*, - machine-checked in CI (`.github/workflows/provable.yml`); the Rust mirror in - `src/abi/` carries the matching runtime types and checks: - - Partition functions produce complete, non-overlapping splits - - Gather functions preserve all results - - Serialization round-trips are identity - - Memory layouts are consistent across the FFI boundary - -* **Zig FFI** (`src/interface/ffi/`) — C-ABI bridge between: - - The user's application (any language with C FFI) - - The Chapel runtime (`chpl_*` functions) - - Memory management across the boundary - -* **Chapel codegen** (`src/codegen/`) — Generates: - - `coforall` distribution loops - - Locale-aware data placement - - Communication primitives (GET/PUT/AMO) - - Fault tolerance (retry, checkpoint, redistribute) - -* **Rust CLI** (`src/`) — The `chapeliser` command: - - Parses `chapeliser.toml` - - Validates workload description - - Generates Chapel + Zig + C header scaffolding - - Builds and links everything - - Provides `chapeliser run` for execution - -== Quick Start - -[source,bash] ----- -# Install (once published to crates.io — see ROADMAP Phase 3) -cargo install chapeliser - -# In your project directory, create chapeliser.toml (see above) -chapeliser init # generates scaffold from manifest -chapeliser build # compiles Chapel wrapper + FFI bridge -chapeliser run # executes locally (1 node) -chapeliser run -n 8 # distributes across 8 nodes -chapeliser run --cluster my-cluster.toml # full cluster ----- - -== First Consumer: panic-attacker - -The first application to be Chapelised is -https://github.com/hyperpolymath/panic-attacker[panic-attacker]'s -`mass-panic` (assemblyline) mode — distributing static analysis across -hundreds of repositories on a compute cluster. - -== Status - -**Pre-alpha.** The Rust CLI and code generator are implemented and tested -(63 tests). The Idris2 proofs, Zig FFI, and a golden Chapel compile-and-run are -wired into CI as the verification gate (`.github/workflows/provable.yml`) — see -`ROADMAP.adoc` Phase 1b for their live (green/red) status. Not yet released. - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/README.md b/README.md new file mode 100644 index 0000000..83c9e95 --- /dev/null +++ b/README.md @@ -0,0 +1,183 @@ + + +[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + +# What Is This? + +Chapeliser is a **general-purpose Chapel acceleration framework** that +lets developers scale single-machine applications to distributed +clusters without learning Chapel. + +You describe your workload in a manifest (`chapeliser.toml`), point +Chapeliser at your code, and it generates the distributed scaffolding — +Chapel `coforall` loops, data partitioning, result gathering, and the +ABI/FFI bridge between your application and the Chapel runtime. + +# The Problem + +Chapel is one of the most powerful parallel programming languages ever +built. It can distribute computation across thousands of nodes with +elegant syntax. But almost nobody uses it because: + +1. **Steep learning curve** — you must rewrite your application in + Chapel or deeply understand its interop model + +2. **No incremental adoption path** — it’s all-or-nothing + +3. **Build system complexity** — integrating Chapel with existing + Rust/C/Zig projects is non-trivial + +Chapeliser solves all three. + +# How It Works + + Your application (Rust, C, Zig) + │ + ▼ + chapeliser.toml ──► Chapeliser CLI + │ │ + │ ┌───────────┴───────────┐ + │ │ │ + ▼ ▼ ▼ + Idris2 ABI Zig FFI Chapel wrapper + (formal proof of (C-ABI bridge (coforall + data + data layout + to Chapel distribution + + partition safety) runtime) gather/reduce) + │ │ │ + └────────┬───────┘ │ + ▼ │ + generated/abi/*.h ◄───────────────────┘ + │ + ▼ + Your app, now distributed + +## The Manifest + +```toml +[workload] +name = "my-scanner" +entry = "src/batch.rs::scan_all" # function to distribute +partition = "per-item" # split strategy +gather = "merge" # combine strategy + +[data] +input-type = "Vec" # what gets distributed +output-type = "Vec" # what comes back +serialization = "bincode" # wire format + +[scaling] +min-nodes = 1 # runs locally if alone +max-nodes = 256 # scales to cluster +grain-size = 50 # items per Chapel task +``` + +You write **zero Chapel code**. Chapeliser generates everything. + +## Partition Strategies + +| Strategy | Description | Best For | +|------------|------------------------|---------------------------------| +| `per-item` | One item per task | File scanning, image processing | +| `chunk` | Fixed-size chunks | Data pipelines, ETL | +| `adaptive` | Dynamic load balancing | Heterogeneous workloads | +| `spatial` | Domain decomposition | Simulation, matrices | +| `keyed` | Group by key | Map-reduce, aggregation | + +## Gather Strategies + +| Strategy | Description | +|---------------|--------------------------------------------------| +| `merge` | Concatenate all results | +| `reduce` | Apply reduction function (sum, max, min, custom) | +| `tree-reduce` | Logarithmic reduction for associative ops | +| `stream` | Results stream back as they complete | +| `first` | Return first successful result (search) | + +# Architecture + +Chapeliser follows the hyperpolymath ABI-FFI standard: + +- **Idris2 ABI** (`src/interface/abi/`) — Dependent-type **proof + obligations**, machine-checked in CI + (`.github/workflows/provable.yml`); the Rust mirror in `src/abi/` + carries the matching runtime types and checks: + + - Partition functions produce complete, non-overlapping splits + + - Gather functions preserve all results + + - Serialization round-trips are identity + + - Memory layouts are consistent across the FFI boundary + + + +- **Zig FFI** (`src/interface/ffi/`) — C-ABI bridge between: + + - The user’s application (any language with C FFI) + + - The Chapel runtime (`chpl_*` functions) + + - Memory management across the boundary + + + +- **Chapel codegen** (`src/codegen/`) — Generates: + + - `coforall` distribution loops + + - Locale-aware data placement + + - Communication primitives (GET/PUT/AMO) + + - Fault tolerance (retry, checkpoint, redistribute) + + + +- **Rust CLI** (`src/`) — The `chapeliser` command: + + - Parses `chapeliser.toml` + + - Validates workload description + + - Generates Chapel + Zig + C header scaffolding + + - Builds and links everything + + - Provides `chapeliser` `run` for execution + +# Quick Start + +```bash +# Install (once published to crates.io — see ROADMAP Phase 3) +cargo install chapeliser + +# In your project directory, create chapeliser.toml (see above) +chapeliser init # generates scaffold from manifest +chapeliser build # compiles Chapel wrapper + FFI bridge +chapeliser run # executes locally (1 node) +chapeliser run -n 8 # distributes across 8 nodes +chapeliser run --cluster my-cluster.toml # full cluster +``` + +# First Consumer: panic-attacker + +The first application to be Chapelised is +[panic-attacker](https://github.com/hyperpolymath/panic-attacker)’s +`mass-panic` (assemblyline) mode — distributing static analysis across +hundreds of repositories on a compute cluster. + +# Status + +**Pre-alpha.** The Rust CLI and code generator are implemented and +tested (63 tests). The Idris2 proofs, Zig FFI, and a golden Chapel +compile-and-run are wired into CI as the verification gate +(`.github/workflows/provable.yml`) — see `ROADMAP.adoc` Phase 1b for +their live (green/red) status. Not yet released. + +# License + +SPDX-License-Identifier: CC-BY-SA-4.0