Metadata-Version: 2.4
Name: mkl_umath
Version: 0.5.0
Summary: Intel (R) MKL-based universal functions for NumPy arrays
Keywords: mkl_umath
Author-Email: Intel Corporation <scripting@intel.com>
License-Expression: BSD-3-Clause
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Project-URL: Download, http://github.com/IntelPython/mkl_umath
Project-URL: Homepage, http://github.com/IntelPython/mkl_umath
Requires-Python: <3.15,>=3.10
Provides-Extra: test
Description-Content-Type: text/markdown
Requires-Dist: intel-cmplr-lib-rt >=2026.1.1,<2027.0a0
Requires-Dist: intel-openmp >=2026.1.1,<2027.0a0
Requires-Dist: mkl >=2026.1.0,<2027.0a0
Requires-Dist: numpy >=1.26.4

[![Conda package](https://github.com/IntelPython/mkl_umath/actions/workflows/conda-package.yml/badge.svg)](https://github.com/IntelPython/mkl_umath/actions/workflows/conda-package.yml)
[![Build using pip and pre-release NumPy](https://github.com/IntelPython/mkl_umath/actions/workflows/build_pip.yml/badge.svg)](https://github.com/IntelPython/mkl_umath/actions/workflows/build_pip.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/IntelPython/mkl_umath/badge)](https://securityscorecards.dev/viewer/?uri=github.com/IntelPython/mkl_umath)

# `mkl_umath`

`mkl_umath._ufuncs` exposes [Intel® OneAPI Math Kernel Library (OneMKL)](https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html)
powered version of loops used in the patched version of [NumPy](https://numpy.org), that used to be included in
[Intel® Distribution for Python*](https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-python.html).

Patches were factored out per community feedback ([NEP-36](https://numpy.org/neps/nep-0036-fair-play.html)).

`mkl_umath` started as a part of Intel® Distribution for Python* optimizations to NumPy, and is now being released
as a stand-alone package. It can be installed into conda environment using:

```
   conda install -c https://software.repos.intel.com/python/conda mkl_umath
```

---

To install mkl_umath PyPI package please use the following command:

```
   python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_umath
```

If command above installs NumPy package from the PyPI, please use the following command to install Intel optimized NumPy wheel package from Intel PyPI Cloud:

```
   python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_umath numpy==<numpy_version>
```

where `<numpy_version>` should be the latest version from https://software.repos.intel.com/python/conda/.

---

# Patching Mechanisms

`mkl_umath` provides convenient patch methods to enable MKL-accelerated
umath operations in NumPy with or without modifying your code.

## CLI Quickstart

### Persistent patch (all Python sessions)

```bash
# Install
python -m mkl_umath --patch install

# Status (exit code: 0 = installed, 1 = not installed)
python -m mkl_umath --patch status

# Remove
python -m mkl_umath --patch uninstall
```

### Verify patch state

```bash
python -c "import mkl_umath; print(f'mkl_umath.is_patched(): {mkl_umath.is_patched()}')"
```

### One-shot patch (single command only)

```bash
# Script
python -m mkl_umath --with-numpy-patch my_script.py

# Pytest
python -m mkl_umath --with-numpy-patch -m pytest tests/

# One-liner
python -m mkl_umath --with-numpy-patch -c "import mkl_umath; print(f\"mkl_umath.is_patched(): {mkl_umath.is_patched()}\")"

# Non-Python command
python -m mkl_umath --with-numpy-patch -- <command> [args...]
```

## Programmatic Quickstart

```python
import mkl_umath
import numpy

mkl_umath.patch_numpy_umath()
print(mkl_umath.is_patched())
# run your accelerated numpy workloads here!
mkl_umath.restore_numpy_umath()
```

```python
import mkl_umath
import numpy
with mkl_umath.mkl_umath():
   # run your accelerated workloads here!
   pass
```
---

## Building from source

A C compiler, Intel® oneAPI Math Kernel Library (oneMKL), and NumPy are required
to build `mkl_umath` from source.

Executing
```sh
CC=icx python -m pip install .
```
will pull in the required build dependencies, including `mkl-devel` and `numpy`, and build `mkl_umath`.

If you already have `mkl` and `numpy` installed (from your system or a conda environment)
and want to reuse them instead of pulling fresh copies into an isolated build, first
install the build dependencies:
```sh
pip install meson-python ninja cmake cython numpy mkl-devel
```

then build against the existing installation with:
```sh
CC=icx pip install --no-build-isolation --no-deps .
```