Skip to content

Commit f5e7139

Browse files
napetrovnapetrov
committed
Add AGENTS.md documentation structure
- Root AGENTS.md with ecosystem context and directory map - .github/AGENTS.md: CI/CD workflows, security scanning - mkl_umath/AGENTS.md: Python API, code generation, patching - mkl_umath/src/AGENTS.md: C/Cython implementation, MKL VM - mkl_umath/tests/AGENTS.md: unit tests and validation - conda-recipe/AGENTS.md: Intel channel packaging - conda-recipe-cf/AGENTS.md: conda-forge recipe - _vendored/AGENTS.md: vendored NumPy utilities Follows dpnp AGENTS.md pattern for IntelPython ecosystem consistency.
1 parent b4f4bf1 commit f5e7139

8 files changed

Lines changed: 290 additions & 0 deletions

File tree

‎.github/AGENTS.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# AGENTS.md — .github/
2+
3+
CI/CD workflows, automation, security scanning, and package distribution.
4+
5+
## Workflows
6+
- **conda-package.yml** — main build/test pipeline (Linux/Windows, Python 3.10-3.13)
7+
- **build_pip.yaml** — PyPI wheel builds for Intel channel
8+
- **build-with-clang.yml** — Clang compatibility validation
9+
- **openssf-scorecard.yml** — security posture scanning
10+
11+
## CI/CD policy
12+
- Keep build matrix (Python versions, platforms) in workflow files only
13+
- Required checks: conda build + test on all supported Python versions
14+
- Artifact naming: `$PACKAGE_NAME $OS Python $VERSION`
15+
- Conda channel: `https://software.repos.intel.com/python/conda`
16+
17+
## Security
18+
- OpenSSF Scorecard runs automatically
19+
- CODEOWNERS enforces review policy
20+
- Dependabot monitors dependencies (`.github/dependabot.yml`)
21+
22+
## Notes
23+
- Workflow/job renames are breaking for downstream tooling
24+
- Cache key includes `meta.yaml` hash for conda packages
25+
- Artifacts uploaded per-Python-version for parallel testing

