scikit-learn-intelex 2025.1.0__py39-none-manylinux_2_28_x86_64.whl

sklearnex/__main__.py

@@ -0,0 +1,58 @@
+# ==============================================================================
+# Copyright 2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+import sys
+
+from sklearnex import patch_sklearn
+
+
+def _main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="python -m sklearnex",
+        description="""
+            Run your Python script with Intel(R) Extension for
+            scikit-learn, optimizing solvers of
+            scikit-learn with Intel(R) oneAPI Data Analytics Library.
+            """,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument(
+        "-m", action="store_true", dest="module", help="Executes following as a module"
+    )
+    parser.add_argument("name", help="Script or module name")
+    parser.add_argument("args", nargs=argparse.REMAINDER, help="Command line arguments")
+    args = parser.parse_args()
+
+    try:
+        import sklearn
+
+        patch_sklearn()
+    except ImportError:
+        print("Scikit-learn could not be imported. Nothing to patch")
+
+    sys.argv = [args.name] + args.args
+    if "_" + args.name in globals():
+        return globals()["_" + args.name](*args.args)
+    import runpy
+
+    runf = runpy.run_module if args.module else runpy.run_path
+    runf(args.name, run_name="__main__")
+
+
+sys.exit(_main())

sklearnex/_config.py

@@ -0,0 +1,116 @@
+# ==============================================================================
+# Copyright 2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+from contextlib import contextmanager
+from os import environ
+
+from sklearn import get_config as skl_get_config
+from sklearn import set_config as skl_set_config
+
+from daal4py.sklearn._utils import sklearn_check_version
+from onedal._config import _get_config as onedal_get_config
+
+
+def get_config():
+    """Retrieve current values for configuration set by :func:`set_config`
+    Returns
+    -------
+    config : dict
+        Keys are parameter names that can be passed to :func:`set_config`.
+    See Also
+    --------
+    config_context : Context manager for global configuration.
+    set_config : Set global configuration.
+    """
+    sklearn = skl_get_config()
+    sklearnex = onedal_get_config()
+    return {**sklearn, **sklearnex}
+
+
+def set_config(
+    target_offload=None,
+    allow_fallback_to_host=None,
+    allow_sklearn_after_onedal=None,
+    **sklearn_configs,
+):
+    """Set global configuration
+    Parameters
+    ----------
+    target_offload : string or dpctl.SyclQueue, default=None
+        The device primarily used to perform computations.
+        If string, expected to be "auto" (the execution context
+        is deduced from input data location),
+        or SYCL* filter selector string. Global default: "auto".
+    allow_fallback_to_host : bool, default=None
+        If True, allows to fallback computation to host device
+        in case particular estimator does not support the selected one.
+        Global default: False.
+    allow_sklearn_after_onedal : bool, default=None
+        If True, allows to fallback computation to sklearn after onedal
+        backend in case of runtime error on onedal backend computations.
+        Global default: True.
+    See Also
+    --------
+    config_context : Context manager for global configuration.
+    get_config : Retrieve current values of the global configuration.
+    """
+
+    array_api_dispatch = sklearn_configs.get("array_api_dispatch", False)
+    if array_api_dispatch and sklearn_check_version("1.6"):
+        environ["SCIPY_ARRAY_API"] = "1"
+
+    skl_set_config(**sklearn_configs)
+
+    local_config = onedal_get_config(copy=False)
+
+    if target_offload is not None:
+        local_config["target_offload"] = target_offload
+    if allow_fallback_to_host is not None:
+        local_config["allow_fallback_to_host"] = allow_fallback_to_host
+    if allow_sklearn_after_onedal is not None:
+        local_config["allow_sklearn_after_onedal"] = allow_sklearn_after_onedal
+
+
+@contextmanager
+def config_context(**new_config):
+    """Context manager for global scikit-learn configuration
+    Parameters
+    ----------
+    target_offload : string or dpctl.SyclQueue, default=None
+        The device primarily used to perform computations.
+        If string, expected to be "auto" (the execution context
+        is deduced from input data location),
+        or SYCL* filter selector string. Global default: "auto".
+    allow_fallback_to_host : bool, default=None
+        If True, allows to fallback computation to host device
+        in case particular estimator does not support the selected one.
+        Global default: False.
+    Notes
+    -----
+    All settings, not just those presently modified, will be returned to
+    their previous values when the context manager is exited.
+    See Also
+    --------
+    set_config : Set global scikit-learn configuration.
+    get_config : Retrieve current values of the global configuration.
+    """
+    old_config = get_config()
+    set_config(**new_config)
+
+    try:
+        yield
+    finally:
+        set_config(**old_config)

