Repository: scikit-learn/scikit-learn
File: examples/release_highlights/plot_release_highlights_1_8_0.py (Python)

Code before:

.. currentmodule:: sklearn

We are pleased to announce the release of scikit-learn 1.8! Many bug fixes
and improvements were added, as well as some key new features. Below we
detail the highlights of this release. **For an exhaustive list of
all the changes**, please refer to the :ref:`release notes <release_notes_1_8>`.

To install the latest version (with pip)::

    pip install --upgrade scikit-learn

or with conda::

    conda install -c conda-forge scikit-learn

"""

# %%
# Array API support
# -----------------
# The progressive adoption of the Python array API standard in SciPy and
# scikit-learn allows the user to pass input arrays from conforming
# libraries to scikit-learn estimators and functions and let them
# use those libraries and possibly non-CPU devices such as GPUs to perform
# the computation instead of attempting to convert all inputs to NumPy.
#
# In scikit-learn 1.8, several estimators and functions have been updated to
# support array API compatible inputs, for example PyTorch tensors and CuPy
# arrays.
#
# Array API support was added to the following estimators:
# :class:`preprocessing.StandardScaler`, :class:`preprocessing.PolynomialFeatures`,
# :class:`linear_model.RidgeCV`, :class:`mixture.GaussianMixture` and
# :class:`calibration.CalibratedClassifierCV`.
#
# Array API support was also added to several metrics in :mod:`sklearn.metrics`
# module, see :ref:`array_api_supported` for more details.
#
# Please refer the :ref:`array API support<array_api>` page for instructions
# to use scikit-learn with array API compatible libraries such as PyTorch or CuPy.
# Note that array API support is still experimental and must be
# explicitly be enabled both in SciPy and scikit-learn to work properly.
#
# TODO do we want to write a snippet?
# - which estimators would we feature?
# - we don't have PyTorch in doc build for now ...
# - we don't have GPU in the doc build but we could show a snippet with numpy
#   and commented out code to switch to PyToch on GPU
# - alternative: show only highlighted code without executing it?
# - alternative: add link to Colab notebook?

Review comment (performance):
I was thinking that a naive user will not know what the array API is, so using concrete library names that they recognise is better. The downside is that it might create the impression that those are the only supported ones :-/ However that is maybe not such a big problem given that we mostly focus on these (dask isn't there yet, jax needs more work).

The other dilemma is that I think keeping the text here short is good, which increases the chances of people reading it. But this also means that more people will read this and leave with half an impression because they don't read anything else. If we make this bit more extensive covering ifs and buts we get a more complete picture across but less people will read it :-/

This is my best effort at a compromise between shorter/all not 100% needed words removed and conveying a complete picture. WDYT?

```suggestion
# The progressive adoption of the Python array API standard in 
# scikit-learn means that PyTorch and CuPy input arrays
# are used directly. This means that in scikit-learn estimators
# and functions non-CPU devices, such as GPUs, can be used
# to perform the computation. As a result performance is improved
# and integration with these libraries is easier.
```

Code after:

.. currentmodule:: sklearn

We are pleased to announce the release of scikit-learn 1.8! Many bug fixes
and improvements were added, as well as some key new features. Below we
detail the highlights of this release. **For an exhaustive list of
all the changes**, please refer to the :ref:`release notes <release_notes_1_8>`.

To install the latest version (with pip)::

    pip install --upgrade scikit-learn

or with conda::

    conda install -c conda-forge scikit-learn

"""

# %%
# Array API support (enables GPU computations)
# --------------------------------------------
# The progressive adoption of the Python array API standard in
# scikit-learn means that PyTorch and CuPy input arrays
# are used directly. This means that in scikit-learn estimators
# and functions non-CPU devices, such as GPUs, can be used
# to perform the computation. As a result performance is improved
# and integration with these libraries is easier.
#
# In scikit-learn 1.8, several estimators and functions have been updated to
# support array API compatible inputs, for example PyTorch tensors and CuPy
# arrays.
#
# Array API support was added to the following estimators:
# :class:`preprocessing.StandardScaler`,
# :class:`preprocessing.PolynomialFeatures`, :class:`linear_model.RidgeCV`,
# :class:`linear_model.RidgeClassifierCV`, :class:`mixture.GaussianMixture` and
# :class:`calibration.CalibratedClassifierCV`.
#
# Array API support was also added to several metrics in :mod:`sklearn.metrics`
# module, see :ref:`array_api_supported` for more details.
#
# Please refer to the :ref:`array API support<array_api>` page for instructions
# to use scikit-learn with array API compatible libraries such as PyTorch or CuPy.
# Note: Array API support is experimental and must be explicitly enabled both
# in SciPy and scikit-learn.
#
# Here is an excerpt of using a feature engineering preprocessor on the CPU,
# followed by :class:`calibration.CalibratedClassifierCV`
# and :class:`linear_model.RidgeCV` together on a GPU with the help of PyTorch:
#
# .. code-block:: python