Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (92 loc) · 4.91 KB

AGENTS.md

File metadata and controls

108 lines (92 loc) · 4.91 KB
Raw

AGENTS.md

Entry point for agent context in this repo.

What this repository is

mkl-service provides a Python API for runtime control of Intel® oneMKL (Math Kernel Library). It exposes support functions for:

  • Threading control (set/get number of threads, domain-specific threading)
  • Version information (MKL version, build info)
  • Memory management (peak memory usage, memory statistics)
  • Conditional Numerical Reproducibility (CNR)
  • Timing functions (get CPU/wall clock time)
  • Miscellaneous utilities (MKL_VERBOSE control, etc.)

Originally part of Intel® Distribution for Python*, now a standalone package available via conda-forge and Intel channels.

Key components

  • Python interface: mkl/__init__.py — public API surface
  • Cython wrapper: mkl/_py_mkl_service.pyx — wraps MKL support functions
  • C init module: mkl/_mklinitmodule.c — Linux-side MKL runtime preloading / initialization
  • Helper: mkl/_init_helper.py — Windows venv DLL loading helper
  • Build system: meson-python + Cython

Build dependencies

Required:

  • Intel® oneMKL
  • meson-python
  • CMake
  • Ninja
  • Cython 3.1+ (required for the freethreading_compatible directive)
  • Python 3.10+

Build against an existing mkl installation:

Install the build dependencies via Conda:

conda install -c conda-forge mkl-devel "cython>=3.1.0" meson-python cmake ninja

or via pip:

python -m pip install mkl-devel "cython>=3.1.0" meson-python cmake ninja

then build without pulling a fresh mkl into an isolated build:

python -m pip install --no-deps --no-build-isolation .

CI/CD

  • Platforms in CI workflows: Linux, Windows, macOS (conda-forge workflow only)
  • Python versions: 3.10, 3.11, 3.12, 3.13, 3.14, 3.15, and free-threaded 3.14t
  • Python 3.14 ABI selection: conda jobs must request an explicit ABI, 3.14.* *_cp314 (GIL) or 3.14.* *_cp314t (free-threaded). Once the recipes stopped constraining python-gil, a bare --python 3.14 was observed to resolve to the free-threaded build, so it must not be relied on.
  • Python 3.15: GIL-only for now; conda-forge's python315 migration provides *_cp315 but no free-threaded *_cp315t yet. Conda jobs pin 3.15.* *_cp315 explicitly for the same ABI-selection reason as 3.14.
  • Workflows: .github/workflows/
    • conda-package.yml — main conda build/test pipeline
    • conda-package-cf.yml — conda build/test using only conda-forge channel
    • build-with-clang.yml — Linux Clang compatibility
    • build-with-standard-clang.yml — standard Clang compiler compatibility validation
    • build_pip.yml — validates editable build
    • pre-commit.yml — code quality checks
    • openssf-scorecard.yml — security scanning

Distribution

  • Conda: conda-forge and https://software.repos.intel.com/python/conda
  • PyPI: python -m pip install mkl-service

Usage

import mkl
mkl.set_num_threads(4)               # Set global thread count
mkl.domain_set_num_threads(1, "fft")  # FFT functions run sequentially
mkl.get_version_string()             # MKL version info

How to work in this repo

  • API stability: Preserve existing function signatures (widely used in ecosystem)
  • Threading: Changes to threading control must be thread-safe
  • CNR: Conditional Numerical Reproducibility flags require careful documentation
  • Testing: Add tests to mkl/tests/test_mkl_service.py
  • Docs: MKL support functions documented in Intel oneMKL Developer Reference

Code structure

  • Cython layer: _py_mkl_service.pyx + _mkl_service.pxd (C declarations)
  • C init: _mklinitmodule.c handles Linux preloading (dlopen(..., RTLD_GLOBAL)) for MKL runtime
  • Windows loading helper: _init_helper.py handles DLL path setup in Windows venv
  • Python wrapper: __init__.py imports _py_mkl_service (generated from .pyx)
  • Version: _version.py

Notes

  • RTLD_GLOBAL preloading is required on Linux (handled by RTLD_for_MKL context manager)
  • MKL must be available at runtime (conda: mkl, pip: relies on system MKL)
  • Do not add mkl to [project].dependencies in pyproject.toml (its PyPI wheel lacks .dist-info, which breaks pip check).
  • Threading functions affect NumPy, SciPy, and other MKL-backed libraries

Directory map

Below directories have local AGENTS.md for deeper context:

  • .github/AGENTS.md — CI/CD workflows and automation
  • mkl/AGENTS.md — Python/Cython implementation
  • mkl/tests/AGENTS.md — unit tests
  • conda-recipe/AGENTS.md — conda packaging
  • examples/AGENTS.md — usage examples

For broader IntelPython ecosystem context, see:

  • mkl_umath (MKL-backed NumPy ufuncs)
  • mkl_random (MKL-based random number generation)
  • mkl_fft (MKL-based fast fourier transform functions)
  • dpnp (Data Parallel NumPy)
  • dpctl (Data Parallel Control)