sklearnex/_device_offload.py

@@ -0,0 +1,126 @@
+# ==============================================================================
+# Copyright 2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+from functools import wraps
+
+from onedal._device_offload import _copy_to_usm, _get_global_queue, _transfer_to_host
+from onedal.utils._array_api import _asarray
+from onedal.utils._dpep_helpers import dpnp_available
+
+if dpnp_available:
+    import dpnp
+    from onedal.utils._array_api import _convert_to_dpnp
+
+from ._config import get_config
+
+
+def _get_backend(obj, queue, method_name, *data):
+    cpu_device = queue is None or queue.sycl_device.is_cpu
+    gpu_device = queue is not None and queue.sycl_device.is_gpu
+
+    if cpu_device:
+        patching_status = obj._onedal_cpu_supported(method_name, *data)
+        if patching_status.get_status():
+            return "onedal", queue, patching_status
+        else:
+            return "sklearn", None, patching_status
+
+    allow_fallback_to_host = get_config()["allow_fallback_to_host"]
+
+    if gpu_device:
+        patching_status = obj._onedal_gpu_supported(method_name, *data)
+        if patching_status.get_status():
+            return "onedal", queue, patching_status
+        else:
+            if allow_fallback_to_host:
+                patching_status = obj._onedal_cpu_supported(method_name, *data)
+                if patching_status.get_status():
+                    return "onedal", None, patching_status
+                else:
+                    return "sklearn", None, patching_status
+            else:
+                return "sklearn", None, patching_status
+
+    raise RuntimeError("Device support is not implemented")
+
+
+def dispatch(obj, method_name, branches, *args, **kwargs):
+    q = _get_global_queue()
+    has_usm_data_for_args, q, hostargs = _transfer_to_host(q, *args)
+    has_usm_data_for_kwargs, q, hostvalues = _transfer_to_host(q, *kwargs.values())
+    hostkwargs = dict(zip(kwargs.keys(), hostvalues))
+
+    backend, q, patching_status = _get_backend(obj, q, method_name, *hostargs)
+    has_usm_data = has_usm_data_for_args or has_usm_data_for_kwargs
+    if backend == "onedal":
+        # Host args only used before onedal backend call.
+        # Device will be offloaded when onedal backend will be called.
+        patching_status.write_log(queue=q, transferred_to_host=False)
+        return branches[backend](obj, *hostargs, **hostkwargs, queue=q)
+    if backend == "sklearn":
+        if (
+            "array_api_dispatch" in get_config()
+            and get_config()["array_api_dispatch"]
+            and "array_api_support" in obj._get_tags()
+            and obj._get_tags()["array_api_support"]
+            and not has_usm_data
+        ):
+            # USM ndarrays are also excluded for the fallback Array API. Currently, DPNP.ndarray is
+            # not compliant with the Array API standard, and DPCTL usm_ndarray Array API is compliant,
+            # except for the linalg module. There is no guarantee that stock scikit-learn will
+            # work with such input data. The condition will be updated after DPNP.ndarray and
+            # DPCTL usm_ndarray enabling for conformance testing and these arrays supportance
+            # of the fallback cases.
+            # If `array_api_dispatch` enabled and array api is supported for the stock scikit-learn,
+            # then raw inputs are used for the fallback.
+            patching_status.write_log(transferred_to_host=False)
+            return branches[backend](obj, *args, **kwargs)
+        else:
+            patching_status.write_log()
+            return branches[backend](obj, *hostargs, **hostkwargs)
+    raise RuntimeError(
+        f"Undefined backend {backend} in " f"{obj.__class__.__name__}.{method_name}"
+    )
+
+
+def wrap_output_data(func):
+    """
+    Converts and moves the output arrays of the decorated function
+    to match the input array type and device.
+    """
+
+    @wraps(func)
+    def wrapper(self, *args, **kwargs):
+        result = func(self, *args, **kwargs)
+        if not (len(args) == 0 and len(kwargs) == 0):
+            data = (*args, *kwargs.values())
+            usm_iface = getattr(data[0], "__sycl_usm_array_interface__", None)
+            if usm_iface is not None:
+                result = _copy_to_usm(usm_iface["syclobj"], result)
+                if dpnp_available and isinstance(data[0], dpnp.ndarray):
+                    result = _convert_to_dpnp(result)
+                return result
+            config = get_config()
+            if not ("transform_output" in config and config["transform_output"]):
+                input_array_api = getattr(data[0], "__array_namespace__", lambda: None)()
+                if input_array_api:
+                    input_array_api_device = data[0].device
+                    result = _asarray(
+                        result, input_array_api, device=input_array_api_device
+                    )
+        return result
+
+    return wrapper

