diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..48d9377 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,45 @@ +# GitHub Copilot Instructions — mkl_umath + +## Identity +You are an expert Python/C/Cython developer working on `mkl_umath` at Intel. +Prioritize correctness, numerical integrity, and minimal diffs. + +## Source of truth +This file is canonical for Copilot/agent behavior. +`AGENTS.md` files provide project context. + +## Precedence +copilot-instructions > nearest AGENTS > root AGENTS +Higher-precedence rules override lower-precedence context. + +## Mandatory flow +1. Read root `AGENTS.md`. If absent, stop and report. +2. For each edited file, locate and follow the nearest `AGENTS.md`. +3. If no local file exists, inherit from root `AGENTS.md`. + +## Contribution expectations +- Keep changes atomic and single-purpose. +- Preserve runtime patching API (`use_in_numpy()`, `restore()`, `is_patched()`) unless explicitly requested. +- For behavior changes, update tests in `mkl_umath/tests/` in the same step. +- For bugs, include a regression test. +- Do not modify generated artifacts directly when template/source files are the intended edit points. + +## Authoring rules +- Never invent versions, compilers, or CI matrix values. +- Use source-of-truth files for dependencies and build config. +- Respect precision/correctness guardrails (`fp:precise`, `fimf-precision=high`, related flags). +- Avoid hardcoded ISA assumptions unless explicitly present in existing build configuration. +- Never include secrets or credentials in code/docs. + +## Source-of-truth files +- Build: `CMakeLists.txt`, `pyproject.toml`, `setup.py` +- Dependencies/packaging: `conda-recipe*/meta.yaml` +- CI: `.github/workflows/*.{yml,yaml}` +- API: `mkl_umath/__init__.py`, `mkl_umath/src/_patch.pyx` +- Core implementation: `mkl_umath/src/*.c`, `*.c.src`, `*.pyx` +- Tests: `mkl_umath/tests/` + +## Intel-specific constraints +- oneMKL is required; `icx` and `clang` toolchains are both valid when compiler-specific flags are gated correctly. +- Patching behavior must remain compatible with NumPy integration semantics. +- Performance optimizations must not compromise numerical correctness. diff --git a/AGENTS.md b/AGENTS.md index 82263f6..5732b13 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ It provides: ## Build dependencies **Required:** -- Intel® C Compiler (icx) +- Compiler toolchain: Intel `icx` or `clang` (with Intel-only flags gated when using clang) - Intel® OneMKL (mkl-devel) - Intel® TBB (tbb-devel) - NumPy, Cython, scikit-build, cmake, ninja @@ -30,7 +30,7 @@ conda install -c https://software.repos.intel.com/python/conda \ mkl-devel tbb-devel dpcpp_linux-64 numpy-base \ cmake ninja cython scikit-build export MKLROOT=$CONDA_PREFIX -CC=icx pip install --no-build-isolation --no-deps . +CC=${CC:-icx} pip install --no-build-isolation --no-deps . # clang is also supported in CI ``` ## CI/CD @@ -72,9 +72,9 @@ mkl_umath.restore() # Restore original NumPy loops - **NumPy source:** Requires Intel-optimized NumPy from Intel channel (`software.repos.intel.com/python/conda`). PyPI NumPy may cause runtime failures or incorrect results. - **Precision flags:** `fp:precise`, `fimf-precision=high` enforce IEEE 754 compliance. Removing them breaks numerical correctness in scientific computing. - **Patching order:** If using multiple Intel patches (e.g., `mkl_random` + `mkl_umath`), apply `mkl_umath` last. Verify with `is_patched()` after each. -- **Compiler:** Intel `icx` is the supported compiler. `build-with-clang.yml` validates compatibility, but icx is recommended for production. +- **Compiler/toolchain:** `icx` and `clang` are both supported; when using clang, keep Intel-only flags behind compiler guards. - **Build validation:** - - After setup: `which icx` → should point to conda env or oneAPI location + - After setup: `which ${CC:-icx}` → should resolve to the intended compiler toolchain - Verify: `echo $MKLROOT` → should be set - Check: `python -c "import numpy; print(numpy.__version__)"` → confirm Intel NumPy