From eca279b7af838c12ddf2a7796bd02259f72c6c5f Mon Sep 17 00:00:00 2001
From: Alexander Andreev <alexander.andreev@intel.com>
Date: Fri, 25 Apr 2025 17:13:45 +0100
Subject: [PATCH 1/2] `n_jobs` support details in docs

---
 doc/sources/index.rst       |  1 +
 doc/sources/parallelism.rst | 45 +++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 doc/sources/parallelism.rst

diff --git a/doc/sources/index.rst b/doc/sources/index.rst
index b0bd8a7c5e..1ba22770ac 100755
--- a/doc/sources/index.rst
+++ b/doc/sources/index.rst
@@ -169,6 +169,7 @@ See :ref:`oneapi_gpu` for other ways of executing on GPU.
    input-types.rst
    array_api.rst
    verbose.rst
+   parallelism.rst
    preview.rst
    deprecation.rst
 
diff --git a/doc/sources/parallelism.rst b/doc/sources/parallelism.rst
new file mode 100644
index 0000000000..6ed43e27f8
--- /dev/null
+++ b/doc/sources/parallelism.rst
@@ -0,0 +1,45 @@
+.. Copyright 2025 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.
+
+.. _parallelism:
+
+#####################
+Parallelism Specifics
+#####################
+
+|sklearnex| supports the `n_jobs <https://scikit-learn.org/stable/glossary.html#term-n_jobs>`_ parameter
+of the original |sklearn| with the following differences:
+
+* `n_jobs` parameter is supported for all estimators patched by |sklearnex|,
+  while |sklearn| enables it for selected estimators only
+* `n_jobs` estimator parameter sets the number of threads used by the underlying |oneDAL|
+* |sklearnex| doesn't use `joblib` for parallelism in patched estimators and functions
+* The only low-level parallelism library used by |sklearnex| is oneTBB (through oneDAL)
+* The `threading` parallel backend of `joblib` is not supported by |sklearnex|
+
+The only exception is multiclass LogisticRegression, which uses `joblib` for parallelism across classes.
+
+|sklearnex| follows the same rules as |sklearn| for
+`the calculation of the 'n_jobs' parameter value <https://scikit-learn.org/stable/glossary.html#term-n_jobs>`_.
+
+When Scikit-learn's utilities with built-in parallelism are used (for example, `GridSearchCV` or `VotingClassifier`),
+|sklearnex| tries to determine the optimal number of threads per job using hints provided by `joblib`.
+If `n_jobs` is not specified for underlying estimator(s), |sklearnex| sets it to the number of available threads
+(usually the number of logical CPUs divided by `n_jobs` set for higher-level parallelized entities).
+
+Environment variables such as `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OPENBLAS_NUM_THREADS`, and others used by
+low-level parallelism libraries are recognized by `joblib` and therefore can be used as hints by |sklearnex|.
+
+To track the actual number of threads used by sklearnex's estimators,
+set the `DEBUG` :ref:`verbosity setting <_verbose>`.

From c11fcfee7cccd04a8fdefa673b536d5eecfaaa51 Mon Sep 17 00:00:00 2001
From: Alexander Andreev <alexander.andreev@intel.com>
Date: Fri, 25 Apr 2025 17:45:45 +0100
Subject: [PATCH 2/2] Fixes for doc page

---
 doc/sources/parallelism.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/sources/parallelism.rst b/doc/sources/parallelism.rst
index 6ed43e27f8..5e5ee8ab02 100644
--- a/doc/sources/parallelism.rst
+++ b/doc/sources/parallelism.rst
@@ -12,6 +12,7 @@
 .. See the License for the specific language governing permissions and
 .. limitations under the License.
 
+.. include:: substitutions.rst
 .. _parallelism:
 
 #####################
@@ -42,4 +43,4 @@ Environment variables such as `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `OPENBLAS_NU
 low-level parallelism libraries are recognized by `joblib` and therefore can be used as hints by |sklearnex|.
 
 To track the actual number of threads used by sklearnex's estimators,
-set the `DEBUG` :ref:`verbosity setting <_verbose>`.
+set the `DEBUG` :ref:`verbosity setting <verbose>`.