8214176814
Prepare infrastructure for specialized numeric array benchmarking: - Add IntArrayCore plugin stub (crates/nyash_kernel/src/plugin/intarray.rs) - Add IntArrayCore/MatI64 box definitions (lang/src/runtime/numeric/) - Add Phase 21.8 documentation and task tracking - Update nyash.toml/hako.toml with numeric library configuration - Extend microbench.sh for matmul_core benchmark case Next: Resolve Stage-B MirBuilder to recognize MatI64/IntArrayCore as boxes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
86 lines
4.6 KiB
Markdown
86 lines
4.6 KiB
Markdown
# Phase 21.8 — Numeric Core Integration & Builder Support
|
||
|
||
Status: proposal (to hand off to Claude Code)
|
||
|
||
## Goal
|
||
|
||
Integrate the new numeric core boxes (IntArrayCore + MatI64) into the Hakorune selfhost chain so that:
|
||
|
||
- Stage‑B → MirBuilder → ny‑llvmc(crate) can emit MIR(JSON) and EXE for code that uses:
|
||
- `using nyash.core.numeric.intarray as IntArrayCore`
|
||
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
||
- The `matmul_core` microbench (MatI64 + IntArrayCore) runs end‑to‑end in EXE mode and can be compared fairly against a matching C implementation.
|
||
|
||
21.6 provides the core boxes; 21.8 focuses on wiring them into the builder/runtime chain without changing default behaviour for other code.
|
||
|
||
## Scope (21.8, this host)
|
||
|
||
- Stage‑B / MirBuilder:
|
||
- Ensure `MatI64` and `IntArrayCore` are recognized as valid boxes when referenced via:
|
||
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
||
- `using nyash.core.numeric.intarray as IntArrayCore`
|
||
- Fix the current provider‑emit failure:
|
||
- Error today: `[mirbuilder/parse/error] undefined variable: MatI64` during `env.mirbuilder.emit`.
|
||
- Diagnose and adjust Stage‑B / MirBuilder so that static box references (`MatI64.new`, `A.mul_naive`) compile in the same way as other boxes.
|
||
|
||
- AotPrep / emit pipeline:
|
||
- Keep AotPrep unchanged for now; the goal is to make `tools/hakorune_emit_mir.sh` succeed on `matmul_core` sources without special‑casing.
|
||
- Ensure `tools/hakorune_emit_mir.sh` with:
|
||
- `HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1`
|
||
- can emit valid MIR(JSON) for MatI64/IntArrayCore code.
|
||
|
||
- Microbench integration:
|
||
- Finish wiring `matmul_core` in `tools/perf/microbench.sh`:
|
||
- Hako side: MatI64/IntArrayCore based O(n³) matmul (`MatI64.mul_naive`).
|
||
- C side: `MatI64Core { int64_t *ptr; rows; cols; stride; }` with identical algorithm.
|
||
- Accept that performance may still be far from the 80% target; 21.8 focuses on **structural integration and parity**, not tuning.
|
||
|
||
Out of scope:
|
||
|
||
- New optimizations inside AotPrep / CollectionsHot.
|
||
- SIMD/blocked matmul kernels (to be handled in a later optimization phase).
|
||
- f64/complex matrix variants.
|
||
|
||
## Tasks for implementation (Claude Code)
|
||
|
||
1) **Fix MatI64 visibility in Stage‑B / MirBuilder**
|
||
- Reproduce the current failure:
|
||
- Use a small `.hako` like:
|
||
- `using nyash.core.numeric.matrix_i64 as MatI64`
|
||
- `static box Main { method main(args) { local n = 4; local A = MatI64.new(n,n); return A.at(0,0); } }`
|
||
- Confirm `env.mirbuilder.emit` reports `undefined variable: MatI64`.
|
||
- Investigate how modules from `nyash.toml` (`"nyash.core.numeric.matrix_i64" = "lang/src/runtime/numeric/mat_i64_box.hako"`) are made visible to Stage‑B and MirBuilder.
|
||
- Adjust the resolver / module prelude so that `MatI64` (and `IntArrayCore`) are treated like other core boxes:
|
||
- Either via explicit prelude inclusion,
|
||
- Or via module registry entries consumed by the builder.
|
||
|
||
2) **Ensure `tools/hakorune_emit_mir.sh` can emit MIR(JSON) for matmul_core**
|
||
- Once MatI64 is visible, run:
|
||
- `HAKO_APPLY_AOT_PREP=1 NYASH_AOT_COLLECTIONS_HOT=1 NYASH_LLVM_FAST=1 NYASH_MIR_LOOP_HOIST=1 NYASH_JSON_ONLY=1 tools/hakorune_emit_mir.sh <matmul_core.hako> tmp/matmul_core.json`
|
||
- Acceptance:
|
||
- No `undefined variable: MatI64` / `IntArrayCore` errors.
|
||
- `tmp/matmul_core.json` is valid MIR(JSON) (same schema as existing matmul case).
|
||
|
||
3) **Finish `matmul_core` microbench**
|
||
- Use the existing skeleton in `tools/perf/microbench.sh` (`case matmul_core`):
|
||
- Confirm Hako side compiles and runs under `--backend vm`.
|
||
- Confirm EXE path works:
|
||
- `NYASH_SKIP_TOML_ENV=1 NYASH_LLVM_SKIP_BUILD=1 tools/perf/microbench.sh --case matmul_core --backend llvm --exe --runs 1 --n 64`
|
||
- Update `benchmarks/README.md`:
|
||
- Add `matmul_core` row with a short description:
|
||
- “MatI64/IntArrayCore vs MatI64Core C struct (ptr+rows+cols+stride)”
|
||
- Record initial ratios (even if far from 80%).
|
||
|
||
4) **Keep existing behaviour stable**
|
||
- No changes to default user behaviour, env toggles, or existing benches beyond adding `matmul_core`.
|
||
- Ensure quick/profile smokes (where applicable) remain green with numeric core present.
|
||
|
||
## Notes
|
||
|
||
- 21.6 already introduced:
|
||
- NyRT `IntArrayCore` (Vec<i64> + RwLock) and handle‑based externs (`nyash.intarray.*`).
|
||
- Hako wrappers `IntArrayCore` and `MatI64` in `lang/src/runtime/numeric/`.
|
||
- `nyash.toml` module aliases for `nyash.core.numeric.intarray` and `nyash.core.numeric.matrix_i64`.
|
||
- 21.8 is about wiring these into the builder/emit chain so that Hakorune can compile and benchmark numeric core code end‑to‑end.
|
||
|