Patching Utilities

Overview

The easiest way to call optimized routines from the Extension for Scikit-learn* is by patching the sklearn module from scikit-learn, which can be achieved with just a call to sklearnex.patch_sklearn:

from sklearnex import patch_sklearn
from sklearnex import is_patched_instance
from sklearn.linear_model import LinearRegression

is_patched_instance(LinearRegression()) == False

patch_sklearn()
from sklearn.linear_model import LinearRegression # now calls sklearnex
is_patched_instance(LinearRegression()) == True

Patching can be applied either temporarily for a Python session (change is applied at the process level), or permanently at the module level by modifying the files in the installed sklearn module to apply patching before importing sklearn.

Either patching mechanism (process-level or module-level) can be applied from inside a Python session, or through command line arguments for the Python process.

Temporary Patching

Once you install the Extension for Scikit-learn*, you can replace estimator classes (algorithms) that exist in the sklearn module from scikit-learn with their optimized versions from the extension. This action is called patching or monkey patching. This is not a permanent change so you can always undo the patching dynamically if necessary.

To patch scikit-learn with the Extension for Scikit-learn*, the following methods can be used:

Method

Action

Use a flag in the command line

Run this command:

python -m sklearnex my_application.py

Modify your script

Add the following lines before importing from sklearn:

from sklearnex import patch_sklearn
patch_sklearn()

Import an estimator from the sklearnex module

Run this command:

from sklearnex.neighbors import NearestNeighbors

These patching methods are interchangeable, with the only difference that if importing estimators from sklearnex without patching and using them inside metaestimators from sklearn (such as sklearn.model_selection.GridSearchCV), it will not be able to correctly propagate all options from configuration contexts from sklearnex (requires patching).

Unpatching

To undo the patch (also called unpatching) means to return the sklearn module to the original implementation from scikit-learn, replacing patched estimators from the Extension for Scikit-learn* with their stock scikit-learn analogs.

In order for changes to take effect, you must reimport the sklearn module(s) afterwards:

sklearnex.unpatch_sklearn()
# Re-import scikit-learn algorithms after the unpatch
from sklearn.cluster import KMeans

Example

This example shows how to patch scikit-learn inside a Python session by modifying your script. To make sure that patching is registered by the scikit-learn estimators, always import module sklearn after calling the patching function:

Example: Drop-In Patching
  import numpy as np
  from sklearnex import patch_sklearn
  patch_sklearn()

  # You need to re-import scikit-learn algorithms after the patch
  from sklearn.cluster import KMeans

  # The optimized estimators follow the same API as the originals
  X = np.array([[1,  2], [1,  4], [1,  0],
                [10, 2], [10, 4], [10, 0]])
  kmeans = KMeans(n_clusters=2, random_state=0).fit(X)
  print(f"kmeans.labels_ = {kmeans.labels_}")

Permanent Patching

You can also use global patching to permanently patch all your scikit-learn applications without any additional actions, by modifying the files in the installed sklearn module.

Before you begin, make sure that you have read and write permissions for the installed sklearn module files.

With global patching, you can:

Task

Action

Note

Patch all supported algorithms

Run this command:

python -m sklearnex.glob patch_sklearn

If you run the global patching command several times with different parameters, then only the last configuration is applied.

Patch selected algorithms

Use --algorithm or -a keys with a list of algorithms to patch. For example, to patch only sklearn.svm.SVC and sklearn.ensemble.RandomForestClassifier estimators, run

python -m sklearnex.glob patch_sklearn -a sklearn.svm.SVC sklearn.ensemble.RandomForestClassifier

Enable global patching via code

Use the patch_sklearn function with the global_patch argument:

from sklearnex import patch_sklearn
patch_sklearn(global_patch=True)
import sklearn

After that, patching is applied in the current application and in all others that use the same environment.

Disable patching notifications

Use --no-verbose or -nv keys:

python -m sklearnex.glob patch_sklearn -a sklearn.svm.SVC sklearn.ensemble.RandomForestClassifier -nv

Disable global patching

Run this command:

python -m sklearnex.glob unpatch_sklearn

Disable global patching via code

Use the global_patch argument in the unpatch_sklearn function

from sklearnex import unpatch_sklearn
unpatch_sklearn(global_patch=True)

Tip

Pass verbose=True to make it print a message confirming that the Extension for Scikit-learn* is being used when importing sklearn.