sklearnex/_utils.py

@@ -0,0 +1,132 @@
+# ===============================================================================
+# Copyright 2021 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===============================================================================
+
+import logging
+import os
+import sys
+import warnings
+from abc import ABC
+
+from daal4py.sklearn._utils import (
+    PatchingConditionsChain as daal4py_PatchingConditionsChain,
+)
+from daal4py.sklearn._utils import daal_check_version
+
+
+class PatchingConditionsChain(daal4py_PatchingConditionsChain):
+    def get_status(self):
+        return self.patching_is_enabled
+
+    def write_log(self, queue=None, transferred_to_host=True):
+        if self.patching_is_enabled:
+            self.logger.info(
+                f"{self.scope_name}: {get_patch_message('onedal', queue=queue, transferred_to_host=transferred_to_host)}"
+            )
+        else:
+            self.logger.debug(
+                f"{self.scope_name}: debugging for the patch is enabled to track"
+                " the usage of Intel® oneAPI Data Analytics Library (oneDAL)"
+            )
+            for message in self.messages:
+                self.logger.debug(
+                    f"{self.scope_name}: patching failed with cause - {message}"
+                )
+            self.logger.info(
+                f"{self.scope_name}: {get_patch_message('sklearn', transferred_to_host=transferred_to_host)}"
+            )
+
+
+def set_sklearn_ex_verbose():
+    log_level = os.environ.get("SKLEARNEX_VERBOSE")
+
+    logger = logging.getLogger("sklearnex")
+    logging_channel = logging.StreamHandler()
+    logging_formatter = logging.Formatter("%(levelname)s:%(name)s: %(message)s")
+    logging_channel.setFormatter(logging_formatter)
+    logger.addHandler(logging_channel)
+
+    try:
+        if log_level is not None:
+            logger.setLevel(log_level)
+    except Exception:
+        warnings.warn(
+            'Unknown level "{}" for logging.\n'
+            'Please, use one of "CRITICAL", "ERROR", '
+            '"WARNING", "INFO", "DEBUG".'.format(log_level)
+        )
+
+
+def get_patch_message(s, queue=None, transferred_to_host=True):
+    if s == "onedal":
+        message = "running accelerated version on "
+        if queue is not None:
+            if queue.sycl_device.is_gpu:
+                message += "GPU"
+            elif queue.sycl_device.is_cpu:
+                message += "CPU"
+            else:
+                raise RuntimeError("Unsupported device")
+        else:
+            message += "CPU"
+    elif s == "sklearn":
+        message = "fallback to original Scikit-learn"
+    elif s == "sklearn_after_onedal":
+        message = "failed to run accelerated version, fallback to original Scikit-learn"
+    else:
+        raise ValueError(
+            f"Invalid input - expected one of 'onedal','sklearn',"
+            f" 'sklearn_after_onedal', got {s}"
+        )
+    if transferred_to_host:
+        message += (
+            ". All input data transferred to host for further backend computations."
+        )
+    return message
+
+
+def get_sklearnex_version(rule):
+    return daal_check_version(rule)
+
+
+def register_hyperparameters(hyperparameters_map):
+    """Decorator for hyperparameters support in estimator class.
+    Adds `get_hyperparameters` method to class.
+    """
+
+    def wrap_class(estimator_class):
+        def get_hyperparameters(self, op):
+            return hyperparameters_map[op]
+
+        estimator_class.get_hyperparameters = get_hyperparameters
+        return estimator_class
+
+    return wrap_class
+
+
+# This abstract class is meant to generate a clickable doc link for classses
+# in sklearnex that are not part of base scikit-learn. It should be inherited
+# before inheriting from a scikit-learn estimator, otherwise will get overriden
+# by the estimator's original.
+class IntelEstimator(ABC):
+    @property
+    def _doc_link_module(self) -> str:
+        return "sklearnex"
+
+    @property
+    def _doc_link_template(self) -> str:
+        module_path, _ = self.__class__.__module__.rsplit(".", 1)
+        class_name = self.__class__.__name__
+        return f"https://intel.github.io/scikit-learn-intelex/latest/non-scikit-algorithms.html#{module_path}.{class_name}"

