# Source code for naginterfaces.library.omp

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 28.5 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

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_28.5/flhtml/x06/x06intro.html
"""

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_28.5/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_28.5/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

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_28.5/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_28.5/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

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_28.5/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_28.5/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

r"""
get_thread_num returns the OpenMP thread number of the calling thread.

For full information please refer to the NAG Library document for x06ad

**Returns**
**tn** : int

**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_28.5/flhtml/x06/x06intro.html>__ for a discussion of the behaviour of these functions when called in serial.

**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_28.5/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_28.5/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_28.5/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_28.5/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_28.5/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_28.5/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_28.5/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_28.5/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_28.5/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

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_28.5/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_28.5/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