Note

If you clone an environment with enabled global patching, it will already be applied in the new environment.

API Reference

sklearnex.patch_sklearn(name: str | list[str] | None = None, verbose: bool = True, global_patch: bool = False, preview: bool = False) → None[source]

Apply patching to the sklearn module.

Patches the sklearn module from scikit-learn to make calls to the accelerated versions of estimators and functions from the Extension for Scikit-learn*, either as a whole or on a per-estimator basis.

Notes

If estimators from sklearn have already been imported before patch_sklearn is called, they need to be re-imported in order for the patching to take effect.

See also

is_patched_instance

To verify that an instance of an estimator is patched.

unpatch_sklearn

To undo the patching.

Parameters:

  • name (str, list of str, or None) –

    Names of the desired estimators to patch. Can pass a single instance name (e.g. "sklearn.linear_model.LogisticRegression"), or a list of names (e.g. ["sklearn.linear_model.LogisticRegression", "sklearn.decomposition.PCA"]).

    If None, will patch all the supported estimators.

    See the algorithm support table for more information.

    Note that functions related to config contexts are always patched regardless of what’s passed here.

  • verbose (bool) –

    Whether to print information messages about the patching being applied or not.

    Note that this refers only to a message about patching applied through this function. Passing True here does not enable verbose mode for further estimator calls.

    When the message is printed, it will use the Python stderr stream.

  • global_patch (bool) –

    Whether to apply the patching on the installed sklearn module itself, which is a mechanism that persists across sessions and processes.

    If True, the sklearn module files will be modified to apply patching immediately upon import of this module, so that next time, importing of sklearnex will not be necessary.

  • preview (bool) –

    Whether to include the preview estimators in the patching.

    Note that this will forcibly set the environment variable SKLEARNEX_PREVIEW.

    If environment variable SKLEARNEX_PREVIEW is set at the moment this function is called, preview estimators will be patched regardless.

Examples

>>> from sklearnex import is_patched_instance
>>> from sklearnex import patch_sklearn
>>> from sklearn.linear_model import LinearRegression
>>> is_patched_instance(LinearRegression())
False
>>> patch_sklearn()
>>> from sklearn.linear_model import LinearRegression # now calls sklearnex
>>> is_patched_instance(LinearRegression())
True
sklearnex.unpatch_sklearn(name: str | list[str] | None = None, global_unpatch: bool = False) → None[source]

Unpatch scikit-learn.

Unpatches the sklearn module, either as a whole or for selected estimators.

Parameters:

  • name (str, list of str, or None) –

    Names of the desired estimators to check for patching status. Can pass a single instance name (e.g. "sklearn.linear_model.LogisticRegression"), or a list of names (e.g. ["sklearn.linear_model.LogisticRegression", "sklearn.decomposition.PCA"]).

    If None, will unpatch all the etimators that are patched.

  • global_unpatch (bool) – Whether to unpatch the installed sklearn module itself, if patching had been applied to it (see patch_sklearn).

sklearnex.sklearn_is_patched(name: str | list[str] | None = None, return_map: bool | None = False) → bool | dict[str, bool][source]

Check patching status.

Checks whether patching of scikit-learn estimators has been applied, either as a whole or for a subset of estimators.

Parameters:

  • name (str, list of str, or None) –

    Names of the desired estimators to check for patching status. Can pass a single instance name (e.g. "LogisticRegression"), or a list of names (e.g. ["LogisticRegression", "PCA"]).

    If None, will check for patching status of all estimators.

  • return_map (bool) – Whether to return per-estimator patching statuses, or just a single result, which will be True if all the estimators from name are patched.

Returns:

Check – The patching status of the desired estimators, either as a whole, or on a per-estimator basis (output type controlled by return_map).

Return type:

bool or dict[str, bool]

sklearnex.is_patched_instance(instance: object) → bool[source]

Check if given estimator instance is patched with scikit-learn-intelex.

Parameters:

instance (object) – Python object, usually a scikit-learn estimator instance.

Returns:

Check – Boolean whether instance is a daal4py or sklearnex estimator.

Return type:

bool

Examples

>>> from sklearnex import is_patched_instance
>>> from sklearn.linear_model import LinearRegression
>>> from sklearnex.linear_model import LinearRegression as patched_LR
>>> is_patched_instance(LinearRegression())
False
>>> is_patched_instance(patched_LR())
True