clarify details on gpu support, remove references to dpctl arrays

Author: david-cortes-intel

doc/sources/array_api.rst

@@ -23,9 +23,8 @@ Overview
 
 Many estimators from the |sklearnex| support passing data classes that conform to the
 `Array API <https://data-apis.org/array-api/>`_ specification as inputs to methods like ``.fit()``
-and ``.predict()``, such as :external+dpnp:doc:`dpnp.ndarray <reference/ndarray>` or
-`torch.tensor <https://docs.pytorch.org/docs/stable/tensors.html>`__. This is particularly
-useful for GPU computations, as it allows performing operations on inputs that are already
+and ``.predict()``, such as |dpnp_array| or `torch.tensor <https://docs.pytorch.org/docs/stable/tensors.html>`__.
+This is particularly useful for GPU computations, as it allows performing operations on inputs that are already
 on GPU without moving the data from host to device.
 
 .. important::
@@ -80,6 +79,7 @@ in many cases they are.
     classes that have :external+dpctl:doc:`USM data <api_reference/dpctl/memory>`. In order to ensure that computations
     happen on the intended device under array API, make sure that the data is already on the desired device.
 
+.. _array_api_estimators:
 
 Supported classes
 =================
@@ -98,11 +98,10 @@ The following patched classes have support for array API inputs:
 - :obj:`sklearnex.linear_model.IncrementalRidge`
 
 .. note::
-    While full array API support is currently not implemented for all classes, :external+dpnp:doc:`dpnp.ndarray <reference/ndarray>`
-    and :external+dpctl:doc:`dpctl.tensor <api_reference/dpctl/tensor>` inputs are supported by all the classes
-    that have :ref:`GPU support <oneapi_gpu>`. Note however that if array API support is not enabled in |sklearn|,
-    when passing these classes as inputs, data will be transferred to host and then back to device instead of being
-    used directly.
+    While full array API support is currently not implemented for all classes, |dpnp_array| inputs are supported
+    by all the classes that have :ref:`GPU support <oneapi_gpu>`. Note however that if array API support is not
+    enabled in |sklearn|, when passing these classes as inputs, data will be transferred to host and then back to
+    device instead of being used directly.
 
 
 Example usage

doc/sources/config-contexts.rst

@@ -0,0 +1,91 @@
+.. Copyright contributors to the oneDAL project
+..
+.. 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.
+.. include:: substitutions.rst
+.. _config_contexts:
+
+=========================================
+Configuration Contexts and Global Options
+=========================================
+
+Overview
+========
+
+Just like |sklearn|, the |sklearnex| offers configurable options which can be managed
+locally through a configuration context, or globally through process-wide settings,
+by extending the configuration-related functions from |sklearn| (see :obj:`sklearn.config_context`
+for details).
+
+Configurations in the |sklearnex| are particularly useful for :ref:`GPU functionalities <oneapi_gpu>`
+and :ref:`SMPD mode <distributed>`, and are necessary to modify for enabling :ref:`array API <array_api>`.
+
+Configuration context and global options manager for the |sklearnex| can either be imported directly
+from the module ``sklearnex``, or can be imported from the ``sklearn`` module after applying patching.
+
+Note that options in the |sklearnex| are a superset of options from |sklearn|, and options passed to
+the configuration contexts and global settings of the |sklearnex| will also affect |sklearn| if the
+option is supported by it - meaning: the same context manager  or global option setter is used for
+both libraries.
+
+Example usage
+=============
+
+Example using the ``target_offload`` option to make computations run on a GPU:
+
+With a local context
+--------------------
+
+Here, only the operations from |sklearn| and from the |sklearnex| that happen within the 'with'
+block will be affected by the options:
+
+.. code:: python
+
+    import numpy as np
+    from sklearnex import config_context
+    from sklearnex.cluster import DBSCAN
+
+    X = np.array([[1., 2.], [2., 2.], [2., 3.],
+                  [8., 7.], [8., 8.], [25., 80.]], dtype=np.float32)
+    with config_context(target_offload="gpu"):
+        clustering = DBSCAN(eps=3, min_samples=2).fit(X)
+
+As a global option
+------------------
+
+Here, all computations from |sklearn| and from the |sklearnex| that happen after the option
+is modified are affected:
+
+.. code:: python
+
+    import numpy as np
+    from sklearnex import set_config
+    from sklearnex.cluster import DBSCAN
+
+    X = np.array([[1., 2.], [2., 2.], [2., 3.],
+                  [8., 7.], [8., 8.], [25., 80.]], dtype=np.float32)
+    
+    set_config(target_offload="gpu") # set it globally
+    clustering = DBSCAN(eps=3, min_samples=2).fit(X)
+    set_config(target_offload="auto") # restore it back
+
+API Reference
+=============
+
+Note that all of the options accepted by these functions in |sklearn| are also accepted
+here - these just list the additional options offered by the |sklearnex|.
+
+.. autofunction:: sklearnex.config_context
+
+.. autofunction:: sklearnex.get_config
+
+.. autofunction:: sklearnex.set_config

