Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -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
62 changes: 62 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
blank_issues_enabled: false
33 changes: 33 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -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
10 changes: 10 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
version: 2
updates:
- package-ecosystem: github-actions
directory: /
schedule:
interval: weekly
- package-ecosystem: pip
directory: /
schedule:
interval: weekly
15 changes: 15 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -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".
75 changes: 75 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
22 changes: 20 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -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
9 changes: 9 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -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
32 changes: 32 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -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.
31 changes: 31 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
Loading
Loading