Skip to content

Commit 8e53661

Browse files
ndgrigorianndgrigorian
authored
Merge branch 'master' into add-conda-forge-workflow
2 parents 512f624 + 86a4d4b commit 8e53661

7 files changed

Lines changed: 305 additions & 0 deletions

File tree

‎.github/AGENTS.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
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.14)
7+
- **build-with-clang.yml** — Linux Clang compiler compatibility validation
8+
- **pre-commit.yml** — code quality checks (flake8, etc.)
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 supported Python versions/platforms in CI
14+
- Artifact naming: `$PACKAGE_NAME $OS Python $VERSION`
15+
- Channels: `conda-forge`, `conda-forge/label/python_rc`, Intel channel
16+
17+
## Security
18+
- OpenSSF Scorecard runs automatically
19+
- CODEOWNERS enforces review policy
20+
- Dependabot monitors dependencies (`.github/dependabot.yml`)
21+
22+
## Platform specifics
23+
- **Linux:** RTLD_GLOBAL handling for MKL library loading
24+
- **Windows:** DLL search path configuration for venv/runtime loading
25+
26+
## Notes
27+
- Workflow/job renames are breaking for downstream tooling
28+
- Cache key includes `meta.yaml` hash for conda packages
29+
- Python 3.14 uses `conda-forge/label/python_rc` for pre-release support

‎.github/copilot-instructions.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# GitHub Copilot Instructions — mkl-service
2+
3+
## Identity
4+
You are an expert Python/Cython/C developer working on `mkl-service` at Intel.
5+
Apply Intel engineering standards: correctness first, minimal diffs, no assumptions.
6+
7+
## Source of truth
8+
This file is canonical for Copilot/agent behavior.
9+
`AGENTS.md` files provide project context.
10+
11+
## Precedence
12+
copilot-instructions > nearest AGENTS > root AGENTS
13+
Higher-precedence file overrides; lower must not restate overridden guidance.
14+
15+
## Mandatory flow
16+
1. Read root `AGENTS.md`. If absent, stop and report.
17+
2. For each edited file, locate and follow the nearest `AGENTS.md`.
18+
3. If no local file exists, inherit rules from root `AGENTS.md`.
19+
20+
## Contribution expectations
21+
- Keep diffs minimal; prefer atomic single-purpose commits.
22+
- Preserve public API signatures in `mkl/__init__.py` unless change is explicitly requested.
23+
- For user-visible behavior changes: update tests in `mkl/tests/test_mkl_service.py`.
24+
- For bug fixes: add or extend regression tests in the same change.
25+
- Do not generate code without corresponding test updates when behavior changes.
26+
- Run `pre-commit run --all-files` when `.pre-commit-config.yaml` is present.
27+
28+
## Authoring rules
29+
- Use source-of-truth files for all mutable details.
30+
- Never invent/hardcode versions, CI matrices, channels, or compiler flags.
31+
- Prefer stable local entry points:
32+
- `python -m pip install -e .`
33+
- `pytest -vv --pyargs mkl`
34+
- Never include secrets/tokens/credentials in files.
35+
36+
## Source-of-truth files
37+
- Build/config: `pyproject.toml`, `setup.py`
38+
- Recipe/deps: `conda-recipe/meta.yaml`, `conda-recipe/conda_build_config.yaml`
39+
- CI: `.github/workflows/*.{yml,yaml}`
40+
- API contracts: `mkl/__init__.py`, `mkl/_mkl_service.pyx`
41+
- Tests: `mkl/tests/test_mkl_service.py`
42+
43+
## MKL-specific constraints
44+
- Linux runtime init path may require `RTLD_GLOBAL` preloading (`mkl/_mklinitmodule.c`).
45+
- Windows venv DLL handling is in `mkl/_init_helper.py`.
46+
- Threading/runtime controls affect downstream MKL-backed libraries (NumPy/SciPy/etc.); maintain compatibility.
47+
- For behavior and semantics of support functions, align with Intel oneMKL developer reference docs.

