Skip to content

n_jobs support details in docs #2453

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

n_jobs support details in docs #2453

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eca279b
`n_jobs` support details in docs
Alexsandruss Apr 25, 2025
c11fcfe
Fixes for doc page
Alexsandruss Apr 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/sources/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
46 changes: 46 additions & 0 deletions doc/sources/parallelism.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
.. Copyright 2025 Intel Corporation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're using a different copyright header now: https://github.com/uxlfoundation/oneDAL/blob/main/CONTRIBUTING.md#license-and-copyright

..
.. 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
.. _parallelism:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This named reference doesn't appear to be used.


#####################
Parallelism Specifics
#####################
Comment on lines +18 to +20
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#####################
Parallelism Specifics
#####################
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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another very important difference not listed here: sklearn defaults to 1 thread, while sklearnex defaults to all threads.

Comment on lines +22 to +23
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
|sklearnex| supports the `n_jobs <https://scikit-learn.org/stable/glossary.html#term-n_jobs>`_ parameter
of the original |sklearn| with the following differences:
|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|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it the case that it always sets the number of threads, or does it set the maximum number of threads and then lets oneDAL make further adjustments? (e.g. dropping low-power E-cores)

* |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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also multi-threading from the MKL side.

* The `threading` parallel backend of `joblib` is not supported by |sklearnex|
Comment on lines +25 to +30
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* `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|
* `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|.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean "not supported by sklearnex"? What happens for example if you run an sklearn metaestimator (like BaggingClassifier) using that joblib backend with an sklearnex estimator inside?


The only exception is multiclass LogisticRegression, which uses `joblib` for parallelism across classes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The only exception is multiclass LogisticRegression, which uses `joblib` for parallelism across classes.
The only exception is multiclass LogisticRegression, which uses :external+joblib:doc:`joblib <index>` for parallelism across classes.

(perhaps it could be added in the substitutions list)


|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>`_.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`the calculation of the 'n_jobs' parameter value <https://scikit-learn.org/stable/glossary.html#term-n_jobs>`_.
`the calculation of the 'n_jobs' parameter value <https://scikit-learn.org/stable/glossary.html#term-n_jobs>`__.

Link is repeated, single underscore makes it a named reference, which can cause with repetitions that change the name.


When Scikit-learn's utilities with built-in parallelism are used (for example, `GridSearchCV` or `VotingClassifier`),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When Scikit-learn's utilities with built-in parallelism are used (for example, `GridSearchCV` or `VotingClassifier`),
When Scikit-learn's utilities with built-in parallelism are used (for example, :obj:`sklearn.model_selection.GridSearchCV` or :obj:`sklearn.model_selection.VotingClassifier`),

|sklearnex| tries to determine the optimal number of threads per job using hints provided by `joblib`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't aware that such a system existed. Could you provide a link to the code where this happens?

If `n_jobs` is not specified for underlying estimator(s), |sklearnex| sets it to the number of available threads
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If `n_jobs` is not specified for underlying estimator(s), |sklearnex| sets it to the number of available threads
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|.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here it could clarify that it happens only when joblib is used, which per the paragraphs above, is usually not the case in sklearnex.


To track the actual number of threads used by sklearnex's estimators,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's also the MKL debug variable, and now the oneDAL debug variable.

set the `DEBUG` :ref:`verbosity setting <verbose>`.
Loading