‎AGENTS.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# AGENTS.md
2+
3+
Entry point for agent context in this repo.
4+
5+
## What this repository is
6+
`mkl_umath` exposes Intel® OneMKL-powered universal function loops for NumPy, originally part of Intel® Distribution for Python* and factored out per NEP-36 (Fair Play).
7+
8+
It provides:
9+
- `mkl_umath._ufuncs` — OneMKL-backed NumPy ufunc loops
10+
- `mkl_umath._patch` — runtime patching interface (`use_in_numpy()`, `restore()`, `is_patched()`)
11+
- Performance-optimized math operations (sin, cos, exp, log, etc.) using Intel MKL VM
12+
13+
## Key components
14+
- **Python interface:** `mkl_umath/__init__.py`, `_init_helper.py`
15+
- **Core C implementation:** `mkl_umath/src/` (ufuncsmodule.c, mkl_umath_loops.c.src)
16+
- **Cython patch layer:** `mkl_umath/src/_patch.pyx`
17+
- **Code generation:** `generate_umath.py`, `generate_umath_doc.py`
18+
- **Build system:** CMake (CMakeLists.txt) + scikit-build
19+
20+
## Build dependencies
21+
**Required:**
22+
- Intel® C Compiler (icx)
23+
- Intel® OneMKL (mkl-devel)
24+
- Intel® TBB (tbb-devel)
25+
- NumPy, Cython, scikit-build, cmake, ninja
26+
27+
**Conda environment:**
28+
```bash
29+
conda install -c https://software.repos.intel.com/python/conda \
30+
mkl-devel tbb-devel dpcpp_linux-64 numpy-base \
31+
cmake ninja cython scikit-build
32+
export MKLROOT=$CONDA_PREFIX
33+
CC=icx pip install --no-build-isolation --no-deps .
34+
```
35+
36+
## CI/CD
37+
- **Platforms:** Linux, Windows
38+
- **Python versions:** 3.10, 3.11, 3.12, 3.13
39+
- **Workflows:** `.github/workflows/`
40+
- `conda-package.yml` — main build/test pipeline
41+
- `build_pip.yaml` — PyPI wheel builds
42+
- `build-with-clang.yml` — Clang compatibility check
43+
- `openssf-scorecard.yml` — security scorecard
44+
45+
## Distribution
46+
- **Conda:** `https://software.repos.intel.com/python/conda`
47+
- **PyPI:** `https://software.repos.intel.com/python/pypi`
48+
- Requires Intel-optimized NumPy from Intel channels
49+
50+
## Usage
51+
```python
52+
import mkl_umath
53+
mkl_umath.use_in_numpy() # Patch NumPy to use MKL loops
54+
# ... perform NumPy operations (now accelerated) ...
55+
mkl_umath.restore() # Restore original NumPy loops
56+
```
57+
58+
## How to work in this repo
59+
- **Performance:** Changes should maintain or improve MKL VM utilization
60+
- **Compatibility:** Must work with upstream NumPy APIs (NEP-36 compliance)
61+
- **Testing:** Add tests to `mkl_umath/tests/test_basic.py`
62+
- **Build hygiene:** CMake changes → verify Linux + Windows
63+
- **Docs:** Update docstrings via `ufunc_docstrings_numpy{1,2}.py`
64+
65+
## Code structure
66+
- **Generated code:** `*.src` files are templates (conv_template.py processes them)
67+
- **Precision flags:** fp:precise, fimf-precision=high, fprotect-parens (non-negotiable)
68+
- **Security:** Stack protection, FORTIFY_SOURCE, NX/DEP enforced in CMake
69+
70+
## Notes
71+
- `_vendored/` contains vendored NumPy code generation utilities
72+
- Version in `mkl_umath/_version.py` (dynamic via setuptools)
73+
- Patching is runtime-only; no NumPy source modification
74+
75+
## Directory map
76+
Below directories have local `AGENTS.md` for deeper context:
77+
- `.github/AGENTS.md` — CI/CD workflows and automation
78+
- `mkl_umath/AGENTS.md` — Python API and code generation
79+
- `mkl_umath/src/AGENTS.md` — C/Cython implementation layer
80+
- `mkl_umath/tests/AGENTS.md` — unit tests and validation
81+
- `conda-recipe/AGENTS.md` — Intel channel conda packaging
82+
- `conda-recipe-cf/AGENTS.md` — conda-forge compatible recipe
83+
- `_vendored/AGENTS.md` — vendored NumPy utilities
84+
85+
---
86+
87+
For broader IntelPython ecosystem context, see:
88+
- `dpnp` (Data Parallel NumPy)
89+
- `mkl_random` (MKL-based random number generation)
90+
- `numba-dpex` (Numba + SYCL)

‎_vendored/AGENTS.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# AGENTS.md — _vendored/
2+
3+
Vendored dependencies from upstream projects (NumPy).
4+
5+
## Files
6+
- **conv_template.py** — NumPy's template processor (from `numpy.distutils`)
7+
- **__init__.py** — Python package marker
8+
9+
## Why vendored?
10+
- `numpy.distutils` removed in NumPy 2.0+ / Python 3.12+
11+
- Needed for `.src` template processing at build time
12+
- Vendored to maintain build compatibility across NumPy versions
13+
14+
## Maintenance
15+
- Source: NumPy's `numpy/distutils/conv_template.py`
16+
- Update if template syntax changes upstream (rare)
17+
- Do not modify vendored code (keep attribution intact)
18+
19+
## Usage
20+
- Imported by `generate_umath.py` for `.src` → `.c` conversion
21+
- Processes `/**begin repeat ... end repeat**/` blocks

