Skip to content

Commit 6ca2ff3

Browse files
jharlow-inteljharlow-intel
authored
task: agent-ready prep
2 parents e06bd74 + a045672 commit 6ca2ff3

11 files changed

Lines changed: 315 additions & 2 deletions

File tree

‎.gitattributes‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Keep shell scripts LF on checkout so shellcheck and conda build scripts work
2+
# the same on Windows and WSL checkouts with core.autocrlf enabled.
3+
*.sh text eol=lf

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Bug report
2+
description: Report incorrect results, a crash, or a build failure
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
For security vulnerabilities, do not open an issue — follow
9+
[SECURITY.md](https://github.com/IntelPython/mkl_fft/blob/master/SECURITY.md).
10+
11+
- type: textarea
12+
id: description
13+
attributes:
14+
label: Description
15+
description: What happened, and what did you expect instead?
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: reproducer
21+
attributes:
22+
label: Reproducer
23+
description: A minimal, self-contained snippet. Include the input shape and dtype.
24+
render: python
25+
validations:
26+
required: true
27+
28+
- type: dropdown
29+
id: install-source
30+
attributes:
31+
label: How was `mkl_fft` installed?
32+
options:
33+
- Intel channel (software.repos.intel.com)
34+
- conda-forge
35+
- pip / PyPI
36+
- Built from source
37+
validations:
38+
required: true
39+
40+
- type: textarea
41+
id: versions
42+
attributes:
43+
label: Versions
44+
description: |
45+
Output of:
46+
```
47+
python -c "import mkl_fft, numpy; print(mkl_fft.__version__); print(numpy.__version__)"
48+
```
49+
If the optional `mkl-service` package is installed, add the MKL version:
50+
```
51+
python -c "import mkl; print(mkl.get_version_string())"
52+
```
53+
Add your OS and Python version too.
54+
render: shell
55+
validations:
56+
required: true
57+
58+
- type: textarea
59+
id: notes
60+
attributes:
61+
label: Anything else
62+
description: |
63+
Optional. Whether NumPy patching was active (`mkl_fft.is_patched()`), whether
64+
the result differs from `numpy.fft`/`scipy.fft`, or a non-default
65+
`MKL_NUM_THREADS`.
66+
validations:
67+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Security vulnerability
4+
url: https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html
5+
about: Report security vulnerabilities through Intel's process, not a public issue.
6+
- name: Question about usage
7+
url: https://github.com/IntelPython/mkl_fft/blob/master/README.md
8+
about: Check the README and the interfaces documentation first.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Feature request
2+
description: Propose a new transform, interface, or capability
3+
labels: ["enhancement"]
4+
body:
5+
- type: textarea
6+
id: problem
7+
attributes:
8+
label: What problem does this solve?
9+
description: The use case, not the implementation.
10+
validations:
11+
required: true
12+
13+
- type: textarea
14+
id: proposal
15+
attributes:
16+
label: Proposal
17+
description: |
18+
What you would like `mkl_fft` to do. If it mirrors a `numpy.fft` or
19+
`scipy.fft` function, name it — upstream signature and semantics are the
20+
contract for the interface layer.
21+
validations:
22+
required: true
23+
24+
- type: input
25+
id: upstream
26+
attributes:
27+
label: Upstream equivalent
28+
description: Link to the NumPy or SciPy docs for the equivalent API, if there is one.
29+
validations:
30+
required: false
31+
32+
- type: textarea
33+
id: alternatives
34+
attributes:
35+
label: Alternatives considered
36+
description: Optional. Workarounds you are using today.
37+
validations:
38+
required: false

‎.github/pull_request_template.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Description
2+
3+
<!-- What changed and why. Link any related issues. -->
4+
5+
## Verification
6+
7+
<!-- The commands you ran, and the platform and versions you ran them on. -->
8+
9+
- Tests: <!-- e.g. `pytest mkl_fft/tests`, Python 3.12 / NumPy 2.x, Linux -->
10+
- Lint: <!-- `pre-commit run --all-files` -->
11+
12+
## Not verified
13+
14+
<!--
15+
Anything skipped or left to CI, and why. Examples: Windows, the Intel-channel
16+
conda build, the benchmarks. Write "none" if you ran everything relevant.
17+
-->
18+
19+
## Checklist
20+
21+
- [ ] NumPy/SciPy FFT API compatibility preserved, or the break is intentional and called out above.
22+
- [ ] Behavior changes have tests in `mkl_fft/tests/`; bug fixes have a regression test.
23+
- [ ] `CHANGELOG.md` updated under `## [dev]` with a `[gh-NNN]` link, or the change isn't user-visible.
24+
25+
<!-- See CONTRIBUTING.md for the build and test workflow, and AGENTS.md for the module map. -->

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,19 @@ mkl_fft.egg-info/
55
# Byte-compiled / optimized / DLL files
66
__pycache__/
77

8+
# Virtual environments, test caches, local env files
9+
.venv/
10+
venv/
11+
.pytest_cache/
12+
.env
13+
814
mkl_fft/_pydfti.c
915
mkl_fft/_pydfti.cpython*.so
1016
mkl_fft/_pydfti.*-win_amd64.pyd
1117
mkl_fft/src/mklfft.c
1218

1319
# ASV benchmark artifacts
1420
.asv/
21+
22+
# Developer-local coding agent settings
23+
.claude/settings.local.json

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ It provides accelerated FFT transforms while aiming to preserve upstream API beh
1414
- **Tests:** `mkl_fft/tests/`
1515
- **Vendored helpers:** `_vendored/`
1616
- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
17+
- **Benchmarks:** `benchmarks/`
1718

1819
## Build/runtime basics
1920
- Build system: `pyproject.toml` + `meson.build`
@@ -46,3 +47,4 @@ Use nearest local `AGENTS.md` when present:
4647
- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
4748
- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
4849
- `_vendored/AGENTS.md` — vendored tooling boundaries
50+
- `benchmarks/AGENTS.md` — ASV performance suite

‎CONTRIBUTING.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Contributing to `mkl_fft`
2+
3+
This document covers the development workflow: how to get a working build, how
4+
to run the checks, and what to include in a pull request.
5+
6+
For end-user installation and API usage, see [README.md](README.md). For a map
7+
of the source tree, see [`AGENTS.md`](AGENTS.md), which links to the local
8+
`AGENTS.md` files in directories that have their own rules. Security
9+
vulnerabilities go through the process in [SECURITY.md](SECURITY.md).
10+
11+
---
12+
13+
## Development setup
14+
15+
Building requires a C compiler, oneMKL headers and libraries (`mkl-devel`), and
16+
NumPy. A conda environment is the least surprising way to get them:
17+
18+
```sh
19+
# add python=X.Y to target a specific interpreter
20+
conda create -n mkl_fft-dev -c conda-forge python pip mkl-devel numpy \
21+
meson-python ninja cmake cython pytest
22+
conda activate mkl_fft-dev
23+
```
24+
25+
Then build in place, which reuses the environment's MKL and NumPy:
26+
27+
```sh
28+
pip install -e . --no-build-isolation --verbose
29+
```
30+
31+
`pyproject.toml` defines the supported Python range, and
32+
`.github/workflows/build_pip.yml` is canonical for the versions CI covers.
33+
34+
SciPy and `mkl-service` are optional. They are needed only for the
35+
`mkl_fft.interfaces.scipy_fft` adapter, and the tests that exercise it are
36+
skipped without them. To use or test the SciPy interface, add both to the
37+
environment:
38+
39+
```sh
40+
conda install -c conda-forge scipy mkl-service
41+
```
42+
43+
The matching pip extras are declared in `pyproject.toml`: `scipy_interface` for
44+
the SciPy adapter, `test` for `pytest` plus both packages, and `benchmark` for
45+
the ASV suite.
46+
47+
`README.md` documents the non-editable install paths, including the isolated
48+
build that resolves its own `mkl` and `numpy`.
49+
50+
### Rebuilding
51+
52+
`meson-python` rebuilds the extension on import for editable installs, so
53+
editing `.pyx`, `.c.src`, or `meson.build` and rerunning `pytest` is usually
54+
enough. Generated sources and the compiled extension live under `build/<tag>/`
55+
rather than in the source tree. If a build gets into a bad state, `rm -rf build`
56+
and reinstall.
57+
58+
## Running the checks
59+
60+
```sh
61+
pytest mkl_fft/tests # test suite
62+
pre-commit run --all-files # lint and format hooks
63+
```
64+
65+
Install the hooks once with `pre-commit install` and they run on each commit.
66+
`.pre-commit-config.yaml` is the source of truth for the tooling.
67+
68+
Opening a pull request also runs CI, which builds and tests the package across
69+
platforms and Python versions and runs various lint and static-analysis checks.
70+
71+
## Code style
72+
73+
Style is loose, and the pre-commit hooks enforce most of it:
74+
75+
- Python is formatted with `black` and `isort`, with a line length of 80.
76+
- Cython is not touched by `black`. `isort` sorts its imports, `cython-lint`
77+
checks it against the same 80-column limit, and string literals use double
78+
quotes.
79+
- C sources follow the repository's `.clang-format`.
80+
- Otherwise, match the surrounding code.
81+
82+
## Dos and don'ts
83+
84+
**Do**
85+
86+
- Keep changes atomic and single-purpose.
87+
- Preserve NumPy/SciPy FFT compatibility. This package is used as a drop-in
88+
replacement, so a behavioral difference is a bug even when the new behavior is
89+
arguably better. Call out an intentional break in the PR.
90+
- Add tests in `mkl_fft/tests/` alongside behavior changes, and a regression
91+
test with every bug fix.
92+
- Keep tests deterministic.
93+
- Edit the `*.c.src` templates in `mkl_fft/src/` for C backend changes. The
94+
`.c` files are generated from them on every build.
95+
- Keep patching reversible and observable: anything installed can be
96+
uninstalled, and `is_patched()` reports the truth.
97+
- Cite the source-of-truth file for mutable details: `pyproject.toml`,
98+
`meson.build`, `conda-recipe*/meta.yaml`, `.github/workflows/`.
99+
- Give benchmark numbers reproducible context — hardware, versions, and the
100+
command you ran.
101+
102+
**Don't**
103+
104+
- Commit generated artifacts, or hand-edit a generated `.c`.
105+
- Hardcode versions, build flags, CI matrices, or channel URLs in documentation.
106+
- Assert on timing or throughput in the test suite.
107+
- Refactor `_vendored/` opportunistically. Keep local diffs minimal and send
108+
fixes upstream where you can.
109+
- Introduce ISA-specific assumptions outside explicit build configuration.
110+
111+
## Submitting a change
112+
113+
Work on a branch: the `no-commit-to-branch` hook blocks direct commits to
114+
`master` and `maintenance/*`.
115+
116+
If the change is user-visible — behavior, API, packaging, or build output — add
117+
a `CHANGELOG.md` entry under `## [dev]` in the matching section, with a
118+
`[gh-NNN](https://github.com/IntelPython/mkl_fft/pull/NNN)` link. The format
119+
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
120+
follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Docs,
121+
tooling, and CI-only changes are usually left out.
122+
123+
Then open the PR and fill in the template, including what you verified locally
124+
and what you left to CI.
125+
126+
By contributing you agree that your contributions are licensed under the
127+
BSD-3-Clause terms in [LICENSE.txt](LICENSE.txt).

‎README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,3 +165,10 @@ Optionally, install `scipy` to use the `mkl_fft.interfaces.scipy_fft` module:
165165
```sh
166166
pip install scipy
167167
```
168+
169+
---
170+
# Contributing
171+
172+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow: setting up a
173+
build environment, running the tests and lint hooks, code style, and what to
174+
include in a pull request.

‎benchmarks/AGENTS.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# AGENTS.md — benchmarks/
2+
3+
ASV performance suite for `mkl_fft`.
4+
5+
## Scope
6+
- `asv.conf.json` — ASV configuration, channels, and regression thresholds
7+
- `benchmarks/` — benchmark modules (`bench_fft1d`, `bench_fftnd`,
8+
`bench_interfaces`, `bench_memory`) plus shared bases in `_utils.py`
9+
- `README.md` — coverage table, threading model, and run commands
10+
11+
## Guardrails
12+
- Treat `asv.conf.json` as canonical for ASV settings; treat `README.md` as
13+
canonical for what each module covers.
14+
- Comparability across machines depends on the thread default in
15+
`benchmarks/__init__.py` and the DFTI warmup call in each `time_*` class's
16+
`setup`. The `peakmem_*` classes in `bench_memory.py` inherit the base
17+
`setup` from `_utils.py`, which only builds the input, so their first call
18+
creates the descriptor. Changing the thread default or either setup behavior
19+
invalidates comparison against existing results — call it out explicitly.
20+
- Keep inputs deterministic; benchmarks seed their own RNG.
21+
- Report performance numbers with reproducible context: hardware, thread count,
22+
versions, and the command used.
23+
- Benchmark results under `.asv/` are local artifacts and are gitignored.

0 commit comments

Comments
 (0)