doc/sources/distributed-mode.rst

@@ -85,7 +85,7 @@ data on device without this may lead to a runtime error): ::
     export I_MPI_OFFLOAD=1
 
 SMPD-aware versions of estimators can be imported from the ``sklearnex.spmd`` module. Data should be distributed across multiple nodes as
-desired, and should be transferred to a |dpctl| or `dpnp <https://github.com/IntelPython/dpnp>`__ array before being passed to the estimator.
+desired, and should be transferred to a |dpnp_array| before being passed to the estimator.
 
 Note that SPMD estimators allow an additional argument ``queue`` in their ``.fit`` / ``.predict`` methods, which accept :obj:`dpctl.SyclQueue` objects. For example, while the signature for :obj:`sklearn.linear_model.LinearRegression.predict` would be
 

doc/sources/index.rst

@@ -41,16 +41,16 @@ These performance charts use benchmarks that you can find in the `scikit-learn b
 
 
 Supported Algorithms
----------------------
+--------------------
 
 See all of the :ref:`sklearn_algorithms`.
 
 
 Optimizations
-----------------------------------
+-------------
 
 Enable CPU Optimizations
-*********************************
+************************
 
 .. tabs::
    .. tab:: By patching
@@ -78,7 +78,7 @@ Enable CPU Optimizations
 
 
 Enable GPU optimizations
-*********************************
+************************
 
 Note: executing on GPU has `additional system software requirements <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/intel-oneapi-dpcpp-system-requirements.html>`__ - see :doc:`oneapi-gpu`.
 
@@ -168,14 +168,15 @@ See :ref:`oneapi_gpu` for other ways of executing on GPU.
 
    algorithms.rst
    oneapi-gpu.rst
+   config-contexts.rst
+   array_api.rst
    distributed-mode.rst
    distributed_daal4py.rst
    non-scikit-algorithms.rst
    non_sklearn_d4p.rst
    model_builders.rst
    logistic_model_builder.rst
    input-types.rst
-   array_api.rst
    verbose.rst
    preview.rst
    deprecation.rst

doc/sources/input-types.rst

@@ -29,10 +29,7 @@ and work with different classes of input data, including:
 - SciPy :external+scipy:doc:`sparse arrays and sparse matrices <tutorial/sparse>` (depending on the estimator).
 - Pandas :external+pandas:doc:`DataFrame and Series <user_guide/dsintro>` classes.
 
-In addition, |sklearnex| also supports:
-
-- :external+dpnp:doc:`dpnp.ndarray <reference/ndarray>`.
-- :external+dpctl:doc:`dpctl.tensor <api_reference/dpctl/tensor>`.
+In addition, |sklearnex| also supports |dpnp_array| arrays, which are particularly useful for GPU computations.
 
 Stock Scikit-Learn estimators, depending on the version, might offer support for additional
 input types beyond this list, such as ``DataFrame`` and ``Series`` classes from other libraries
@@ -50,8 +47,9 @@ enabled the input is unsupported).
   The affected cases are listed below.
 
   - Non-contiguous NumPy array - i.e. where strides are wider than one element across both rows and columns
-  - For SciPy CSR matrix / array, index arrays are always copied.
+  - For SciPy CSR matrix / array, index arrays are always copied. Note that sparse matrices in formats other than CSR
+    will be converted to CSR, which implies more than just data copying.
   - Heterogeneous NumPy array
-  - If SYCL queue is provided for device without ``float64`` support but data are ``float64``, data are copied with reduced precision.
+  - If SyCL queue is provided for device without ``float64`` support but data are ``float64``, data are copied with reduced precision.
   - If :ref:`Array API <array_api>` is not enabled then data from GPU devices are always copied to the host device and then result table 
     (for applicable methods) is copied to the source device.