From f3f0b23b99f2e35638182240083f94567b2fd9af Mon Sep 17 00:00:00 2001
From: Kavin K K <219786728+Kavin-Re@users.noreply.github.com>
Date: Thu, 19 Nov 2026 13:16:08 +0000
Subject: [PATCH 1/2] Repository overhaul: docs, tests, CI, fixes
---
.editorconfig | 24 ++
.github/ISSUE_TEMPLATE/bug_report.yml | 62 ++++
.github/ISSUE_TEMPLATE/config.yml | 1 +
.github/ISSUE_TEMPLATE/feature_request.yml | 33 ++
.github/dependabot.yml | 10 +
.github/pull_request_template.md | 15 +
.github/workflows/ci.yml | 75 +++++
.gitignore | 22 +-
CITATION.cff | 9 +
CODE_OF_CONDUCT.md | 32 ++
CONTRIBUTING.md | 31 ++
README.md | 334 +++++++++++++--------
approxkit/adders.py | 10 +-
approxkit/base.py | 14 +-
approxkit/dse.py | 9 +-
approxkit/metrics.py | 5 +-
approxkit/multipliers.py | 19 +-
pyproject.toml | 36 ++-
scripts/compare_csv.py | 52 ++++
tests/test_units.py | 65 ++++
v2/README.md | 39 +++
v2/RESULTS_V2.md | 10 +-
v2/scripts/synth_costs.py | 6 +-
23 files changed, 759 insertions(+), 154 deletions(-)
create mode 100644 .editorconfig
create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
create mode 100644 .github/ISSUE_TEMPLATE/config.yml
create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
create mode 100644 .github/dependabot.yml
create mode 100644 .github/pull_request_template.md
create mode 100644 .github/workflows/ci.yml
create mode 100644 CITATION.cff
create mode 100644 CODE_OF_CONDUCT.md
create mode 100644 CONTRIBUTING.md
create mode 100755 scripts/compare_csv.py
create mode 100644 v2/README.md
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..f41a177
--- /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.9", "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
+[](https://github.com/Kavin-Re/ApproxKit/actions/workflows/ci.yml)
+[](LICENSE)
+
+
+
+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)
From 2f1c1123de5c435eee8ff1edd122c084ddbd0b2e Mon Sep 17 00:00:00 2001
From: Kavin K K <219786728+Kavin-Re@users.noreply.github.com>
Date: Thu, 19 Nov 2026 13:41:20 +0000
Subject: [PATCH 2/2] CI: test on Python 3.10 (3.9 is not available on
ubuntu-latest)
---
.github/workflows/ci.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f41a177..05057c1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,7 +15,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- python-version: ["3.9", "3.11", "3.13"]
+ python-version: ["3.10", "3.11", "3.13"]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5