# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.3 `omp` Chapter.
``omp`` - OpenMP Utilities
This module contains utilities for controlling the OpenMP environment for your program.
They are based on OpenMP runtime library routines, although their functionality varies slightly.
Functionality Index
-------------------
Active parallel region test: :meth:`in_parallel`
**Number of OpenMP Threads**
get upper bound for next parallel region: :meth:`get_max_threads`
in current team: :meth:`get_num_threads`
set for next parallel region: :meth:`set_num_threads`
**OpenMP Active Levels of Parallelism**
get number of active levels allowed: :meth:`get_max_active_levels`
set number of active levels: :meth:`set_max_active_levels`
Threaded library test: :meth:`using_threaded_impl`
Thread number: :meth:`get_thread_num`
For full information please refer to the NAG Library document
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html
"""
# NAG Copyright 2017-2023.
[docs]def set_num_threads(num):
r"""
``set_num_threads`` sets the number of threads requested for subsequent OpenMP parallel regions.
.. _x06aa-py2-py-doc:
For full information please refer to the NAG Library document for x06aa
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06aaf.html
.. _x06aa-py2-py-parameters:
**Parameters**
**num** : int
The number of threads requested for subsequent OpenMP parallel regions.
.. _x06aa-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{num} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{num}\geq 1`.
.. _x06aa-py2-py-notes:
**Notes**
``set_num_threads``, for multithreaded implementations, sets the number of threads to be requested for subsequent parallel regions to :math:`\mathrm{num}`. The first element of the list held by the OpenMP Internal Control Variable (ICV) used in determining the number of threads is set.
The number of threads used in parallel regions will be equal to, or less than, the value of the ICV.
The actual number of threads used is dependent on several factors, such as the presence of a ``num_threads`` clause on the ``parallel`` directive or the number of threads already in use by the program.
Please refer to :ref:`References <x06aa-py2-py-references>` for a full description of how the number of threads is chosen for a particular parallel region.
In serial implementations of the NAG Library this function has no effect. See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06aa-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def get_num_threads():
r"""
``get_num_threads`` returns the number of OpenMP threads in the current team.
.. _x06ab-py2-py-doc:
For full information please refer to the NAG Library document for x06ab
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06abf.html
**Returns**
**nt** : int
The returned number of OpenMP threads in the current team.
.. _x06ab-py2-py-notes:
**Notes**
``get_num_threads``, for multithreaded implementations, returns the number of OpenMP threads in the current team.
If the number of threads is deemed critical then you are advised to use ``get_num_threads`` to retrieve this value as it may be less than that requested with either a call to :meth:`set_num_threads`, your OMP_NUM_THREADS environment variable value or by using a ``num_threads`` clause on an OpenMP ``parallel`` directive.
The number of threads actually in use in a parallel region is dependent on several factors.
Please refer to :ref:`References <x06ab-py2-py-references>` for a full description of how the number of threads is chosen for a particular parallel region.
If this function is called from a sequential part of a multithreaded program then it will return the value :math:`1`.
In serial implementations of the NAG Library this function will always return :math:`1`.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06ab-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def get_max_threads():
r"""
``get_max_threads`` returns an upper bound on the number of threads used for subsequent OpenMP parallel regions.
.. _x06ac-py2-py-doc:
For full information please refer to the NAG Library document for x06ac
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06acf.html
**Returns**
**ntmax** : int
The returned upper bound on the number of threads used for subsequent OpenMP parallel regions.
.. _x06ac-py2-py-notes:
**Notes**
``get_max_threads``, for multithreaded implementations, returns the number of the threads to be requested for subsequent parallel regions. The value is the first element of the list held by the OpenMP Internal Control Variable (ICV) used in determining the number of threads.
The number of threads used in parallel regions will be equal to, or less than, the first value of the ICV.
The actual number of threads used is dependent on several factors, such as the presence of a ``num_threads`` clause on the ``parallel`` directive or the number of threads already in use by the program.
Please refer to :ref:`References <x06ac-py2-py-references>` for a full description of how the number of threads is chosen for a particular parallel region.
In serial implementations of the NAG Library this function will always return :math:`1`. See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06ac-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def get_thread_num():
r"""
``get_thread_num`` returns the OpenMP thread number of the calling thread.
.. _x06ad-py2-py-doc:
For full information please refer to the NAG Library document for x06ad
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06adf.html
**Returns**
**tn** : int
The returned OpenMP thread number of the calling thread.
.. _x06ad-py2-py-notes:
**Notes**
``get_thread_num``, for multithreaded implementations, returns the calling OpenMP thread's unique thread number within the current team.
The master thread will always return :math:`0`.
The remaining threads will return a value between :math:`1` and the value returned by :meth:`get_num_threads` less :math:`1`.
If this function is called from a sequential part of a multithreaded program then it will return the value :math:`0`.
In serial implementations of the NAG Library this function will always return :math:`0`.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06ad-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def in_parallel():
r"""
``in_parallel`` returns :math:`\mathbf{True}` if called from within an active OpenMP parallel region, and :math:`\mathbf{False}` otherwise.
.. _x06af-py2-py-doc:
For full information please refer to the NAG Library document for x06af
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06aff.html
**Returns**
**inpar** : bool
:math:`\mathbf{True}` if called from within an active OpenMP parallel region, and :math:`\mathbf{False}` otherwise.
.. _x06af-py2-py-notes:
**Notes**
``in_parallel``, for multithreaded implementations, returns :math:`\mathbf{True}` if called from within an active OpenMP parallel region, and :math:`\mathbf{False}` otherwise.
In serial implementations of the NAG Library this function will always return :math:`\mathbf{False}`.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06af-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def set_nested(nesting):
r"""
``set_nested`` enables or disables nested OpenMP parallelism.
.. deprecated:: 28.3.0.0
``set_nested`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`set_max_active_levels` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _x06ag-py2-py-doc:
For full information please refer to the NAG Library document for x06ag
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06agf.html
.. _x06ag-py2-py-parameters:
**Parameters**
**nesting** : int
If :math:`\mathrm{nesting} = 0`, nesting of OpenMP parallel regions is disabled, otherwise it is enabled.
.. _x06ag-py2-py-notes:
**Notes**
``set_nested``, for multithreaded implementations, enables or disables the nesting of OpenMP parallel regions by setting an OpenMP Internal Control Variable (ICV) and any vendor library specific options where that is possible.
Nesting is disabled by default in OpenMP.
In serial implementations of the NAG Library ``set_nested`` has no effect.
See the submodule ``omp`` for a discussion of the behaviour of these functions when called in serial.
.. _x06ag-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def get_nested():
r"""
``get_nested`` returns :math:`\mathbf{True}` if nested OpenMP parallelism has been enabled, and :math:`\mathbf{False}` otherwise.
.. deprecated:: 28.3.0.0
``get_nested`` will be removed in naginterfaces 31.3.0.0.
Please use :meth:`get_max_active_levels` instead.
See also the :ref:`Replacement Calls <replace>` document.
.. _x06ah-py2-py-doc:
For full information please refer to the NAG Library document for x06ah
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06ahf.html
**Returns**
**nesting** : bool
:math:`\mathbf{True}` if nested OpenMP parallelism has been enabled, and :math:`\mathbf{False}` otherwise.
.. _x06ah-py2-py-notes:
**Notes**
``get_nested``, for multithreaded implementations, tests whether the nesting of OpenMP parallel regions has been enabled as if with a call to :meth:`set_nested`.
The return value will be :math:`\mathbf{True}` if nesting is enabled or :math:`\mathbf{False}` if it is disabled.
In serial implementations of the NAG Library ``get_nested`` will always return :math:`\mathbf{False}`.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06ah-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def set_max_active_levels(num):
r"""
``set_max_active_levels`` sets the number of nested active parallel regions.
.. _x06aj-py2-py-doc:
For full information please refer to the NAG Library document for x06aj
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06ajf.html
.. _x06aj-py2-py-parameters:
**Parameters**
**num** : int
:math:`n`, the number of active parallel regions allowed.
If :math:`\mathrm{num} = 0`
parallelism is disabled.
If :math:`\mathrm{num} = 1`
the outermost parallel region is active and nested regions are inactive (i.e., no new threads are created when entering the nested parallel region and it is executed in serial.)
If :math:`\mathrm{num} \geq 2`
:math:`\mathrm{num}` parallel regions can be active and :math:`\mathrm{num}-1` nested regions can be active.
.. _x06aj-py2-py-errors:
**Raises**
**NagValueError**
(`errno` :math:`1`)
On entry, :math:`\mathrm{num} = \langle\mathit{\boldsymbol{value}}\rangle`.
Constraint: :math:`\mathrm{num}\geq 0`.
.. _x06aj-py2-py-notes:
**Notes**
``set_max_active_levels``, for multithreaded implementations, sets the maximum number of nested active parallel regions to :math:`\mathrm{num}`.
When :math:`\mathrm{num}` is set to zero parallelism is disabled, if set to one then only the outermost parallel region is active and nested regions are inactive (i.e., no new threads are created when entering the nested parallel region and it is executed in serial.) If :math:`\mathrm{num}` is set to :math:`n`, where :math:`n\geq 2` then :math:`n` parallel regions can be active and :math:`n-1` nested regions can be active.
In serial implementations of the NAG Library this function has no effect.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06aj-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def get_max_active_levels():
r"""
``get_max_active_levels`` returns the maximum number of nested active parallel regions allowed.
.. _x06ak-py2-py-doc:
For full information please refer to the NAG Library document for x06ak
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06akf.html
**Returns**
**nl** : int
The returned maximum number of active nested parallel regions allowed.
.. _x06ak-py2-py-notes:
**Notes**
``get_max_active_levels``, for multithreaded implementations, retrieves the maximum number of nested active parallel regions allowed.
This has either been set by the user or is the default for the implementation of OpenMP being used.
In serial implementations of the NAG Library this function will always return :math:`0`.
See `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__ for a discussion of the behaviour of these functions when called in serial.
.. _x06ak-py2-py-references:
**References**
The OpenMP API Specification for Parallel Programming
Chapman, B, Jost, G and van der Pas, R, 2008, `Using OpenMP Portable Shared Memory Parallel Programming`, The MIT Press
"""
raise NotImplementedError
[docs]def using_threaded_impl():
r"""
``using_threaded_impl`` returns :math:`\mathbf{True}` when using a multithreaded implementation of the NAG Library and :math:`\mathbf{False}` otherwise.
.. _x06xa-py2-py-doc:
For full information please refer to the NAG Library document for x06xa
https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06xaf.html
**Returns**
**smplib** : bool
:math:`\mathbf{True}` if using a multithreaded implementation of the NAG Library and :math:`\mathbf{False}` otherwise.
.. _x06xa-py2-py-notes:
**Notes**
``using_threaded_impl`` can be used to determine whether you are using a serial or multithreaded implementation of the NAG Library.
In particular, with this information the behaviour of the other routines in this module can be predicted, as described in `the X06 Introduction <https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/x06/x06intro.html>`__.
The function returns :math:`\mathbf{True}` when a multithreaded implementation of the NAG Library is being used and :math:`\mathbf{False}` if a serial implementation is being used.
"""
raise NotImplementedError