‎AGENTS.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# AGENTS.md
2+
3+
Entry point for agent context in this repo.
4+
5+
## What this repository is
6+
`mkl-service` provides a Python API for runtime control of Intel® oneMKL (Math Kernel Library). It exposes support functions for:
7+
- Threading control (set/get number of threads, domain-specific threading)
8+
- Version information (MKL version, build info)
9+
- Memory management (peak memory usage, memory statistics)
10+
- Conditional Numerical Reproducibility (CNR)
11+
- Timing functions (get CPU/wall clock time)
12+
- Miscellaneous utilities (MKL_VERBOSE control, etc.)
13+
14+
Originally part of Intel® Distribution for Python*, now a standalone package available via conda-forge and Intel channels.
15+
16+
## Key components
17+
- **Python interface:** `mkl/__init__.py` — public API surface
18+
- **Cython wrapper:** `mkl/_mkl_service.pyx` — wraps MKL support functions
19+
- **C init module:** `mkl/_mklinitmodule.c` — Linux-side MKL runtime preloading / initialization
20+
- **Helper:** `mkl/_init_helper.py` — Windows venv DLL loading helper
21+
- **Build system:** setuptools + Cython
22+
23+
## Build dependencies
24+
**Required:**
25+
- Intel® oneMKL
26+
- Cython
27+
- Python 3.10+
28+
29+
**Conda environment:**
30+
```bash
31+
conda install -c conda-forge mkl-devel cython
32+
python setup.py install
33+
```
34+
35+
## CI/CD
36+
- **Platforms in CI workflows:** Linux, Windows
37+
- **Python versions:** 3.10, 3.11, 3.12, 3.13, 3.14
38+
- **Workflows:** `.github/workflows/`
39+
- `conda-package.yml` — main conda build/test pipeline
40+
- `build-with-clang.yml` — Linux Clang compatibility
41+
- `pre-commit.yml` — code quality checks
42+
- `openssf-scorecard.yml` — security scanning
43+
44+
## Distribution
45+
- **Conda:** `conda-forge` and `https://software.repos.intel.com/python/conda`
46+
- **PyPI:** `python -m pip install mkl-service`
47+
48+
## Usage
49+
```python
50+
import mkl
51+
mkl.set_num_threads(4) # Set global thread count
52+
mkl.domain_set_num_threads(1, "fft") # FFT functions run sequentially
53+
mkl.get_version_string() # MKL version info
54+
```
55+
56+
## How to work in this repo
57+
- **API stability:** Preserve existing function signatures (widely used in ecosystem)
58+
- **Threading:** Changes to threading control must be thread-safe
59+
- **CNR:** Conditional Numerical Reproducibility flags require careful documentation
60+
- **Testing:** Add tests to `mkl/tests/test_mkl_service.py`
61+
- **Docs:** MKL support functions documented in [Intel oneMKL Developer Reference](https://www.intel.com/content/www/us/en/docs/onemkl/developer-reference-c/2025-2/support-functions.html)
62+
63+
## Code structure
64+
- **Cython layer:** `_mkl_service.pyx` + `_mkl_service.pxd` (C declarations)
65+
- **C init:** `_mklinitmodule.c` handles Linux preloading (`dlopen(..., RTLD_GLOBAL)`) for MKL runtime
66+
- **Windows loading helper:** `_init_helper.py` handles DLL path setup in Windows venv
67+
- **Python wrapper:** `__init__.py` imports `_py_mkl_service` (generated from `.pyx`)
68+
- **Version:** `_version.py` (dynamic via setuptools)
69+
70+
## Notes
71+
- RTLD_GLOBAL preloading is required on Linux (handled by `RTLD_for_MKL` context manager)
72+
- MKL must be available at runtime (conda: mkl, pip: relies on system MKL)
73+
- Threading functions affect NumPy, SciPy, and other MKL-backed libraries
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/AGENTS.md` — Python/Cython implementation
79+
- `mkl/tests/AGENTS.md` — unit tests
80+
- `conda-recipe/AGENTS.md` — conda packaging
81+
- `examples/AGENTS.md` — usage examples
82+
83+
---
84+
85+
For broader IntelPython ecosystem context, see:
86+
- `mkl_umath` (MKL-backed NumPy ufuncs)
87+
- `mkl_random` (MKL-based random number generation)
88+
- `dpnp` (Data Parallel NumPy)

‎conda-recipe/AGENTS.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# AGENTS.md — conda-recipe/
2+
3+
Conda package build recipe for conda-forge and Intel channel distribution.
4+
5+
## Files
6+
- **meta.yaml** — package metadata, dependencies, build requirements
7+
- **build.sh** — Linux/macOS build script
8+
- **bld.bat** — Windows build script
9+
- **conda_build_config.yaml** — compiler / stdlib pinning used by conda-build variants
10+
11+
## Build configuration
12+
- **Channels:** `conda-forge`, `conda-forge/label/python_rc`, Intel channel
13+
- **Python versions in CI build matrix:** 3.10, 3.11, 3.12, 3.13, 3.14
14+
- **Compilers:** pinned via `conda_build_config.yaml` (GCC/GXX on Linux, VS2022 on Windows)
15+
- **Dependencies:** `mkl` (runtime), `mkl-devel` (build), `cython`
16+
17+
## Build outputs
18+
- Conda package: `mkl-service-<version>-<build>.conda`
19+
- Platform-specific artifacts from CI currently: `linux-64/`, `win-64/`
20+
21+
## CI usage
22+
- Built in `.github/workflows/conda-package.yml`
23+
- Artifacts uploaded per Python version and platform
24+
- Test stage uses built artifacts from a temporary local channel
25+
26+
## Platform specifics
27+
- **Linux:** RTLD_GLOBAL handling in runtime init path
28+
- **Windows:** MKL library path configuration
29+
- **macOS:** recipe scripts exist, but current GitHub Actions matrix does not build/test macOS
30+
31+
## Maintenance
32+
- Keep recipe metadata in sync with workflow matrix and package metadata
33+
- MKL version pinning: track Intel MKL releases through recipe deps
34+
- Python 3.14 in CI uses `conda-forge/label/python_rc` while pre-release

‎examples/AGENTS.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# AGENTS.md — examples/
2+
3+
Usage examples for mkl-service runtime control API.
4+
5+
## Files
6+
- **example.py** — basic usage: MKL version query, instruction dispatch control, and timing
7+
8+
## Examples cover
9+
- Querying MKL version/build info (`get_version()`, `get_version_string()`)
10+
- Controlling instruction dispatch with `enable_instructions()`
11+
- Using `dsecnd()` for simple timing
12+
13+
## Running examples
14+
```bash
15+
python examples/example.py
16+
```
17+
18+
## Notes
19+
- Examples assume MKL is installed (conda: `mkl` package)
20+
- Example is intended as a lightweight installation/runtime sanity check
21+
- Threading/domain APIs are available in `mkl-service` but not exercised in this example

‎mkl/AGENTS.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# AGENTS.md — mkl/
2+
3+
Core Python/Cython implementation: MKL support function wrappers and runtime control.
4+
5+
## Structure
6+
- `__init__.py` — public API, RTLD_GLOBAL context manager, module initialization
7+
- `_mkl_service.pyx` — Cython wrappers for MKL support functions
8+
- `_mkl_service.pxd` — Cython declarations (C function signatures)
9+
- `_mklinitmodule.c` — C extension for Linux-side MKL runtime preloading/init
10+
- `_init_helper.py` — Windows loading helper (DLL path setup in venv)
11+
- `_version.py` — version string (dynamic via setuptools)
12+
- `tests/` — unit tests for API functionality
13+
14+
## API categories
15+
### Threading control
16+
- `set_num_threads(n)` — global thread count
17+
- `get_max_threads()` — max threads available
18+
- `domain_set_num_threads(n, domain)` — per-domain threading (FFT, VML, etc.)
19+
- `domain_get_max_threads(domain)` — domain-specific max threads
20+
21+
### Version information
22+
- `get_version()` — MKL version dict
23+
- `get_version_string()` — formatted version string
24+
25+
### Memory management
26+
- `peak_mem_usage(memtype)` — peak memory usage stats
27+
- `mem_stat()` — memory allocation statistics
28+
29+
### CNR (Conditional Numerical Reproducibility)
30+
- `set_num_threads_local(n)` — thread-local thread count
31+
- CNR mode control functions
32+
33+
### Timing
34+
- `second()` — wall clock time
35+
- `dsecnd()` — high-precision timing
36+
37+
## Development guardrails
38+
- **Thread safety:** All threading functions must be thread-safe
39+
- **API stability:** Preserve function signatures (widely used in ecosystem)
40+
- **MKL dependency:** Assumes MKL is available at runtime (conda: mkl package)
41+
- **RTLD_GLOBAL preload path:** Linux preload is handled in `_mklinitmodule.c`; Windows DLL setup is in `_init_helper.py`
42+
43+
## Cython details
44+
- `_mkl_service.pyx` → generates `_py_mkl_service` extension module
45+
- `.pxd` file declares external C functions from MKL headers
46+
- Cython build requires MKL headers (`mkl-devel`)
47+
48+
## C init module
49+
- `_mklinitmodule.c` → `_mklinit` extension
50+
- Ensures MKL runtime is initialized with correct flags before Cython extension
51+
- Platform-specific behavior in current code:
52+
- Linux: `dlopen(..., RTLD_GLOBAL)` preload path (when applicable)
53+
- Windows: runtime DLL loading support is handled by `_init_helper.py`
54+
55+
## Notes
56+
- Domain strings: "fft", "vml", "pardiso", "blas", etc. (see MKL docs)
57+
- Threading changes affect all MKL-using libraries (NumPy, SciPy, etc.)
58+
- `MKL_VERBOSE` environment variable controls MKL diagnostic output

‎mkl/tests/AGENTS.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# AGENTS.md — mkl/tests/
2+
3+
Unit tests for MKL runtime control API.
4+
5+
## Test files
6+
- **test_mkl_service.py** — API functionality, threading control, version info
7+
8+
## Test coverage
9+
- Threading: `set_num_threads`, `get_max_threads`, domain-specific threading
10+
- Version: `get_version`, `get_version_string` format validation
11+
- Memory: `peak_mem_usage`, `mem_stat` (if supported by MKL build)
12+
- CNR: Conditional Numerical Reproducibility flags
13+
- Edge cases currently covered: thread-local settings and API round-trips
14+
15+
## Running tests
16+
```bash
17+
pytest mkl/tests/
18+
```
19+
20+
## CI integration
21+
- Tests run in `conda-package.yml` workflow
22+
- Separate test jobs per Python version and CI platform
23+
- CI coverage: Linux + Windows
24+
25+
## Adding tests
26+
- New API functions → add to `test_mkl_service.py` with validation
27+
- Threading behavior → test thread count changes take effect
28+
- Use `mkl.get_version()` to check MKL availability before tests

0 commit comments

Comments
 (0)