DOC: Note few global global options we currently have in refdocs

These are options that are controlled typically through environment
variable at startup or compile time.

2 files changed, 86 insertions, 0 deletions

diff --git a/doc/source/reference/global_state.rst b/doc/source/reference/global_state.rst
new file mode 100644
index 000000000..ac6787b7f
--- /dev/null
+++ b/doc/source/reference/global_state.rst
@@ -0,0 +1,85 @@
+.. _globale_state:
+
+************
+Global State
+************
+
+NumPy has a few startup time, compile, or runtime options
+which change the global behaviour.
+Most of these are related to performance or for debugging
+purposes and will not be interesting to the vast majority
+of users.
+
+
+Performance Related Options
+===========================
+
+Number of Threads used for Linear Algebra
+-----------------------------------------
+
+NumPy itself is normally intentionally limited to a single thread
+during function calls, however it does support multiple python
+threads running at the same time.
+Note that for performant linear algebra NumPy uses a BLAS backend
+such as OpenBLAS or MKL, which may use multiple threads that may
+be controlled by environment variables such as ``OMP_NUM_THREADS``
+depending on what is used.
+One way to control the number of threads is the package
+`threadpoolctl <https://pypi.org/project/threadpoolctl/>`_
+
+
+Madvise Hugepage on Linux
+-------------------------
+
+When working with very large arrays on modern Linux kernels,
+you can experience a significant speedup when transparent
+hugepage is enabled.
+This may always be the case or may use ``madvise`` option as
+seen by::
+
+    cat /sys/kernel/mm/transparent_hugepage/enabled
+
+on most kernels.  When set to ``madvise`` NumPy will typically
+use enable hugepages for a performance boost. This behaviour can
+be set through the environment variable::
+
+    NUMPY_MADVISE_HUGEPAGE=0
+
+or ``1`` for enabling it. When not set, the default is to use
+madvise on Kernels 4.6 and newer. These kernels presumably
+experience a large speedup when set.
+This flag is checked at import time.
+
+
+Interpoerabilty
+===============
+
+The array function protocol which allows array-like objects to
+hook into the NumPy API is currently enabled by default.
+It can be disabled using::
+
+    NUMPY_EXPERIMENTAL_ARRAY_FUNCTION=0
+
+See also `class.__array_function__` for more information.
+This flag is checked at import time.
+
+
+Debugging
+=========
+
+Relaxed Strides Checking
+------------------------
+
+The *compile* time environment variables::
+
+    NPY_RELAXED_STRIDES_DEBUG=0
+    NPY_RELAXED_STRIDES_CHECKING=1
+
+control how NumPy reports contiguity for arrays.
+The default that it is enabled and the debug mode is disabled.
+This setting should always be enabled. Setting the
+debug option can be interesting for testing code written
+in C which iterates through arrays that may or may not be
+contiguous in memory.
+Most users will have no reason to change these, for details
+please see the `memory layout <memory-layout>`_ documentation.
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
index 6742d605a..3b79fc459 100644
--- a/doc/source/reference/index.rst
+++ b/doc/source/reference/index.rst
@@ -22,6 +22,7 @@ For learning how to use NumPy, see also :ref:`user`.
    constants
    ufuncs
    routines
+   global_state
    distutils
    distutils_guide
    c-api/index