diff --git a/doc/sources/index.rst b/doc/sources/index.rst index 4808070960..4663cd1d5b 100755 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -109,6 +109,7 @@ Enable Intel(R) GPU optimizations input-types.rst array_api.rst verbose.rst + preview.rst deprecation.rst diff --git a/doc/sources/preview.rst b/doc/sources/preview.rst new file mode 100644 index 0000000000..bc97d5c270 --- /dev/null +++ b/doc/sources/preview.rst @@ -0,0 +1,76 @@ +.. ****************************************************************************** +.. * Copyright 2024 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. +.. *******************************************************************************/ + +.. _preview: + +##################### +Preview Functionality +##################### + +Some of implemented functionality in |intelex| doesn't meet one or few of next requirements +for being enabled by default for all users: + +* The functionality API is not stable and can be changed in future +* The functionality doesn't have full compatibility with stock Scikit-learn +* The functionality misses performance targets compared to stock Scikit-learn or previously available version of functionality +* The functionality is not fully tested + +This type of functionality is available under **preview mode** of |intelex| and located in +the corresponding module (`sklearnex.preview`). + +Preview functionality *may* or *may not* participate in patching of Scikit-learn. +For example, a preview estimator may be a replacement for a stock one or a completely new one. + +To enable preview functionality, you need to set the `SKLEARNEX_PREVIEW` environment variable +to non-empty value before patching of Scikit-learn. +For example, you can set the environment variable in the following way: + +- On Linux* OS :: + + export SKLEARNEX_PREVIEW=1 + +- On Windows* OS :: + + set SKLEARNEX_PREVIEW=1 + +Then, you can import Scikit-learn estimator patched with a preview one from `sklearnex.preview` module:: + + from sklearnex import patch_sklearn + patch_sklearn() + from sklearn.linear_model import Ridge + print(Ridge.__module__) + # output: + # sklearnex.preview.linear_model.ridge + +Current list of preview estimators: + +.. list-table:: + :widths: 30 20 10 + :header-rows: 1 + :align: left + + * - Estimator name + - Module + - Is patching supported + * - EmpiricalCovariance + - sklearnex.preview.covariance + - Yes + * - IncrementalPCA + - sklearnex.preview.decomposition + - Yes + * - Ridge + - sklearnex.preview.linear_model + - Yes