Add supported CPU/GPU operators to API docs and update docstrings (#5239

)

This PR:
- Adds a section to the `Module Configuration` section of the API documentation (next to the section on Verbosity Levels). As device selection capabilities can be configured, this feels like a reasonable location
- Updates the relevant estimator docstrings with a reference to device selection (always at the bottom of the "Extended Summary" section, based on recommendations in the numpydoc [Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html#sections)) and a link to the documentation to learn more. 

This closes #5143 and closes #5144

This is a replacement for #5150

Authors:
  - Nick Becker (https://github.com/beckernick)

Approvers:
  - Dante Gama Dessavre (https://github.com/dantegd)

URL: #5239

docs/source/api.rst

@@ -18,6 +18,62 @@ Output Data Type Configuration
  .. autofunction:: cuml.internals.memory_utils.set_global_output_type
  .. autofunction:: cuml.internals.memory_utils.using_output_type
 
+.. _device-selection:
+
+CPU / GPU Device Selection (Experimental)
+-----------------------------------------
+cuML provides experimental support for running selected estimators and operators on either the GPU or CPU. This document covers the set of operators for which CPU/GPU device selection capabilities are supported as of the current nightly packages. If an operator isn't listed here, it can only be run on the GPU. Prior versions of cuML may have reduced support compared to the following table.
+
+.. list-table:: Operators Supporting CPU/GPU Device Selection and Execution
+   :header-rows: 1
+   :align: center
+   :widths: auto
+
+   * - Category
+     - Operator
+   * - Clustering
+     - HDBSCAN
+   * - Dimensionality Reduction and Manifold Learning
+     - PCA
+   * - Dimensionality Reduction and Manifold Learning
+     - TruncatedSVD
+   * - Dimensionality Reduction and Manifold Learning
+     - UMAP
+   * - Neighbors
+     - NearestNeighbors
+   * - Regression and Classification
+     - ElasticNet
+   * - Regression and Classification
+     - Lasso
+   * - Regression and Classification
+     - LinearRegression
+   * - Regression and Classification
+     - LogisticRegression
+   * - Regression and Classification
+     - Ridge
+
+If a CUDA-enabled GPU is available on the system, cuML will default to using it. Users can configure CPU or GPU execution for supported operators via context managers or global configuration. 
+
+.. code-block:: python
+
+   from cuml.linear_model import Lasso
+   from cuml.common.device_selection import using_device_type, set_global_device_type
+
+   with using_device_type("CPU"): # Alternatively, using_device_type("GPU")
+       model = Lasso()
+       model.fit(X_train, y_train)
+       predictions = model.predict(X_test)
+
+   # All operators supporting CPU execution will run on the CPU after this configuration
+   set_global_device_type("CPU")
+
+   model = Lasso()
+   model.fit(X_train, y_train)
+   predictions = model.predict(X_test)
+
+For more detailed examples, please see the `Execution Device Interoperability Notebook
+<execution_device_interoperability.ipynb>`_ in the User Guide.
+
 .. _verbosity-levels:
 
 Verbosity Levels

python/cuml/cluster/hdbscan/hdbscan.pyx

@@ -341,6 +341,10 @@ class HDBSCAN(UniversalBase, ClusterMixin, CMajorInputTagMixin):
     (and often will) lead to some points being assigned different
     cluster labels between the two implementations.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Parameters
     ----------
     handle : cuml.Handle

python/cuml/decomposition/pca.pyx

@@ -131,6 +131,10 @@ class PCA(UniversalBase,
     as it iteratively tries to correct the top K eigenvectors, but might be
     less accurate.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Examples
     --------
 

python/cuml/decomposition/tsvd.pyx

@@ -117,6 +117,10 @@ class TruncatedSVD(UniversalBase,
     faster as it iteratively tries to correct the top K singular vectors, but
     might be less accurate.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Examples
     --------
 

python/cuml/linear_model/lasso.py

@@ -31,6 +31,10 @@ class Lasso(ElasticNet):
     compliant), in addition to cuDF objects. It uses coordinate descent to fit
     a linear model.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Examples
     --------
 

python/cuml/linear_model/linear_regression.pyx

@@ -143,6 +143,10 @@ class LinearRegression(LinearPredictMixin,
     and provides 2 algorithms SVD and Eig to fit a linear model. SVD is more
     stable, but Eig (default) is much faster.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Examples
     --------
 

python/cuml/linear_model/logistic_regression.pyx

@@ -67,6 +67,10 @@ class LogisticRegression(UniversalBase,
 
     Note that, just like in Scikit-learn, the bias will not be regularized.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Examples
     --------
 

python/cuml/manifold/umap.pyx

@@ -144,6 +144,10 @@ class UMAP(UniversalBase,
     The UMAP algorithm is outlined in [1]. This implementation follows the
     GPU-accelerated version as described in [2].
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Parameters
     ----------
     n_neighbors: float (optional, default 15)

python/cuml/neighbors/nearest_neighbors.pyx

@@ -161,6 +161,10 @@ class NearestNeighbors(UniversalBase,
     datapoints. Currently, cuML supports k-NN queries, which define
     the neighborhood as the closest `k` neighbors to each query point.
 
+    This estimator supports cuML's experimental device selection capabilities.
+    It can be configured to run on either the CPU or the GPU.
+    To learn more, please see :ref:`device-selection`.
+
     Parameters
     ----------
     n_neighbors : int (default=5)