‎conda-recipe-cf/AGENTS.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# AGENTS.md — conda-recipe-cf/
2+
3+
Conda-forge compatible build recipe (alternative to Intel channel recipe).
4+
5+
## Difference from conda-recipe/
6+
- No `conda_build_config.yaml` (uses conda-forge defaults)
7+
- May use different compiler toolchain
8+
- For conda-forge feedstock integration (if upstreamed)
9+
10+
## Files
11+
- **meta.yaml** — conda-forge compatible metadata
12+
- **build.sh** / **bld.bat** — platform build scripts
13+
- **run_tests.{sh,bat}** — test invocation
14+
15+
## Status
16+
- Not currently used in main CI workflows
17+
- Maintained for potential conda-forge submission
18+
- Use `conda-recipe/` for Intel channel builds
19+
20+
## Notes
21+
- If upstreaming to conda-forge, this recipe should be preferred
22+
- Compiler requirements may differ (Clang/GCC vs Intel icx)

‎conda-recipe/AGENTS.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# AGENTS.md — conda-recipe/
2+
3+
Conda package build recipe for Intel channel distribution.
4+
5+
## Files
6+
- **meta.yaml** — package metadata, dependencies, build requirements
7+
- **build.sh** — Linux build script
8+
- **bld.bat** — Windows build script
9+
- **conda_build_config.yaml** — build matrix (Python versions, numpy pins)
10+
- **run_tests.{sh,bat}** — post-build test invocation
11+
12+
## Build configuration
13+
- **Channels:** `https://software.repos.intel.com/python/conda`, `conda-forge`
14+
- **Python versions:** 3.10, 3.11, 3.12, 3.13
15+
- **Compilers:** Intel C compiler (icx/icl)
16+
- **Dependencies:** mkl-devel, tbb-devel, dpcpp_{linux,win}-64, numpy-base
17+
18+
## Build outputs
19+
- Conda package: `mkl_umath-<version>-<build>.conda`
20+
- Platform-specific: `linux-64/`, `win-64/`
21+
22+
## CI usage
23+
- Built in `.github/workflows/conda-package.yml`
24+
- Artifacts uploaded per Python version
25+
- Test stage uses built artifacts from channel
26+
27+
## Maintenance
28+
- Keep `conda_build_config.yaml` in sync with CI matrix
29+
- NumPy pin: must match Intel channel NumPy versions
30+
- MKL/TBB versions: track oneAPI releases

‎mkl_umath/AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# AGENTS.md — mkl_umath/
2+
3+
Core MKL-backed ufunc implementation: Python interface, Cython patching, and C/MKL integration.
4+
5+
## Structure
6+
- `__init__.py` — public API surface (`_ufuncs`, `_patch`, version)
7+
- `_init_helper.py` — module initialization helpers
8+
- `_version.py` — version string (dynamic via setuptools)
9+
- `src/` — C implementation and Cython patch layer
10+
- `tests/` — basic functionality and patching tests
11+
- `generate_umath.py` — code generation for ufunc loops
12+
- `generate_umath_doc.py` — docstring generation
13+
- `ufunc_docstrings_numpy{1,2}.py` — NumPy version-specific docstrings
14+
15+
## Patching API
16+
```python
17+
mkl_umath.use_in_numpy() # Replace NumPy loops with MKL
18+
mkl_umath.restore() # Restore original NumPy loops
19+
mkl_umath.is_patched() # Check patch status
20+
```
21+
22+
## Development guardrails
23+
- **API stability:** Patching must be runtime-only, no NumPy source modification
24+
- **Precision:** fp:precise, fimf-precision=high, fprotect-parens are non-negotiable
25+
- **Compatibility:** Must work with upstream NumPy (NEP-36 compliance)
26+
- **Testing:** Add tests to `tests/test_basic.py` for new ufuncs or patch behavior
27+
28+
## Code generation
29+
- `*.src` files are templates processed by `_vendored/conv_template.py`
30+
- Generated files: `src/__umath_generated.c`, loop implementations
31+
- Docstrings: dual NumPy 1.x/2.x support via separate docstring modules
32+
33+
## Notes
34+
- `_patch.pyx` is Cython; changes require Cython rebuild
35+
- MKL VM loops in `src/mkl_umath_loops.c.src`
36+
- `src/ufuncsmodule.c` — NumPy ufunc registration and dispatch