sklearnex/basic_statistics/__init__.py

@@ -0,0 +1,20 @@
+# ==============================================================================
+# Copyright 2023 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+from .basic_statistics import BasicStatistics
+from .incremental_basic_statistics import IncrementalBasicStatistics
+
+__all__ = ["BasicStatistics", "IncrementalBasicStatistics"]

sklearnex/basic_statistics/basic_statistics.py

@@ -0,0 +1,230 @@
+# ==============================================================================
+# Copyright 2023 Intel Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+import warnings
+
+import numpy as np
+from sklearn.base import BaseEstimator
+from sklearn.utils import check_array
+from sklearn.utils.validation import _check_sample_weight
+
+from daal4py.sklearn._n_jobs_support import control_n_jobs
+from daal4py.sklearn._utils import sklearn_check_version
+from onedal.basic_statistics import BasicStatistics as onedal_BasicStatistics
+
+from .._device_offload import dispatch
+from .._utils import IntelEstimator, PatchingConditionsChain
+
+if sklearn_check_version("1.6"):
+    from sklearn.utils.validation import validate_data
+else:
+    validate_data = BaseEstimator._validate_data
+
+if sklearn_check_version("1.2"):
+    from sklearn.utils._param_validation import StrOptions
+
+
+@control_n_jobs(decorated_methods=["fit"])
+class BasicStatistics(IntelEstimator, BaseEstimator):
+    """
+    Estimator for basic statistics.
+    Allows to compute basic statistics for provided data.
+
+    Parameters
+    ----------
+    result_options: string or list, default='all'
+        Used to set statistics to calculate. Possible values are ``'min'``, ``'max'``, ``'sum'``, ``'mean'``, ``'variance'``,
+        ``'variation'``, ``sum_squares'``, ``sum_squares_centered'``, ``'standard_deviation'``, ``'second_order_raw_moment'``
+        or a list containing any of these values. If set to ``'all'`` then all possible statistics will be
+        calculated.
+
+    Attributes
+    ----------
+        min_ : ndarray of shape (n_features,)
+            Minimum of each feature over all samples.
+        max_ : ndarray of shape (n_features,)
+            Maximum of each feature over all samples.
+        sum_ : ndarray of shape (n_features,)
+            Sum of each feature over all samples.
+        mean_ : ndarray of shape (n_features,)
+            Mean of each feature over all samples.
+        variance_ : ndarray of shape (n_features,)
+            Variance of each feature over all samples.
+        variation_ : ndarray of shape (n_features,)
+            Variation of each feature over all samples.
+        sum_squares_ : ndarray of shape (n_features,)
+            Sum of squares for each feature over all samples.
+        standard_deviation_ : ndarray of shape (n_features,)
+            Standard deviation of each feature over all samples.
+        sum_squares_centered_ : ndarray of shape (n_features,)
+            Centered sum of squares for each feature over all samples.
+        second_order_raw_moment_ : ndarray of shape (n_features,)
+            Second order moment of each feature over all samples.
+
+    Note
+    ----
+    Attribute exists only if corresponding result option has been provided.
+
+    Note
+    ----
+    Names of attributes without the trailing underscore are
+    supported currently but deprecated in 2025.1 and will be removed in 2026.0
+
+    Note
+    ----
+    Some results can exhibit small variations due to
+    floating point error accumulation and multithreading.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from sklearnex.basic_statistics import BasicStatistics
+    >>> bs = BasicStatistics(result_options=['sum', 'min', 'max'])
+    >>> X = np.array([[1, 2], [3, 4]])
+    >>> bs.fit(X)
+    >>> bs.sum_
+    np.array([4., 6.])
+    >>> bs.min_
+    np.array([1., 2.])
+    """
+
+    def __init__(self, result_options="all"):
+        self.result_options = result_options
+
+    _onedal_basic_statistics = staticmethod(onedal_BasicStatistics)
+
+    if sklearn_check_version("1.2"):
+        _parameter_constraints: dict = {
+            "result_options": [
+                StrOptions(
+                    {
+                        "all",
+                        "min",
+                        "max",
+                        "sum",
+                        "mean",
+                        "variance",
+                        "variation",
+                        "sum_squares",
+                        "standard_deviation",
+                        "sum_squares_centered",
+                        "second_order_raw_moment",
+                    }
+                ),
+                list,
+            ],
+        }
+
+    def _save_attributes(self):
+        assert hasattr(self, "_onedal_estimator")
+
+        if self.result_options == "all":
+            result_options = onedal_BasicStatistics.get_all_result_options()
+        else:
+            result_options = self.result_options
+
+        if isinstance(result_options, str):
+            setattr(
+                self,
+                result_options + "_",
+                getattr(self._onedal_estimator, result_options),
+            )
+        elif isinstance(result_options, list):
+            for option in result_options:
+                setattr(self, option + "_", getattr(self._onedal_estimator, option))
+
+    def __getattr__(self, attr):
+        if self.result_options == "all":
+            result_options = onedal_BasicStatistics.get_all_result_options()
+        else:
+            result_options = self.result_options
+        is_deprecated_attr = (
+            isinstance(result_options, str) and (attr == result_options)
+        ) or (isinstance(result_options, list) and (attr in result_options))
+        if is_deprecated_attr:
+            warnings.warn(
+                "Result attributes without a trailing underscore were deprecated in version 2025.1 and will be removed in 2026.0"
+            )
+            attr += "_"
+        if attr in self.__dict__:
+            return self.__dict__[attr]
+
+        raise AttributeError(
+            f"'{self.__class__.__name__}' object has no attribute '{attr}'"
+        )
+
+    def _onedal_supported(self, method_name, *data):
+        patching_status = PatchingConditionsChain(
+            f"sklearnex.basic_statistics.{self.__class__.__name__}.{method_name}"
+        )
+        return patching_status
+
+    _onedal_cpu_supported = _onedal_supported
+    _onedal_gpu_supported = _onedal_supported
+
+    def _onedal_fit(self, X, sample_weight=None, queue=None):
+        if sklearn_check_version("1.2"):
+            self._validate_params()
+
+        if sklearn_check_version("1.0"):
+            X = validate_data(self, X, dtype=[np.float64, np.float32], ensure_2d=False)
+        else:
+            X = check_array(X, dtype=[np.float64, np.float32])
+
+        if sample_weight is not None:
+            sample_weight = _check_sample_weight(sample_weight, X)
+
+        onedal_params = {
+            "result_options": self.result_options,
+        }
+
+        if not hasattr(self, "_onedal_estimator"):
+            self._onedal_estimator = self._onedal_basic_statistics(**onedal_params)
+        self._onedal_estimator.fit(X, sample_weight, queue)
+        self._save_attributes()
+        self.n_features_in_ = X.shape[1] if len(X.shape) > 1 else 1
+
+    def fit(self, X, y=None, *, sample_weight=None):
+        """Calculate statistics of X.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Data for compute, where ``n_samples`` is the number of samples and
+            ``n_features`` is the number of features.
+
+        y : Ignored
+            Not used, present for API consistency by convention.
+
+        sample_weight : array-like of shape (n_samples,), default=None
+            Weights for compute weighted statistics, where ``n_samples`` is the number of samples.
+
+        Returns
+        -------
+        self : object
+            Returns the instance itself.
+        """
+        dispatch(
+            self,
+            "fit",
+            {
+                "onedal": self.__class__._onedal_fit,
+                "sklearn": None,
+            },
+            X,
+            sample_weight,
+        )
+        return self