diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..bd3cd51 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,24 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 + +[*.py] +indent_size = 4 + +[*.{v,sv}] +indent_size = 2 + +[*.{yml,yaml,json}] +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[{Makefile,*.mk}] +indent_style = tab diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e5f325a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,62 @@ +name: Bug report +description: Report something that is not working +labels: +- bug +body: +- type: textarea + id: what + attributes: + label: What happened? + description: Describe the bug and what you expected instead. + validations: + required: true +- type: textarea + id: steps + attributes: + label: Steps to reproduce + description: Numbered steps, as exact as possible. + validations: + required: true +- type: input + id: env + attributes: + label: Operating system and Python version + description: e.g. Ubuntu 24.04, Python 3.12.3 (`python3 --version`). + validations: + required: true +- type: input + id: numpy + attributes: + label: numpy version + description: '`python3 -c ''import numpy; print(numpy.__version__)''`.' + validations: + required: false +- type: input + id: unit + attributes: + label: Adder / multiplier / module + description: e.g. `LOA(8, k=3)` or `rtl/drum_mult.v`. + validations: + required: false +- type: input + id: tools + attributes: + label: Simulator / tool versions + description: Output of `iverilog -V | head -1`, `yosys -V`, `verilator --version` (whichever you used) (only for RTL issues). + validations: + required: true +- type: input + id: commit + attributes: + label: Commit + description: Output of `git rev-parse --short HEAD`. + validations: + required: true +- type: textarea + id: logs + attributes: + label: Logs or output + description: Paste relevant output. It will be formatted as code. Remove personal data first. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..fb61131 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: Feature request +description: Suggest an improvement +labels: +- enhancement +body: +- type: textarea + id: problem + attributes: + label: Problem or motivation + description: What are you trying to do that is hard today? + validations: + required: true +- type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe what you would like to see. + validations: + required: true +- type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches you thought about. + validations: + required: false +- type: textarea + id: hw + attributes: + label: RTL / area impact + description: New Verilog units or gate-count proxy changes, if any. + validations: + required: false diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..8e39a40 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: +- package-ecosystem: github-actions + directory: / + schedule: + interval: weekly +- package-ecosystem: pip + directory: / + schedule: + interval: weekly diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d3f9626 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Summary + +What does this change and why? + +## Checklist + +- [ ] `python tests/test_units.py` passes +- [ ] Python model and Verilog stay bit-exact: `python scripts/rtl_regress.py --out build --synth` (needs iverilog, yosys) or state "not run" +- [ ] README tables updated if a unit or result changed +- [ ] Documentation updated where behaviour changed +- [ ] No secrets, keys or personal data committed + +## Test notes + +How was this verified? Paste commands and results, or write "not run". diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..05057c1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,75 @@ +name: CI + +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + python: + name: Python ${{ matrix.python-version }} + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: ["3.10", "3.11", "3.13"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + - name: Install + run: | + python -m pip install --upgrade pip + python -m pip install -e ".[test]" + - name: Unit tests (core + v2) + run: python -m pytest + - name: Tests also run as plain scripts + run: | + python tests/test_units.py + python v2/tests/test_v2.py + + examples: + name: Examples and committed results + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: python -m pip install -e ".[plots]" + - name: DSE sweep (n = 8, exhaustive) reproduces results/dse_*_n8.csv + run: | + python examples/run_dse.py --n 8 --out "$RUNNER_TEMP/dse" + python scripts/compare_csv.py "$RUNNER_TEMP/dse/dse_adder_n8.csv" results/dse_adder_n8.csv + python scripts/compare_csv.py "$RUNNER_TEMP/dse/dse_multiplier_n8.csv" results/dse_multiplier_n8.csv + - name: v2 error sweep reproduces v2/results/errors_v2_n8.csv + working-directory: v2 + run: | + python scripts/error_sweep.py --n 8 --out "$RUNNER_TEMP/v2" + python ../scripts/compare_csv.py "$RUNNER_TEMP/v2/errors_v2_n8.csv" results/errors_v2_n8.csv + + rtl: + name: RTL vs Python models (Icarus Verilog) + runs-on: ubuntu-latest + continue-on-error: true # optional job: depends on the distribution's iverilog package + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: python -m pip install -e . + - run: sudo apt-get update && sudo apt-get install -y --no-install-recommends iverilog + - name: Core units, exhaustive at n = 8, 7, 5 + run: | + python scripts/rtl_regress.py --out build | tee rtl.log + grep -q ' 0 FAIL/ERROR, 0 not simulated' rtl.log + - name: v2 units, exhaustive at n = 6, 5 + working-directory: v2 + run: python scripts/rtl_regress_v2.py --out build --widths 6,5 + - name: v2 testbench detects injected RTL faults + working-directory: v2 + run: python scripts/rtl_regress_v2.py --out build --mutations diff --git a/.gitignore b/.gitignore index e6d9e1d..0dd5127 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,22 @@ +# Python __pycache__/ -*.pyc -build/ +*.py[cod] *.egg-info/ +build/ +dist/ +.pytest_cache/ +.ruff_cache/ +.mypy_cache/ +.venv/ +venv/ + +# RTL regression / synthesis scratch (scripts write to build/ by default) +*.vvp +*.vcd +v2/build/ +*.partial.csv + +# Editors / OS +.idea/ +.vscode/ +.DS_Store diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..04224bb --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,9 @@ +cff-version: 1.2.0 +message: If you use this software, please cite it as below. +title: ApproxKit +type: software +authors: + - given-names: Kavin + family-names: K K + alias: Kavin-Re +repository-code: https://github.com/Kavin-Re/ApproxKit diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1a0dcb1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,32 @@ +# Code of Conduct + +This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). The full text at that link applies; this is a summary. + +## Our pledge + +We pledge to make participation in ApproxKit a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, nationality, personal appearance, race, religion, or sexual identity and orientation. + +## Expected behaviour + +- Be respectful, welcoming and constructive. +- Accept feedback gracefully and give it kindly. +- Focus on what is best for the project and community. + +## Unacceptable behaviour + +- Harassment, insults, trolling, or personal or political attacks. +- Sexualized language or imagery, and unwelcome attention. +- Publishing others' private information without permission. +- Other conduct that would reasonably be considered inappropriate in a professional setting. + +## Enforcement + +Maintainers may remove, edit or reject comments, commits, issues and other contributions that violate this code, and may ban contributors for behaviour they deem harmful. + +## Reporting + +To report a problem, open an issue at https://github.com/Kavin-Re/ApproxKit/issues without including sensitive details, and ask for private follow-up. Maintainers will respond and handle reports with discretion. + +## Attribution + +Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1d2e8fb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing to ApproxKit + +Thanks for your interest. ApproxKit provides bit-accurate Python models, error metrics, a Pareto explorer and Verilog for approximate adders and multipliers. + +## Getting started + +``` +pip install -e ".[plots,test]" # numpy; matplotlib for plots; pytest optional +python examples/run_dse.py --n 8 +python examples/demo_apps.py +``` + +## Testing + +``` +python tests/test_units.py # plain asserts (pytest tests also works) +python scripts/rtl_regress.py --out build --synth # Python models vs Verilog; needs iverilog and yosys +``` + +The Python model and the Verilog must stay bit-exact; the RTL regression is the check for that. + +## Pull requests + +- Open an issue first for larger changes. +- Keep PRs focused and fill in the pull request template. +- Follow `.editorconfig` and match the style of surrounding code. +- Say which simulator and tool versions you used for RTL changes. + +## Conduct + +Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index ba4871f..b089c50 100644 --- a/README.md +++ b/README.md @@ -1,165 +1,245 @@ # ApproxKit -Bit-accurate Python models, error metrics, a Pareto design-space explorer and -Verilog implementations of approximate adders and multipliers. Written to be -reused across projects (correlators / MAC arrays, small neural-net datapaths, -filters). Dependencies: `numpy` (matplotlib only for plots). Plain Python -asserts for tests (pytest also works if installed). MIT licence (change if you prefer). - -``` -approxkit/ package: adders.py multipliers.py metrics.py cost.py dse.py apps.py plotting.py -examples/ run_dse.py (Pareto + plots), demo_apps.py (FIR / dot / matmul) -rtl/ Verilog-2001 units (one module per file) -scripts/ rtl_regress.py: Python models -> exhaustive vectors -> iverilog self-check -> yosys -tests/ test_units.py (scalar reference models, metrics, apps) -results/ CSVs, PNGs and logs produced by the runs described below +[![CI](https://github.com/Kavin-Re/ApproxKit/actions/workflows/ci.yml/badge.svg)](https://github.com/Kavin-Re/ApproxKit/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) +![Python](https://img.shields.io/badge/python-3.9%2B-blue) +![HDL](https://img.shields.io/badge/HDL-Verilog--2001-lightgrey) + +Bit-accurate Python models, error metrics, a Pareto design-space explorer and matching +Verilog for approximate adders and multipliers. Every Verilog unit is checked against its +Python model over **all** operand pairs, and every Python model against an independent +bit-level reference. + +```mermaid +flowchart LR + M["Python models
(numpy, bit-accurate)"] --> E["Error metrics
ER / MED / MRED / NMED / WCE"] + M --> C["Cost proxy
(gate equivalents)"] + E --> P["Pareto front
error vs cost"] + C --> P + M --> A["Application demos
FIR, dot product, matmul"] + M -- "exhaustive vectors" --> V["Verilog units (rtl/)
iverilog self-check"] + V --> Y["yosys synthesis
generic gates / sky130"] + Y -. "rank check" .-> C ``` -## Quick start +## Install and quick start + +```bash +pip install -e . # needs numpy; add ".[plots]" for matplotlib, ".[test]" for pytest +``` ```python import numpy as np, approxkit as ak + add = ak.LOA(8, k=3) # 8-bit lower-part-OR adder, 3 approximate bits mul = ak.DRUM(8, k=4) # 8-bit DRUM with 4-bit segments add(200, 100), mul(np.array([13, 200]), np.array([9, 77])) # numpy-vectorised, unsigned m = ak.evaluate(mul) # exhaustive for n <= 12, Monte Carlo above -m.ER, m.MED, m.MRED, m.NMED, m.WCE # see definitions below +m.ER, m.MED, m.MRED, m.NMED, m.WCE # definitions below counts, edges = m.histogram(bins=61) # signed-error distribution mul.area_ge() # gate-equivalent PROXY (not synthesized area) ak.make("multiplier", "booth", 16, k=10) # factory by family name ``` -Run `python examples/run_dse.py --n 8` (or `--n 16`), `python examples/demo_apps.py`, -`python tests/test_units.py`, `python scripts/rtl_regress.py --out build --synth` (needs iverilog, yosys). -## Units (all unsigned; adders n -> n+1 bits, multipliers n x n -> 2n bits) +```bash +python examples/run_dse.py --n 8 # sweep + Pareto plots + CSV (use --n 16 for Monte Carlo) +python examples/demo_apps.py # FIR / dot product / matmul accuracy +python -m pytest # unit tests (core + v2) +python scripts/rtl_regress.py --out build --synth # RTL vs model; needs iverilog (and yosys for --synth) +``` + +## Repository layout -| Class | Parameters | Definition (bit-exact, same in Python and Verilog) | +| Path | Contents | +|---|---| +| `approxkit/` | The installable library: `adders.py`, `multipliers.py`, `metrics.py`, `cost.py`, `dse.py`, `apps.py`, `plotting.py` | +| `rtl/` | Verilog-2001 implementation of every unit, one module per file | +| `tests/` | Scalar bit-level reference models, metric and Pareto checks | +| `scripts/` | `rtl_regress.py` (models -> exhaustive vectors -> iverilog self-check -> optional yosys), `compare_csv.py` | +| `examples/` | `run_dse.py`, `demo_apps.py` | +| `results/` | CSVs, plots and logs produced by the runs reported below | +| `v2/` | Follow-on study built on top of the library: signed multipliers, dividers, reciprocal, squarers, FPGA-flow cost ranking, image/FIR quality. Separate package `approxkit_v2`, own RTL, tests and results. See [`v2/README.md`](v2/README.md) | + +`approxkit/` is the stable, unsigned core. `v2/` imports it unchanged and is run from the +source tree; it is not part of the installed package. + +## Units + +All units are unsigned. Adders map n-bit operands to n+1 bits; multipliers n x n to 2n bits. +The definitions below are bit-exact and identical in Python and Verilog. + +| Class | Parameters | Definition | |---|---|---| -| `ExactAdder`, `ExactMultiplier` | n | references | -| `LOA` | k | low k sum bits = a OR b; carry into the exact upper part = a[k-1] AND b[k-1] | -| `TruncatedAdder` | k | upper n-k bits added exactly, low k result bits = 0, no carry from the low part | -| `ETA` (ETA-I flavour) | k | upper part exact with no carry-in; low part scanned from bit k-1 down: sum = a XOR b until the first bit where a=b=1, which and all lower bits become 1 | -| `GeAr` (ACA-style for R=1) | R, P | sub-adders of length L=R+P, each producing R new bits from P predictor bits (carry-in speculated 0); last block anchored at the MSB; L=n is exact | -| `AMA` (simplified FA cells) | k, cell | low k bits use a simplified full-adder cell (`sum_b`: Sum=b, Cout=a; `inv_carry`: Cout=maj, Sum=NOT Cout). These two cells are *my choice in the spirit of* mirror-adder approximations, not copies of a specific published cell | -| `TruncatedMultiplier` | k | partial-product bits in columns < k dropped, no compensation | -| `BrokenArray` | vbl, hbl | rows i < hbl dropped and columns < vbl dropped, rest summed exactly | -| `DRUM` | k | k-bit segment from the leading one with LSB forced to 1 if bits were discarded; exact k x k product, shifted back; operands < 2^k exact | -| `Mitchell` | - | log2 x ~ K + f, add in fixed point (n-1 fraction bits), linear antilog, floor. Always underestimates | -| `BoothApprox` | k | radix-4 Booth (unsigned input handled with n//2+1 digits); each partial-product *magnitude* has columns < k cleared, then it is negated if the digit is negative; sum mod 2^2n (k=0 exact) | - -Constraints: `0 <= k <= n-1` for adders (Verilog: `1 <= k <= n-1`); n <= 31 -(int64 arithmetic). Signed use: apply sign-magnitude around the unsigned unit -(`approxkit.apps.signed_mul`). +| `ExactAdder`, `ExactMultiplier` | n | References | +| `LOA` | k | Low k sum bits = a OR b; carry into the exact upper part = a[k-1] AND b[k-1] | +| `TruncatedAdder` | k | Upper n-k bits added exactly, low k result bits = 0, no carry from the low part | +| `ETA` (ETA-I flavour) | k | Upper part exact with no carry-in; low part scanned from bit k-1 down: sum = a XOR b until the first bit where a = b = 1; that bit and all lower bits become 1 | +| `GeAr` (ACA-style for R = 1) | R, P | Sub-adders of length L = R + P, each producing R new bits from P predictor bits (carry-in speculated 0); last block anchored at the MSB; L = n is exact | +| `AMA` | k, cell | Low k bits use a simplified full-adder cell (`sum_b`: Sum = b, Cout = a; `inv_carry`: Cout = majority, Sum = NOT Cout). These two cells are this project's own, in the spirit of mirror-adder approximations, not copies of a published cell | +| `TruncatedMultiplier` | k | Partial-product bits in columns < k dropped, no compensation | +| `BrokenArray` | vbl, hbl | Rows i < hbl and columns < vbl dropped, the rest summed exactly | +| `DRUM` | k | k-bit segment from the leading one, LSB forced to 1 if bits were discarded; exact k x k product shifted back; operands < 2^k are exact | +| `Mitchell` | - | log2 x ~ K + f, added in fixed point (n-1 fraction bits), linear antilog, floor. Always underestimates | +| `BoothApprox` | k | Radix-4 Booth (n//2 + 1 digits for unsigned input); each partial-product *magnitude* has columns < k cleared, then is negated if the digit is negative; sum modulo 2^2n (k = 0 is exact) | + +Constraints: `0 <= k <= n-1` for adders (Verilog: `1 <= K <= N-1`), `2 <= n <= 31` (int64 +arithmetic). Non-integer or out-of-range parameters raise `ValueError`. For signed operands +use the sign-magnitude wrapper `approxkit.apps.signed_mul`, or the native signed units in `v2/`. ## Error metrics -With e = approx - exact over the evaluated pairs (uniform inputs): -**ER** = P(e != 0); **MED** = mean |e|; **MRED** = mean |e|/exact over pairs with exact != 0; -**NMED** = MED / (max exact output: 2(2^n-1) for adders, (2^n-1)^2 for multipliers); -**WCE** = max |e|; also reported: signed mean error (`bias`) and RMSE. -Exhaustive for n <= 12 (up to n = 14 can be forced); otherwise Monte Carlo -(default 2^20 seeded uniform pairs). Monte-Carlo WCE is only a *lower bound* of the true -worst case. Uniform inputs are rarely the real distribution of your application: -re-run `evaluate` on your own operand statistics (pass arrays through the unit directly) -before trusting MRED/NMED for a design. +With e = approx - exact over the evaluated operand pairs (uniform inputs): + +| Metric | Definition | +|---|---| +| ER | P(e != 0) | +| MED | mean \|e\| | +| MRED | mean \|e\| / exact, over pairs with exact != 0 | +| NMED | MED / maximum exact output: 2(2^n - 1) for adders, (2^n - 1)^2 for multipliers | +| WCE | max \|e\| | +| bias, RMSE | mean e (signed), root mean square of e | + +Evaluation is exhaustive for n <= 12 (n <= 14 can be forced), otherwise Monte Carlo +(default 2^20 seeded uniform pairs). A Monte-Carlo WCE is only a *lower bound* on the true +worst case. Uniform operands are rarely the distribution of a real application: evaluate on +your own operand statistics before trusting MRED/NMED for a design. ## Cost model (a proxy) -`approxkit/cost.py`: NAND2 = 1 GE, AND/OR 1.5, XOR 2.5, MUX 2.5, HA 4, FA 9.5. -Adders are ripple structures; multipliers use carry-save bit counting -(#FA = kept partial-product bits - active columns); shifters/leading-one detectors are -heuristics. **This is a ranking proxy, not synthesized area**: no wiring, no timing, no sizing. -`delay_levels()` gives the longest carry chain for adders. Sanity check against -synthesis is in the next section; the proxy is clearly wrong for some structures -(it understates Mitchell's shifters and ETA's control logic, and overstates GeAr's cost -for the small overlaps). - -## Results from this build - -**Tests.** `tests/test_units.py`: 10/10 pass (every unit against an independent scalar bit-level -reference over all operand pairs at n=6, plus exactness limits, known values, Mitchell -never overestimates, metrics vs brute force, Monte-Carlo vs exhaustive, apps). - -**Verilog vs Python (iverilog 12.0, exhaustive).** `scripts/rtl_regress.py`: 173/173 cases pass -(61 configurations at n = 8, the same families at n = 7 and n = 5, every one of the 2^(2n) operand pairs compared bit-for-bit, including odd widths and -non-divisible GeAr windows). The testbench was verified to fail when the RTL is deliberately broken -(two mutations tried). Log: `results/rtl_regress.log`. - -**Synthesis (yosys 0.33, n = 8, `synth -flatten` then `abc`).** Two numbers per design in -`results/rtl_synth_n8.csv`: generic-gate count / GE-weighted count (same GE weights as the proxy), -and, mapped to the sky130 high-density liberty used on the build machine, the cell area in um^2 -(yosys+abc only: no place&route, no timing). These are *synthesis estimates, not silicon area*. -Rank agreement with the proxy (Spearman): 0.94 (adders) / 0.92 (multipliers) against the sky130 -area, 0.70 / 0.88 against generic gate counts. Important caveat: `bam_mult`, `trunc_mult` and -`booth_mult` accumulate partial products with a sequential chain of `+`, whereas `exact_mult` uses `*` -(yosys builds a macc/carry-save structure). The fair baseline for those three is `bam_mult` with -VBL=0/HBL=0 (2054 um^2), not `exact_mult` (1927 um^2). A hand-built compressor tree would shift every -multiplier number. - -**Pareto highlights, n = 8, exhaustive, error = MRED** (sky130 area from synthesis above): - -| design | MRED | NMED | sky130 area (um^2) | exact reference | -|---|---|---|---|---| +`approxkit/cost.py`: NAND2 = 1 GE, AND/OR 1.5, XOR 2.5, MUX 2.5, HA 4, FA 9.5. Adders are +ripple structures; multipliers use carry-save bit counting (#FA = kept partial-product bits +minus active columns); shifters and leading-one detectors are heuristics. +**This is a ranking proxy, not synthesized area**: no wiring, timing or sizing. +`delay_levels()` gives the longest carry chain for adders. The proxy is known to be wrong for +some structures: it understates Mitchell's shifters and ETA's control logic and overstates +GeAr's cost for small overlaps. The synthesis cross-check is below. + +`dse.pareto_front(rows, cost_key, err_key)` returns the non-dominated designs when minimising +both keys, sorted by increasing cost. + +## Results + +All numbers below come from files in `results/`; nothing is quoted from the literature. + +**Tests.** `python -m pytest`: 28 tests (13 core, 15 v2). Every unit is compared with an +independent scalar bit-level reference over all operand pairs at n = 6 and on random and corner operands at n = 16, 24 and 31, plus exactness +limits, known values, parameter validation, metrics against brute force, Monte Carlo against +exhaustive, a brute-force non-dominance check of the Pareto front, and the application demos. + +**Verilog vs Python (iverilog 12.0, exhaustive).** `scripts/rtl_regress.py`: 173/173 cases +pass (61 configurations at n = 8 and the same families at n = 7 and n = 5; all 2^(2n) +operand pairs compared bit-for-bit, including odd widths and non-divisible GeAr windows). +The testbench was confirmed to fail on deliberately broken RTL (two mutations tried). +Log: `results/rtl_regress.log`. + +**Synthesis (yosys 0.33, n = 8, `synth -flatten` then `abc`).** `results/rtl_synth_n8.csv` +holds, per design, the generic-gate count, its GE-weighted sum (same weights as the proxy) +and the cell area after mapping to a sky130 high-density liberty (yosys + abc only: no place +and route, no timing). These are *synthesis estimates, not silicon area*. Spearman rank +agreement between proxy and synthesis: 0.94 (adders) / 0.92 (multipliers) against sky130 +area, 0.70 / 0.88 against generic gate counts. + +Caveat: `bam_mult`, `trunc_mult` and `booth_mult` accumulate partial products with a +sequential chain of `+`, whereas `exact_mult` uses `*` (yosys builds a carry-save structure). +The fair baseline for those three is `bam_mult` with VBL = 0, HBL = 0 (2054 um^2), not +`exact_mult` (1927 um^2). A hand-built compressor tree would shift every multiplier number. + +**Pareto highlights, n = 8, exhaustive** (area: sky130 synthesis estimate): + +| Design | MRED | NMED | sky130 area (um^2) | Exact reference (um^2) | +|---|---:|---:|---:|---| | LOA k=2 | 0.34 % | 0.12 % | 184 | exact adder 208 | -| ETA k=2 | 0.37 % | 0.14 % | 168 | | +| ETA k=2 | 0.37 % | 0.13 % | 168 | | | LOA k=4 | 1.5 % | 0.56 % | 141 | | -| truncated mult k=6 | 2.6 % | 0.12 % | 1292 | array-with-adder-chain 2054 | -| truncated mult k=8 | 9.8 % | 0.69 % | 905 | | +| Truncated mult k=6 | 2.6 % | 0.12 % | 1292 | adder-chain array 2054 | +| Truncated mult k=8 | 9.8 % | 0.69 % | 905 | | | Booth-approx k=8 | 4.8 % | 0.24 % | 1132 | | | DRUM-4 | 5.9 % | 1.4 % | 1295 | | | DRUM-6 | 1.3 % | 0.36 % | 1647 | | | Mitchell | 3.8 % | 0.93 % | 1848 | no saving at n = 8 | -Findings (n = 8): the best low-error multiplier designs on both the proxy and the synthesized area are -the column-truncation/broken-array/Booth-approx family (DRUM reaches the synthesized Pareto front -only at isolated points: k = 2, 6, 7), and Mitchell gives no area benefit at 8 bits in this implementation (its barrel shifters and -detectors cost about as much as the exact multiplier), though its relative error is data-independent -and one-sided. Adders: LOA and ETA win at small k; the `sum_b` AMA cell is the cheapest at larger k -but errs on almost every input (ER ~ 94 % at k=4), ETA and LOA have similar MRED at equal k -(ETA's WCE is about 2x larger at k=4) and ETA's control chain costs more proxy area. GeAr buys delay (carry chain = L), not area: its cost is -higher than the exact ripple adder, and a missed carry costs a large error (2^L-scale), which -is visible in the accumulator demo. Full sweeps: `results/dse_*_n8.csv`, `results/dse_*_n16.csv`, -Pareto plots `results/pareto_*.png`, histograms `results/errhist_*.png`. -(The n = 16 sweep is Monte Carlo, 2^20 samples, seed 0.) - -**Application demos** (`results/apps_*.csv/png`, 8-bit multipliers; 31-tap FIR on a noisy two-tone -signal, 256-long dot products, 16x16 uint8 matmul; accuracy vs exact): e.g. Mitchell gives 31 dB FIR SNR -(dot-product relative RMS 5 %, matmul 3.4 %); truncated k=1 gives 66 dB; DRUM-2 only 9.8 dB. With an exact -multiplier and 24-bit accumulators, LOA k=4 gives 47 dB FIR SNR vs 43.5 dB for truncated/ETA k=4, and -GeAr(R=4,P=8) is very poor on dot products (relative RMS 0.49) because missed carries are large. FIR operands here -span only 7 bits, so DRUM-7 is trivially exact there. -Sign handling: magnitudes go through the unsigned unit, accumulation uses separate positive and -negative accumulators. +Findings at n = 8: + +* **Multipliers.** The best low-error designs on both the proxy and the synthesized area are + the column-truncation / broken-array / Booth-approx family. DRUM reaches the synthesized + Pareto front only at isolated points (k = 2, 6, 7). Mitchell gives no area benefit at 8 + bits in this implementation (its barrel shifters and detectors cost about as much as the + exact multiplier), although its relative error is data-independent and one-sided. +* **Adders.** LOA and ETA win at small k. The `sum_b` AMA cell is cheapest at larger k but + errs on almost every input (ER ~ 94 % at k = 4). ETA and LOA have similar MRED at equal k, + but ETA's worst-case error is about twice LOA's at k = 4 and its control chain costs more. +* **GeAr buys delay, not area.** Its carry chain is L bits, but its cost exceeds the exact + ripple adder, and a missed carry is a large (2^L-scale) error. + +Full sweeps: `results/dse_*_n8.csv` (exhaustive) and `results/dse_*_n16.csv` (Monte Carlo, +2^20 samples, seed 0); Pareto plots `results/pareto_*.png`; histograms `results/errhist_*.png`. +The n = 8 CSVs are regenerated and compared in CI. + +**Application demos** (`results/apps_*.csv`, 8-bit multipliers; 31-tap FIR on a noisy +two-tone signal, 256-term dot products, 16 x 16 uint8 matmul; accuracy against exact): +Mitchell gives 31 dB FIR SNR (dot-product relative RMS 5 %, matmul 3.4 %); truncated k = 1 +gives 66 dB; DRUM-2 only 9.8 dB. With an exact multiplier and 24-bit accumulators, LOA k = 4 +gives 47 dB FIR SNR against 43.5 dB for truncated / ETA k = 4, and GeAr(R=4, P=8) is very +poor on dot products (relative RMS 0.49) because missed carries are large. FIR operands +here span only 7 bits, so DRUM-7 is trivially exact. Signed data is handled by passing +magnitudes through the unsigned unit and accumulating positive and negative terms +separately; `v2/RESULTS_V2.md` section 5 shows that this organisation makes ETA and +truncation accumulators produce identical results, and repeats the comparison with a single +two's-complement accumulator. ## Verilog (`rtl/`) `exact_adder`, `loa_adder`, `trunc_adder`, `eta_adder`, `gear_adder`, `ama_adder`, `exact_mult`, `bam_mult`, `trunc_mult`, `drum_mult`, `mitchell_mult`, `booth_mult`. -All have ports `a`, `b`, `y` and parameters `N` plus the unit parameter names above (upper case). -Plain Verilog-2001 (`$clog2`), purely combinational, written for clarity rather than timing; the -multipliers use behavioural `for` loops and `+` chains that synthesis tools restructure. -Regenerate vectors/testbenches: `python scripts/rtl_regress.py --out build [--widths 8,7,5] [--no-sim] [--synth] [--liberty file.lib]`. - -## Honest limits - -* Unsigned only; signed operation via sign-magnitude wrappers (extra hardware not modelled). -* Cost = proxy; do not quote GE or the sky130 numbers as area for a PolarFire/other-FPGA flow. On an - FPGA, carry chains and LUT mapping change the picture entirely (an exact adder is already fast and cheap - there, and many approximations save nothing); synthesize on your actual target. -* No delay/power model beyond the adder carry-chain length. -* Metrics assume uniform independent operands; real signals (e.g. correlator inputs, NN activations) differ. -* Booth unit uses a sign-magnitude truncation definition of mine; the two `AMA` cells are mine; the - other units follow the usual descriptions of each technique but exact variants in papers differ in details - (e.g. compensation constants), so numbers will not match published tables. -* No literature numbers are quoted anywhere in this repository. - -## References (only those I am sure of) - -* J. N. Mitchell Jr., "Computer Multiplication and Division Using Binary Logarithms", IRE Trans. Electronic Computers, 1962. -* S. Hashemi, R. I. Bahar, S. Reda, "DRUM: A Dynamic Range Unbiased Multiplier for Approximate Applications", ICCAD 2015. - -The remaining techniques (lower-part-OR adders, error-tolerant adders, generic accuracy-configurable -adders / almost-correct adders, mirror-adder approximations, broken-array multipliers, approximate Booth -multipliers) are described from general knowledge of the techniques without citation. + +All modules have ports `a`, `b`, `y` and parameter `N` plus the unit parameters above in +upper case. Plain Verilog-2001 (`$clog2`), purely combinational, written for clarity rather +than timing; the multipliers use behavioural `for` loops and `+` chains that synthesis tools +restructure. + +```bash +python scripts/rtl_regress.py --out build [--widths 8,7,5] [--no-sim] [--synth] [--liberty file.lib] +``` + +## Limitations + +* The core library is unsigned; signed operation uses sign-magnitude wrappers whose extra + hardware is not modelled (native signed units are in `v2/`). +* Cost is a proxy. Do not quote GE or the sky130 numbers as area for an FPGA flow: carry + chains and LUT mapping change the picture entirely (an exact adder is already fast and + cheap on an FPGA, and many approximations save nothing). Synthesize on the actual target. + `v2/RESULTS_V2.md` section 3 quantifies how weakly LUT counts track sky130 area. +* No delay or power model beyond the adder carry-chain length. +* Metrics assume uniform, independent operands. +* The Booth unit uses this project's own sign-magnitude truncation and the two `AMA` cells + are this project's own. The other units follow the usual descriptions of each technique, + but published variants differ in details (for example compensation constants), so numbers + will not match published tables. +* RTL equivalence was run at n = 5, 7 and 8 only. Wider instances (n = 16, 24, 31) are + checked in Python against arbitrary-precision references on random and corner operands, + not by simulation. + +## Related work in this account + +ApproxKit is an independent, general-purpose library. It shares its subject with +my approximate-SAD research project +(approximate 4:2-compressor SAD units for video motion estimation; repository private until publication) but no code: there are no +compressor or SAD models here. + +## References + +* J. N. Mitchell Jr., "Computer Multiplication and Division Using Binary Logarithms", + *IRE Transactions on Electronic Computers*, 1962. +* S. Hashemi, R. I. Bahar, S. Reda, "DRUM: A Dynamic Range Unbiased Multiplier for + Approximate Applications", ICCAD 2015. + +The remaining techniques (lower-part-OR adders, error-tolerant adders, generic +accuracy-configurable / almost-correct adders, mirror-adder approximations, broken-array +multipliers, approximate Booth multipliers) are implemented from their standard textbook +descriptions; consult the original papers before comparing numbers. + +## License + +Released under the [MIT License](LICENSE). diff --git a/approxkit/adders.py b/approxkit/adders.py index 6a06bbc..445143b 100644 --- a/approxkit/adders.py +++ b/approxkit/adders.py @@ -6,7 +6,7 @@ (0 <= k <= n-1); k = 0 is the exact adder where applicable. """ import numpy as np -from .base import ApproxUnit +from .base import ApproxUnit, as_int from . import cost from .cost import GE @@ -34,9 +34,10 @@ class _LowerK(ApproxUnit): def __init__(self, n, k): super().__init__(n) - if not (0 <= k <= n - 1): + k = as_int("k", k) + if not (0 <= k <= self.n - 1): raise ValueError("k must satisfy 0 <= k <= n-1") - self.k = int(k) + self.k = k @property def params(self): @@ -128,7 +129,8 @@ class GeAr(ApproxUnit): def __init__(self, n, R, P): super().__init__(n) - R, P = int(R), int(P) + R, P = as_int("R", R), as_int("P", P) + n = self.n if R < 1 or P < 0 or R + P > n: raise ValueError("need R>=1, P>=0, R+P<=n") self.R, self.P, self.L = R, P, R + P diff --git a/approxkit/base.py b/approxkit/base.py index c51f3f8..896705f 100644 --- a/approxkit/base.py +++ b/approxkit/base.py @@ -16,13 +16,25 @@ def msb_pos(x, n): return pos +def as_int(name, value): + """Return `value` as int; reject non-integral values (e.g. k=2.5) instead of + silently truncating them.""" + try: + i = int(value) + except (TypeError, ValueError): + raise ValueError(f"{name} must be an integer, got {value!r}") from None + if i != value: + raise ValueError(f"{name} must be an integer, got {value!r}") + return i + + class ApproxUnit: kind = None # "adder" | "multiplier" family = "base" MAX_N = 31 def __init__(self, n): - n = int(n) + n = as_int("n", n) if not (2 <= n <= self.MAX_N): raise ValueError(f"{type(self).__name__}: n must be in [2,{self.MAX_N}]") self.n = n diff --git a/approxkit/dse.py b/approxkit/dse.py index a197b9b..26c2d2a 100644 --- a/approxkit/dse.py +++ b/approxkit/dse.py @@ -49,8 +49,13 @@ def explore(units, mode="auto", samples=1 << 20, seed=0): def pareto_front(rows, cost_key="area_ge", err_key="MRED"): - """Non-dominated rows (minimise both). Ties on both are all kept out - except the first; result sorted by increasing cost.""" + """Non-dominated rows when minimising both `cost_key` and `err_key`. + + A row is kept iff no other row is at least as good on both axes and + strictly better on one. Of several rows with identical (cost, error) only + the first is kept. The result is sorted by increasing cost (and therefore + strictly decreasing error). + """ pts = sorted(rows, key=lambda r: (r[cost_key], r[err_key])) front, best = [], float("inf") for r in pts: diff --git a/approxkit/metrics.py b/approxkit/metrics.py index 4a80c5d..da5ea0e 100644 --- a/approxkit/metrics.py +++ b/approxkit/metrics.py @@ -1,4 +1,4 @@ -"""Error metrics: exhaustive (n <= 12) or Monte Carlo (wider). +"""Error metrics: exhaustive (n <= 12 by default, n <= 14 on request) or Monte Carlo (wider). Error e = approx - exact (signed). With N evaluated input pairs: ER = P(e != 0) @@ -90,6 +90,9 @@ def evaluate(unit, mode="auto", samples=1 << 20, seed=0, chunk=1 << 22): B = np.tile(full, av.size) _accumulate(unit, A, B, st) elif mode == "monte_carlo": + if int(samples) < 1: + raise ValueError("monte_carlo needs samples >= 1") + samples = int(samples) rng = np.random.default_rng(seed) left = samples while left > 0: diff --git a/approxkit/multipliers.py b/approxkit/multipliers.py index a3adf3b..3c3cd6c 100644 --- a/approxkit/multipliers.py +++ b/approxkit/multipliers.py @@ -1,6 +1,6 @@ """Approximate multipliers (unsigned n x n -> 2n bits), bit-accurate.""" import numpy as np -from .base import ApproxUnit, msb_pos +from .base import ApproxUnit, as_int, msb_pos from . import cost from .cost import GE @@ -40,9 +40,10 @@ class BrokenArray(ApproxUnit): def __init__(self, n, vbl, hbl=0): super().__init__(n) - if not (0 <= vbl <= 2 * n and 0 <= hbl <= n): + vbl, hbl = as_int("vbl", vbl), as_int("hbl", hbl) + if not (0 <= vbl <= 2 * self.n and 0 <= hbl <= self.n): raise ValueError("0<=vbl<=2n, 0<=hbl<=n") - self.vbl, self.hbl = int(vbl), int(hbl) + self.vbl, self.hbl = vbl, hbl @property def params(self): @@ -90,9 +91,10 @@ class DRUM(ApproxUnit): def __init__(self, n, k): super().__init__(n) - if not (2 <= k <= n): + k = as_int("k", k) + if not (2 <= k <= self.n): raise ValueError("2 <= k <= n") - self.k = int(k) + self.k = k @property def params(self): @@ -165,10 +167,11 @@ class BoothApprox(ApproxUnit): def __init__(self, n, k): super().__init__(n) - if not (0 <= k <= 2 * n): + k = as_int("k", k) + if not (0 <= k <= 2 * self.n): raise ValueError("0 <= k <= 2n") - self.k = int(k) - self.D = n // 2 + 1 + self.k = k + self.D = self.n // 2 + 1 @property def params(self): diff --git a/pyproject.toml b/pyproject.toml index ad5d0e5..14f3bca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,15 +5,47 @@ build-backend = "setuptools.build_meta" [project] name = "approxkit" version = "0.1.0" -description = "Bit-accurate approximate adders/multipliers, error metrics, Pareto explorer, Verilog" +description = "Bit-accurate approximate adders and multipliers: Python models, error metrics, Pareto design-space exploration and matching Verilog" readme = "README.md" requires-python = ">=3.9" -dependencies = ["numpy"] license = { text = "MIT" } +authors = [{ name = "Kavin K K" }] +keywords = ["approximate computing", "approximate adder", "approximate multiplier", "verilog", "design space exploration", "error metrics"] +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)", +] +dependencies = ["numpy"] [project.optional-dependencies] plots = ["matplotlib"] test = ["pytest"] +dev = ["pytest", "matplotlib", "ruff"] + +[project.urls] +Homepage = "https://github.com/Kavin-Re/ApproxKit" +Issues = "https://github.com/Kavin-Re/ApproxKit/issues" [tool.setuptools] +# Only the core library is installable. v2/ (signed multipliers, dividers, +# squarers, application-quality study) is a research extension run from the +# source tree; see v2/README.md. packages = ["approxkit"] + +[tool.pytest.ini_options] +minversion = "7.0" +testpaths = ["tests", "v2/tests"] +pythonpath = [".", "v2", "v2/scripts"] +addopts = "-ra" + +[tool.ruff] +line-length = 130 +target-version = "py39" +extend-exclude = ["build"] + +[tool.ruff.lint] +# Correctness rules only; the code base uses a compact style on purpose. +select = ["E9", "F"] diff --git a/scripts/compare_csv.py b/scripts/compare_csv.py new file mode 100755 index 0000000..9f034c2 --- /dev/null +++ b/scripts/compare_csv.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""Compare two CSV files cell by cell; numeric cells may differ by a relative +tolerance (floating-point summation order can change the last digits between +numpy builds), everything else must match exactly. + + python scripts/compare_csv.py new.csv results/dse_adder_n8.csv [--rtol 1e-9] + +Exit status 0 if equivalent, 1 otherwise. Standard library only. +""" +import argparse +import csv +import math +import sys + + +def same(x, y, rtol): + if x == y: + return True + try: + fx, fy = float(x), float(y) + except ValueError: + return False + if math.isnan(fx) and math.isnan(fy): + return True + return math.isclose(fx, fy, rel_tol=rtol, abs_tol=1e-12) + + +def main(): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("new") + ap.add_argument("reference") + ap.add_argument("--rtol", type=float, default=1e-9) + a = ap.parse_args() + with open(a.new, newline="") as f: + new = list(csv.reader(f)) + with open(a.reference, newline="") as f: + ref = list(csv.reader(f)) + if len(new) != len(ref): + print(f"row count differs: {len(new)} vs {len(ref)}") + return 1 + bad = 0 + for i, (rn, rr) in enumerate(zip(new, ref)): + if len(rn) != len(rr) or not all(same(x, y, a.rtol) for x, y in zip(rn, rr)): + bad += 1 + if bad <= 5: + print(f"row {i} differs:\n new: {rn}\n ref: {rr}") + print(f"{a.new} vs {a.reference}: {len(ref)} rows, {bad} differing") + return 1 if bad else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_units.py b/tests/test_units.py index c8aeac3..e5ae614 100644 --- a/tests/test_units.py +++ b/tests/test_units.py @@ -184,6 +184,35 @@ def test_multipliers_vs_scalar_reference(): check(ak.BoothApprox(n, 3), ref_booth(n, 3), n=n) +def test_wide_widths_vs_bigint_reference(): + """n = 16, 24, 31 (the int64 limit): numpy models against the arbitrary-precision + scalar references on corner values, single-bit operands and seeded random operands.""" + import random + rnd = random.Random(2026) + + def fuzz(unit, ref, n, cnt=400): + lim = (1 << n) - 1 + pick = lambda: rnd.choice([0, 1, lim, lim - 1, 1 << rnd.randrange(n), rnd.randint(0, lim), rnd.randint(0, lim)]) + a = [pick() for _ in range(cnt)] + [lim, lim, 0] + b = [pick() for _ in range(cnt)] + [lim, 0, lim] + got = unit(np.array(a, dtype=np.int64), np.array(b, dtype=np.int64)) + for x, y, g in zip(a, b, got.tolist()): + assert g == ref(x, y), f"{unit.name}: a={x} b={y} got={g} ref={ref(x, y)}" + + for n in (16, 24, 31): + fuzz(ak.LOA(n, n // 2), ref_loa(n, n // 2), n) + fuzz(ak.ETA(n, n - 1), ref_eta(n, n - 1), n) + fuzz(ak.AMA(n, n - 1, "inv_carry"), ref_ama(n, n - 1, "inv_carry"), n) + fuzz(ak.GeAr(n, 3, 5), ref_gear(n, 3, 5), n) + fuzz(ak.BrokenArray(n, n, 2), ref_bam(n, n, 2), n) + fuzz(ak.DRUM(n, 6), ref_drum(n, 6), n) + fuzz(ak.DRUM(n, n), ref_drum(n, n), n) + fuzz(ak.Mitchell(n), ref_mitchell(n), n) + fuzz(ak.BoothApprox(n, 0), ref_booth(n, 0), n) + fuzz(ak.BoothApprox(n, n), ref_booth(n, n), n) + fuzz(ak.ExactMultiplier(n), lambda x, y: x * y, n) + + def test_exact_limits(): for n in (5, 6): a = np.repeat(np.arange(1 << n), 1 << n) @@ -225,6 +254,42 @@ def test_range_check(): raise AssertionError("range check missing") +def test_parameter_validation(): + bad = [lambda: ak.LOA(8, 2.5), lambda: ak.LOA(8, 8), lambda: ak.LOA(8, -1), lambda: ak.GeAr(8, 0, 2), + lambda: ak.GeAr(8, 5, 4), lambda: ak.DRUM(8, 1), lambda: ak.DRUM(8, 9), lambda: ak.BoothApprox(8, 17), + lambda: ak.BrokenArray(8, 17), lambda: ak.TruncatedMultiplier(8, 1.5), lambda: ak.AMA(8, 2, "nope"), + lambda: ak.ExactAdder(1), lambda: ak.ExactAdder(32), lambda: ak.LOA(8, "x"), + lambda: evaluate(ak.LOA(8, 2), mode="monte_carlo", samples=0), + lambda: evaluate(ak.LOA(8, 2), mode="nonsense")] + for i, f in enumerate(bad): + try: + f() + except ValueError: + continue + raise AssertionError(f"case {i} did not raise ValueError") + assert ak.LOA(8, np.int64(3)).k == 3 and ak.LOA(8, 3.0).k == 3 # integral values are accepted + assert isinstance(ak.LOA(8, np.int64(3)).k, int) + + +def test_pareto_front_is_non_dominated(): + """Brute-force definition of non-dominance on a real n=6 sweep.""" + rows = dse.explore(dse.default_designs("adder", 6) + dse.default_designs("multiplier", 6)) + for kind_rows in ([r for r in rows if "add" in r["family"] or r["family"] in ("loa", "eta", "gear", "ama")], + [r for r in rows if r["family"] in ("exact_mul", "bam", "trunc_mul", "drum", "mitchell", "booth_approx")]): + for err in ("MRED", "NMED", "ER"): + front = dse.pareto_front(kind_rows, "area_ge", err) + pts = {(r["area_ge"], r[err]) for r in front} + + def dominated(r): + return any(o["area_ge"] <= r["area_ge"] and o[err] <= r[err] + and (o["area_ge"] < r["area_ge"] or o[err] < r[err]) for o in kind_rows) + expect = {(r["area_ge"], r[err]) for r in kind_rows if not dominated(r)} + assert pts == expect, (err, sorted(pts ^ expect)) + costs = [r["area_ge"] for r in front] + errs = [r[err] for r in front] + assert costs == sorted(costs) and errs == sorted(errs, reverse=True) and len(set(errs)) == len(errs) + + def test_metrics_vs_bruteforce(): u = ak.LOA(5, 2) m = evaluate(u, mode="exhaustive") diff --git a/v2/README.md b/v2/README.md new file mode 100644 index 0000000..dd7782a --- /dev/null +++ b/v2/README.md @@ -0,0 +1,39 @@ +# ApproxKit v2: signed multipliers, dividers, squarers and application quality + +A follow-on study built on the core library in [`../approxkit`](../approxkit). It imports +the core unchanged (the core is never modified from here) and adds units and experiments +that the unsigned core does not cover. + +| | Core (`approxkit/`) | v2 (`v2/approxkit_v2/`) | +|---|---|---| +| Units | Unsigned adders and multipliers | Signed multipliers (Baugh-Wooley truncated / OR-low, signed DRUM, sign-magnitude wrappers around the core units), unsigned dividers, reciprocal, squarers | +| Metrics | ER, MED, MRED, NMED, WCE, bias, RMSE | Same, plus MRED16 and 95 % confidence intervals for Monte Carlo | +| Cost | Gate-equivalent proxy, yosys generic gates / sky130 | yosys iCE40 / ECP5 LUT and carry counts, rank correlation against sky130 | +| Applications | FIR, dot product, matmul | Image convolution (PSNR / SSIM), FIR, dot product, with confidence intervals | +| Installed by `pip install` | Yes | No; run from this directory | + +## Layout + +| Path | Contents | +|---|---| +| `approxkit_v2/` | `signed.py`, `divsq.py`, `metrics2.py`, `quality.py`, `catalog.py` (the 75-design n = 8 catalogue), `common.py` | +| `rtl/` | Verilog for every v2 unit | +| `scripts/` | `error_sweep.py`, `rtl_regress_v2.py`, `synth_costs.py`, `fpga_rank.py`, `app_quality.py`, `pareto_plots.py`, `eta_vs_trunc.py` | +| `tests/test_v2.py` | Scalar bit-level references, structural properties, metric checks | +| `results/` | CSVs, logs and plots behind every claim | +| [`RESULTS_V2.md`](RESULTS_V2.md) | Findings, a claim-to-script-to-evidence table, and limits | + +## Run + +```bash +python -m pytest v2/tests # from the repository root +cd v2 +python scripts/error_sweep.py --n 8 --out results +python scripts/rtl_regress_v2.py --out build # needs iverilog +python scripts/rtl_regress_v2.py --out build --mutations # testbench must fail on injected faults +APPROXKIT_LIBERTY=/path/to/sky130_fd_sc_hd__tt_025C_1v80.lib \ + python scripts/synth_costs.py --n 8 --out results # needs yosys; liberty optional +``` + +All hardware cost numbers are estimates from generic yosys flows; none is a vendor-tool or +board result. Read `RESULTS_V2.md` section 6 ("Limits and not done") before reusing them. diff --git a/v2/RESULTS_V2.md b/v2/RESULTS_V2.md index 7a69dce..55d8d5a 100644 --- a/v2/RESULTS_V2.md +++ b/v2/RESULTS_V2.md @@ -1,6 +1,6 @@ # ApproxKit v2 - results, claim-to-script map, caveats -Everything below was produced by the scripts in `scripts/` (run from `v2/`, cloud container; yosys 0.33, iverilog 12.0, Python/numpy). +Everything below was produced by the scripts in `scripts/` (run from `v2/`; yosys 0.33, iverilog 12.0, Python/numpy). Raw numbers are in `results/*.csv`; this file contains no hand-typed measurement that is not in a CSV or log. All hardware cost numbers are **estimates from generic yosys flows**; **nothing here is a PolarFire result**. @@ -8,7 +8,7 @@ All hardware cost numbers are **estimates from generic yosys flows**; **nothing | # | Claim | Script | Evidence file | CI / exactness | Caveat | |---|-------|--------|---------------|----------------|--------| -| C1 | Python models of all 75 n=8 designs (signed BW trunc/OR-low, signed DRUM, sign-magnitude wrappers, dividers, reciprocal, squarers) are bit-identical to the Verilog | `scripts/rtl_regress_v2.py` (iverilog, self-checking bench, ALL operand combinations incl. b=0 / x=0) | `results/rtl_regress_v2.log`: 285 cases (n=8:75, n=7:74, n=6:71, n=5:65), 285 PASS, 0 FAIL | exhaustive, no sampling | RTL regression log is from the first part of the build (before the rate-limit cut); it was not re-run in this session. Mutation mode (`--mutations`) exists but its result is not part of this evidence. | +| C1 | Python models of all 75 n=8 designs (signed BW trunc/OR-low, signed DRUM, sign-magnitude wrappers, dividers, reciprocal, squarers) are bit-identical to the Verilog | `scripts/rtl_regress_v2.py` (iverilog, self-checking bench, ALL operand combinations incl. b=0 / x=0) | `results/rtl_regress_v2.log`: 285 cases (n=8:75, n=7:74, n=6:71, n=5:65), 285 PASS, 0 FAIL | exhaustive, no sampling | The RTL regression log is from the first part of the build and was not re-run afterwards. Mutation mode (`--mutations`) exists but its result is not part of this evidence. | | C2 | Models agree with independent scalar bit-by-bit references (BW matrix, OR-low, signed DRUM, literal restoring-division loop, squarer matrix) over all operand pairs at n=5,6 | `tests/test_v2.py` | `results/test_v2.log`: 15 tests, ALL PASS | exhaustive | the Mitchell/DRUM dividers and Mitchell squarer/reciprocal have no second independent reference, only structural checks (exact on powers of two, bounds, b=0 convention) plus the RTL equivalence of C1 | | C3 | Error metrics (ER, MED, MRED, MRED16, NMED, WCE, bias, RMSE) for every design, exhaustive at n=8 | `scripts/error_sweep.py`, `approxkit_v2/metrics2.py` | `results/errors_v2_n8.csv` | exact (CI half-width 0); Monte-Carlo path (16 batch means, t-95 %) is only used above 2^22 combinations and is checked against the exhaustive value in `test_monte_carlo_matches_exhaustive_within_ci` | MRED is over exact != 0; MRED16 over |exact| >= 16 to remove floor-quantisation artefacts of small quotients; divider metrics exclude b=0 | | C4 | Generic-flow FPGA cost estimates and their rank agreement with sky130 | `scripts/synth_costs.py`, `scripts/fpga_rank.py` | `results/costs_*.csv`, `results/rank_corr.csv` | Spearman/Kendall with 95 % bootstrap CI over designs | see section 3 | @@ -25,7 +25,7 @@ All hardware cost numbers are **estimates from generic yosys flows**; **nothing ## 3. Generic-vendor-flow FPGA cost vs sky130 ranking (C4) -**Labelled estimates, NOT PolarFire.** Flows: `synth_ice40`, `synth_ecp5 -nodsp`, (`synth_xilinx` was implemented in the script behind `--xilinx` but NOT run for the reported tables - too slow on the shared container), all yosys 0.33, `-flatten`, DSP inference disabled. "LUT4" columns count LUTs only; carry cells (SB_CARRY / CCU2C) are in separate columns and are not in the LUT count. `ice40nc_lut4` = iCE40 with `-nocarry` (adders mapped to LUTs). +**Labelled estimates, NOT PolarFire.** Flows: `synth_ice40`, `synth_ecp5 -nodsp`, (`synth_xilinx` is implemented in the script behind `--xilinx` but was NOT run for the reported tables - too slow on the build machine), all yosys 0.33, `-flatten`, DSP inference disabled. "LUT4" columns count LUTs only; carry cells (SB_CARRY / CCU2C) are in separate columns and are not in the LUT count. `ice40nc_lut4` = iCE40 with `-nocarry` (adders mapped to LUTs). Reference ranking: v1 flow sky130 (yosys + abc + sky130_fd_sc_hd tt, `results/rtl_synth_n8.csv` of v1; re-synthesis here reproduces it exactly, rho = 1.000 on the 25 v1 multipliers). | set (n designs) | iCE40 LUT4 | iCE40 -nocarry | ECP5 LUT4 | generic gate-equivalents | @@ -72,8 +72,8 @@ Interpretation: the identity is an artefact of the two-unsigned-accumulator orga * No PolarFire/Libero results; vendor-flow numbers are generic yosys estimates (section 3). `synth_xilinx` not run for the tables. * Cost analysis covers 71 of 75 v2 designs and 25 of 61 v1 designs (v1 adders omitted for time). -* Mutation testing of the RTL bench (`rtl_regress_v2.py --mutations`) was not run in this session; the claim that the bench detects broken RTL is untested here. -* RTL regression log predates this session (not re-run); Python-side tests were re-run (`results/test_v2.log`). +* Mutation testing of the RTL bench (`rtl_regress_v2.py --mutations`) has not been run; the claim that the bench detects broken RTL is untested. +* The RTL regression log is from the first part of the build (not re-run); the Python-side tests were re-run (`results/test_v2.log`). * Only n=8 cost/quality; n=5-7 used for equivalence testing only. No formal (z3/yosys-smtbmc) equivalence. * 8 synthetic images only; no natural-image evaluation; no PSNR on colour or video. * Unit-model RTL for dividers uses behavioural `/` (restoring-loop for `div_trunc`), so FPGA/ASIC divider costs depend on yosys's mapping of `/` and `%`. diff --git a/v2/scripts/synth_costs.py b/v2/scripts/synth_costs.py index f444a59..9e8d986 100644 --- a/v2/scripts/synth_costs.py +++ b/v2/scripts/synth_costs.py @@ -87,7 +87,9 @@ def v1_cases(n): def main(): ap = argparse.ArgumentParser() ap.add_argument("--n", type=int, default=8) - ap.add_argument("--liberty", default="/home/claude/work/lib/sky130hd_tt_du.lib") + ap.add_argument("--liberty", default=os.environ.get("APPROXKIT_LIBERTY", ""), + help="sky130 (or other) liberty file for the mapped-area column; " + "defaults to $APPROXKIT_LIBERTY, column left empty if unset") ap.add_argument("--out", default="results") ap.add_argument("--which", default="v2,v1") ap.add_argument("--groups", default="", help="v2 only: comma list of groups (smul,div,recip,sq); default all") @@ -95,7 +97,7 @@ def main(): ap.add_argument("--jobs", type=int, default=2) ap.add_argument("--xilinx", action="store_true", help="also run synth_xilinx (slow: ~9 s/design); v2 designs only") a = ap.parse_args() - lib = a.liberty if os.path.exists(a.liberty) else None + lib = a.liberty if a.liberty and os.path.exists(a.liberty) else None if lib is None: print("WARNING: liberty not found; sky130 column left empty") os.makedirs(a.out, exist_ok=True)