‎mkl_umath/src/AGENTS.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# AGENTS.md — mkl_umath/src/
2+
3+
C/Cython implementation layer: MKL VM integration, ufunc loops, and NumPy patching.
4+
5+
## Core files
6+
- **ufuncsmodule.c** — NumPy ufunc registration and module init
7+
- **ufuncsmodule.h** — ufunc module public headers
8+
- **mkl_umath_loops.c.src** — MKL VM loop implementations (template, ~60k LOC)
9+
- **mkl_umath_loops.h.src** — loop function declarations (template)
10+
- **_patch.pyx** — Cython patching layer (runtime NumPy loop replacement)
11+
- **fast_loop_macros.h** — loop generation macros
12+
- **blocking_utils.h** — blocking/chunking utilities for large arrays
13+
14+
## Template system
15+
- `.src` files are processed by `_vendored/conv_template.py` at build time
16+
- Generates type-specialized loops for float32, float64, complex64, complex128
17+
- Pattern: `/**begin repeat ... end repeat**/` blocks
18+
19+
## MKL VM integration
20+
- Calls `vdSin`, `vsExp`, etc. from Intel MKL Vector Math (VM)
21+
- Blocking strategy: chunk large arrays for cache efficiency
22+
- Error handling: MKL VM status → NumPy error state
23+
24+
## Patching mechanism (_patch.pyx)
25+
- Cython extension exposing `use_in_numpy()`, `restore()`, `is_patched()`
26+
- Replaces function pointers in NumPy's ufunc loop tables
27+
- Thread-safe: guards against concurrent patching
28+
- Reversible: stores original pointers for restoration
29+
30+
## Build output
31+
- `mkl_umath_loops.c` → shared library (libmkl_umath_loops.so/.dll)
32+
- `_patch.pyx` → Python extension (_patch.*.so)
33+
- `ufuncsmodule.c` + `__umath_generated.c` → `_ufuncs` extension
34+
35+
## Development notes
36+
- **Precision flags:** fp:precise, fimf-precision=high enforced in CMake
37+
- **Security:** Stack protections, FORTIFY_SOURCE enabled
38+
- **Vectorization:** `-fveclib=SVML -fvectorize` for SIMD
39+
- **Optimization reports:** `cmake -DOPTIMIZATION_REPORT=ON` for `-qopt-report=3`

‎mkl_umath/tests/AGENTS.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# AGENTS.md — mkl_umath/tests/
2+
3+
Unit tests for MKL-backed ufuncs and NumPy patching.
4+
5+
## Test files
6+
- **test_basic.py** — core functionality, patching API, numerical correctness
7+
8+
## Test coverage
9+
- Ufunc correctness: compare MKL loops vs NumPy reference
10+
- Patching: `use_in_numpy()`, `restore()`, `is_patched()` state transitions
11+
- Edge cases: NaN, Inf, empty arrays, large arrays
12+
- Dtype coverage: float32, float64, complex64, complex128
13+
14+
## Running tests
15+
```bash
16+
pytest mkl_umath/tests/
17+
```
18+
19+
## CI integration
20+
- Tests run in conda-package.yml workflow
21+
- Separate test jobs per Python version (3.10-3.13)
22+
- Linux + Windows platforms
23+
24+
## Adding tests
25+
- New ufuncs → add to `test_basic.py` with NumPy reference comparison
26+
- Patching behavior → test state transitions and thread safety
27+
- Use `numpy.testing.assert_allclose` for floating-point comparisons

0 commit comments

Comments
 (0)