build: tune Python install for the host CPU by default

Compile the native library with -march=native (or -mcpu=native on
Apple-silicon clang) and -ffast-math when the compiler accepts them, probing
each flag first so the build degrades gracefully. Opt out with BFFT_NO_NATIVE=1
or BFFT_NO_FAST_MATH=1. Since no prebuilt binaries are distributed and the
library is always compiled on the install machine, host-native codegen is the
right default and lets the SIMD kernels actually use AVX2/AVX-512.

Also document the flags and caveats in README.md and documentation/python.md,
and switch pyproject license to an SPDX string.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: falseywinchnet

README.md

@@ -211,10 +211,16 @@ From a clone of the repository:
 pip install .
 ```
 
-This compiles `src/bfft.cpp` and `src/bodft.cpp` with your C++ compiler (override
-with the `CXX` environment variable) and bundles the resulting shared library
-inside the installed package. A C++17 compiler and NumPy are the only
-requirements.
+This compiles `src/bfft.cpp` and `src/bodft.cpp` with your C++ compiler and
+bundles the resulting shared library inside the installed package. A C++17
+compiler and NumPy are the only requirements.
+
+Because the build runs on your own machine, it tunes for the local CPU by
+default, selecting `-O3`, `-march=native` (or `-mcpu=native` on Apple silicon),
+and `-ffast-math` when the compiler accepts them. Override with environment
+variables: `CXX` (compiler), `BFFT_CXXFLAGS` (extra flags), `BFFT_NO_NATIVE=1`
+(portable codegen), and `BFFT_NO_FAST_MATH=1` (strict IEEE math). See
+[`documentation/python.md`](documentation/python.md) for details and caveats.
 
 Alternatively, build and install the native library system-wide first, then the
 Python loader will find it automatically:

documentation/python.md

@@ -16,13 +16,39 @@ This compiles `src/bfft.cpp` and `src/bodft.cpp` with your C++ compiler and
 bundles the resulting shared library inside the installed package. The only
 requirements are a C++17 compiler and NumPy.
 
-Override the compiler with the `CXX` environment variable, and pass extra flags
-with `BFFT_CXXFLAGS` if needed:
+### Optimization flags
+
+Because the library is compiled on your own machine (no prebuilt binaries are
+distributed), the build tunes for the local CPU by default. It selects, when the
+compiler accepts them:
+
+- `-O3`
+- `-march=native` (or `-mcpu=native` on Apple-silicon clang) — emit AVX2/AVX-512
+  and other host-specific instructions.
+- `-ffast-math` — relaxed floating-point for faster math.
+
+Each flag is probed against your compiler first, so the build degrades
+gracefully on toolchains that lack them. Control the defaults with environment
+variables:
+
+| Variable | Effect |
+| --- | --- |
+| `BFFT_NO_NATIVE=1` | Skip `-march=native` / `-mcpu=native` (portable codegen). |
+| `BFFT_NO_FAST_MATH=1` | Keep strict IEEE math (drop `-ffast-math`). |
+| `CXX=...` | Choose the compiler. |
+| `BFFT_CXXFLAGS="..."` | Append extra flags to the compile. |
 
 ```sh
-CXX=clang++ BFFT_CXXFLAGS="-march=native" pip install .
+CXX=clang++ BFFT_NO_FAST_MATH=1 pip install .
 ```
 
+`-ffast-math` assumes no NaNs/infinities and reorders operations, so results may
+differ in the last bits from a strict-IEEE build (still accurate to
+floating-point precision for these transforms). It also enables
+flush-to-zero/denormals-are-zero for the process when the library loads, which
+can affect denormal handling elsewhere. Set `BFFT_NO_FAST_MATH=1` if you need
+bit-reproducible or strict denormal behavior.
+
 ### Using a system-installed library
 
 If you prefer to build the native library separately, install it first and the

pyproject.toml

@@ -7,7 +7,8 @@ name = "bfft"
 version = "0.1.0"
 description = "Python bindings for the BFFT real Fourier transform library (drop-in numpy.fft.rfft + half-bin ODFT)."
 readme = "README.md"
-license = { file = "LICENSE" }
+license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.8"
 dependencies = ["numpy>=1.20"]
 

setup.py

@@ -9,7 +9,7 @@
 import os
 import subprocess
 import sys
-import sysconfig
+import tempfile
 from pathlib import Path
 
 from setuptools import setup
@@ -28,10 +28,55 @@ def _shared_lib_suffix() -> str:
     return ".so"
 
 
+def _env_off(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _compiler_accepts(cxx: str, flags: list) -> bool:
+    """Return True if the compiler accepts ``flags`` on a trivial source file."""
+    with tempfile.TemporaryDirectory() as d:
+        src = Path(d) / "probe.cpp"
+        src.write_text("int main() { return 0; }\n")
+        try:
+            subprocess.run(
+                [cxx, *flags, "-c", str(src), "-o", str(Path(d) / "probe.o")],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=True,
+            )
+            return True
+        except (subprocess.CalledProcessError, OSError):
+            return False
+
+
+def _optimization_flags(cxx: str) -> list:
+    """Pick the strongest optimization flags the host compiler accepts.
+
+    Because the library is compiled on the install machine (no prebuilt binaries
+    are distributed), tuning for the local CPU is safe and is the default. Set
+    BFFT_NO_NATIVE=1 to skip CPU-native codegen and BFFT_NO_FAST_MATH=1 to keep
+    strict IEEE math.
+    """
+    flags = ["-O3"]
+
+    if not _env_off("BFFT_NO_NATIVE"):
+        # x86 / older clang / gcc use -march=native; Apple-silicon clang wants
+        # -mcpu=native instead. Probe and take whichever the compiler accepts.
+        if _compiler_accepts(cxx, ["-march=native"]):
+            flags.append("-march=native")
+        elif _compiler_accepts(cxx, ["-mcpu=native"]):
+            flags.append("-mcpu=native")
+
+    if not _env_off("BFFT_NO_FAST_MATH") and _compiler_accepts(cxx, ["-ffast-math"]):
+        flags.append("-ffast-math")
+
+    return flags
+
+
 def _compile_shared_library(out_path: Path) -> None:
     cxx = os.environ.get("CXX", "c++")
     out_path.parent.mkdir(parents=True, exist_ok=True)
-    cmd = [cxx, "-O3", "-std=c++17", "-fPIC", "-shared"]
+    cmd = [cxx, *_optimization_flags(cxx), "-std=c++17", "-fPIC", "-shared"]
     cmd += ["-I", str(ROOT / INCLUDE)]
     cmd += [str(ROOT / s) for s in SOURCES]
     cmd += ["-o", str(out_path)]