sagemathgh-37575: Intersphinx for cvxopt, cvxpy, cypari2, cysignals, …

…flint, fpylll, gmpy2, ipywidgets, matplotlib, mpmath, networkx, numpy, rpy2, scipy, sympy

    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes sagemath#12345". -->

[Intersphinx](https://www.sphinx-
doc.org/en/master/usage/extensions/intersphinx.html) allows us to refer
to functions and classes in other projects using the standard Sphinx
roles `:func:`,  `:class:`, ...

Examples in the documentation preview:
- [References to FLINT functions in
sage.libs.flint.arith_sage](https://deploy-preview-37575--sagemath.netli
fy.app/html/en/reference/libs/sage/libs/flint/arith_sage#sage.libs.flint
.arith_sage.bell_number)
- [References to SciPy functions in
sage.manifolds.differentiable.integrated_curve](https://deploy-
preview-37575--sagemath.netlify.app/html/en/reference/manifolds/sage/man
ifolds/differentiable/integrated_curve#sage.manifolds.differentiable.int
egrated_curve.IntegratedCurve.solve)
- [References to NetworkX functions in
sage.graphs.generic_graph](https://deploy-preview-37575--sagemath.netlif
y.app/html/en/reference/graphs/sage/graphs/generic_graph#sage.graphs.gen
eric_graph.GenericGraph.export_to_file)
- [Examples in the Developer Guide](https://deploy-preview-37575--
sagemath.netlify.app/html/en/developer/sage_manuals#hyperlinks)

Based on a rebased version of sagemath#29231 by @mwageringel. In addition to the
`scipy` intersphinx done in sagemath#29231, here we add a number of relevant
Python libraries, as well as `flint`, whose docs are built with Sphinx
as well.

To address concerns in the discussion there about the docbuild
contacting remote servers for the inventory files, here we instead
vendor the inventory files:
```
$ ls -l src/doc/common/_vendor
-rw-r--r--  1 mkoeppe  staff    1942 Mar  9 21:20 cvxopt.inv
-rw-r--r--  1 mkoeppe  staff   13251 Mar  9 21:20 cvxpy.inv
-rw-r--r--  1 mkoeppe  staff   10728 Mar  9 21:20 cypari2.inv
-rw-r--r--  1 mkoeppe  staff     775 Mar  9 21:20 cysignals.inv
-rw-r--r--  1 mkoeppe  staff  246266 Mar  9 21:20 flint.inv
-rw-r--r--  1 mkoeppe  staff    1603 Mar  9 21:20 fpylll.inv
-rw-r--r--  1 mkoeppe  staff    2891 Mar  9 21:20 gmpy2.inv
-rw-r--r--  1 mkoeppe  staff   10934 Mar  9 21:20 ipywidgets.inv
-rw-r--r--  1 mkoeppe  staff  105887 Mar  9 21:20 matplotlib.inv
-rw-r--r--  1 mkoeppe  staff    3115 Mar  9 21:20 mpmath.inv
-rw-r--r--  1 mkoeppe  staff   51830 Mar  9 21:20 networkx.inv
-rw-r--r--  1 mkoeppe  staff   78006 Mar  9 21:20 numpy.inv
-rw-r--r--  1 mkoeppe  staff    1449 Mar  9 21:20 pplpy.inv
-rw-r--r--  1 mkoeppe  staff  136166 Mar  9 21:20 python.inv
-rw-r--r--  1 mkoeppe  staff    3289 Mar  9 21:20 rpy2.inv
-rw-r--r--  1 mkoeppe  staff  112691 Mar  9 21:20 scipy.inv
-rw-r--r--  1 mkoeppe  staff   55596 Mar  9 21:20 sympy.inv
```
This extends our existing practice with the Python inventory (moved here
from its previous location `src/doc/common/python3.inv`). The new
command `sage -python -m sage_docbuild.vendor` retrieves the latest
versions of these files. (Distribution notes: These files are not
installed, as they are only needed at the build time of the
documentation. After sagemath#36730, they are part of the sdist of sagemath-doc-
html, but not part of the wheel.)

By setting `SAGE_DOC_REMOTE_INVENTORIES=yes`, this can be overridden, as
previously suggested in
sagemath#29231 (comment).
In this case it is first tried to contact the remote servers.

Fixes sagemath#29231 (stalled since 2020).
Fixes sagemath#27164 (stalled since 2019).

**Outside the scope of this PR:**
- adding such Intersphinx links everywhere (that would be a long-term
writing project - https://groups.google.com/g/sage-
devel/c/PfYpuOWt8xQ/m/Emn7pZd5AQAJ)
- linking to documentation of non-Sphinx projects (see sagemath#37598, sagemath#37577)
- any considerations how these .inv files could/should/would be taken
from our installations of these packages, or from system packages that
ship the documentation.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
    
URL: sagemath#37575
Reported by: Matthias Köppe
Reviewer(s): David Coudert, Matthias Köppe

src/doc/en/developer/sage_manuals.rst

@@ -38,7 +38,7 @@ Sage's manuals are written in `ReST <http://docutils.sourceforge.net/rst.html>`_
   ``SAGE_ROOT/src/doc/en``.
 
 - Some documents have been **translated** into other languages. In order to
-  access them, change en/ into fr/,es/, de/... See :ref:`section-manuals-names`.
+  access them, change ``en/`` into ``fr/``, ``es/``, ``de/``... See :ref:`section-manuals-names`.
 
 .. _section-manuals-edit:
 
@@ -82,9 +82,12 @@ The documentation can contain links toward modules, classes, or methods, e.g.::
     :mod:`link to a module <sage.module_name>`
     :mod:`sage.module_name` (here the link's text is the module's name)
 
-For links toward classes, methods, or function, replace **:mod:** by
-**:class:**, **:meth:** or **:func:** respectively.  See `Sphinx' documentation
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
+For links toward classes, methods, or functions, replace ``:mod:`` by
+``:class:``, ``:meth:``, or ``:func:``, respectively.  See Sphinx' documentation
+on `cross-referencing Python objects
+<https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects>`_
+and for the general syntax of
+`roles <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_.
 
 **Short links:** the link ``:func:`~sage.mod1.mod2.mod3.func1``` is equivalent
 to ``:func:`func1 <sage.mod1.mod2.mod3.func1>```: the function's name will be
@@ -94,6 +97,72 @@ used as the link name, instead of its full path.
 absolute. If you are documenting ``method_one``, you can write
 ``:meth:`method_two```.
 
+**Intersphinx references:** in the same way, you can refer to the modules, classes,
+methods, functions of the Python standard library and of several Python packages
+used by SageMath; see the `Intersphinx documentation
+<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
+for details. Likewise, you can refer to the C functions of the
+:ref:`FLINT <spkg_flint>` library; see `Sphinx' documentation on
+cross-referencing C constructs
+<https://www.sphinx-doc.org/en/master/usage/domains/c.html#cross-referencing-c-constructs>`_
+for more information.
+
+.. LIST-TABLE::
+   :widths: 4 7 5
+   :header-rows: 0
+
+   * - Python
+     - ``:exc:`ValueError```
+     - :exc:`ValueError`
+   * - :ref:`CVXOPT <spkg_cvxopt>`
+     - ``:func:`cvxopt.solvers.socp```
+     - :func:`cvxopt.solvers.socp`
+   * - :ref:`CVXpy <spkg_cvxpy>`
+     - ``:class:`~cvxpy.atoms.log_det.log_det```
+     - :class:`~cvxpy.atoms.log_det.log_det`
+   * - :ref:`cypari2 <spkg_cypari>`
+     - ``:class:`cypari2.gen.Gen```
+     - :class:`cypari2.gen.Gen`
+   * - :ref:`cysignals <spkg_cysignals>`
+     - ``:envvar:`CYSIGNALS_CRASH_DAYS```
+     - :envvar:`CYSIGNALS_CRASH_DAYS`
+   * - :ref:`FLINT <spkg_flint>`
+     - ``:c:func:`arith_bell_number```
+     - :c:func:`arith_bell_number`
+   * - :ref:`gmpy2 <spkg_gmpy2>`
+     - ``:func:`gmpy2.gamma_inc```
+     - :func:`gmpy2.gamma_inc`
+   * - :ref:`ipywidgets <spkg_ipywidgets>`
+     - ``:mod:`~ipywidgets.widgets.widget_date```
+     - :mod:`~ipywidgets.widgets.widget_date`
+   * - :ref:`Matplotlib <spkg_matplotlib>`
+     - ``:mod:`matplotlib.bezier```
+     - :mod:`matplotlib.bezier`
+   * - :ref:`mpmath <spkg_mpmath>`
+     - ``:attr:`mpmath.mp.khinchin```
+     - :attr:`mpmath.mp.khinchin`
+   * - :ref:`NetworkX <spkg_networkx>`
+     - ``:attr:`~networkx.DiGraph.out_degree```
+     - :attr:`~networkx.DiGraph.out_degree`
+   * - :ref:`NumPy <spkg_numpy>`
+     - ``:data:`numpy.NAN```
+     - :data:`numpy.NAN`
+   * - :ref:`pplpy <spkg_pplpy>`
+     - ``:mod:`ppl.polyhedron```
+     - :mod:`ppl.polyhedron`
+   * - :ref:`rpy2 <spkg_rpy2>`
+     - ``:class:`~rpy2.robjects.vectors.DataFrame```
+     - :class:`~rpy2.robjects.vectors.DataFrame`
+   * - :ref:`SciPy <spkg_scipy>`
+     - ``:data:`scipy.special.huber```
+     - :data:`scipy.special.huber`
+   * - :ref:`SymPy <spkg_sympy>`
+     - ``:class:`~sympy.diffgeom.WedgeProduct```
+     - :class:`~sympy.diffgeom.WedgeProduct`
+
+To see the available cross references in any of these libraries, you can use the command
+``./sage -python -m sphinx.ext.intersphinx src/doc/common/_vendor/numpy.inv``.
+
 **Global namespace:** if an object (e.g. ``integral``) is automatically imported
 by Sage, you can link toward it without specifying its full path:
 

src/doc/en/reference/matrices/index.rst

@@ -29,7 +29,7 @@ following additional ways to compute with matrices:
 -  The GSL C-library is included with Sage, and can be used via
    Cython.
 
--  The ``scipy`` module provides support for
+-  The :mod:`scipy:scipy` module provides support for
    *sparse* numerical linear algebra, among many other things.
 
 -  The ``numpy`` module, which you load by typing

src/sage/calculus/desolvers.py

@@ -27,8 +27,8 @@
   order equations, return list of points.
 
 - :func:`desolve_odeint` - Solve numerically a system of first-order ordinary
-  differential equations using ``odeint`` from `scipy.integrate module.
-  <https://docs.scipy.org/doc/scipy/reference/integrate.html#module-scipy.integrate>`_
+  differential equations using :func:`~scipy:scipy.integrate.odeint` from
+  the module :mod:`scipy:scipy.integrate`.
 
 - :func:`desolve_system` - Solve a system of 1st order ODEs of any size using
   Maxima. Initial conditions are optional.
@@ -1499,7 +1499,7 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=()
                    mxstep=0, mxhnil=0, mxordn=12, mxords=5, printmessg=0):
     r"""
     Solve numerically a system of first-order ordinary differential equations
-    using ``odeint`` from scipy.integrate module.
+    using :func:`scipy:scipy.integrate.odeint`.
 
     INPUT:
 
@@ -1517,8 +1517,9 @@ def desolve_odeint(des, ics, times, dvars, ivar=None, compute_jac=False, args=()
     - ``compute_jac`` -- boolean. If True, the Jacobian of ``des`` is computed and
       used during the integration of stiff systems. Default value is False.
 
-    Other Parameters (taken from the documentation of odeint function from `scipy.integrate module.
-    <https://docs.scipy.org/doc/scipy/reference/integrate.html#module-scipy.integrate>`_)
+    Other Parameters (taken from the documentation of the
+    :func:`~scipy:scipy.integrate.odeint` function from
+    :mod:`scipy:scipy.integrate`):
 
     - ``rtol``, ``atol`` : float
       The input parameters ``rtol`` and ``atol`` determine the error

src/sage/graphs/generators/families.py

@@ -513,12 +513,13 @@ def BalancedTree(r, h):
     OUTPUT:
 
     The perfectly balanced tree of height `h \geq 1` and whose root has
-    degree `r \geq 2`. A ``NetworkXError`` is returned if `r < 2` or
-    `h < 1`.
+    degree `r \geq 2`. A :exc:`~networkx.exception.NetworkXError` is raised
+    if `r < 2` or `h < 1`.
 
     ALGORITHM:
 
-    Uses `NetworkX <http://networkx.lanl.gov>`_.
+    Uses the :ref:`NetworkX <spkg_networkx>` function
+    :func:`~networkx.generators.classic.balanced_tree`.
 
     EXAMPLES:
 

src/sage/graphs/generic_graph.py

@@ -1336,9 +1336,9 @@ def export_to_file(self, filename, format=None, **kwds):
 
         - ``format`` -- string (default: ``None``); select the output format
           explicitly. If set to ``None`` (default), the format is set to be the
-          file extension of ``filename``. Admissible formats are: ``adjlist``,
-          ``dot``, ``edgelist``, ``gexf``, ``gml``, ``graphml``,
-          ``multiline_adjlist``, ``pajek``, ``yaml``.
+          file extension of ``filename``. Admissible formats are: ``'adjlist'``,
+          ``'dot'``, ``'edgelist'``, ``'gexf'``, ``'gml'``, ``'graphml'``,
+          ``'multiline_adjlist'``, ``'pajek'``.
 
         - All other arguments are forwarded to the subfunction. For more
           information, see their respective documentation:
@@ -1348,15 +1348,14 @@ def export_to_file(self, filename, format=None, **kwds):
               :widths: 30, 70
               :delim: |
 
-              ``adjlist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.adjlist.write_adjlist.html
-              ``dot`` | https://networkx.github.io/documentation/latest/reference/generated/networkx.drawing.nx_pydot.write_dot.html
-              ``edgelist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.edgelist.write_edgelist.html
-              ``gexf`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.gexf.write_gexf.html
-              ``gml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.gml.write_gml.html
-              ``graphml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.graphml.write_graphml.html
-              ``multiline_adjlist`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.multiline_adjlist.write_multiline_adjlist.html
-              ``pajek`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.pajek.write_pajek.html
-              ``yaml`` | http://networkx.lanl.gov/reference/generated/networkx.readwrite.nx_yaml.write_yaml.html
+              ``'adjlist'``           | :func:`networkx.readwrite.adjlist.write_adjlist`
+              ``'dot'``               | :func:`networkx.drawing.nx_pydot.write_dot`
+              ``'edgelist'``          | :func:`networkx.readwrite.edgelist.write_edgelist`
+              ``'gexf'``              | :func:`networkx.readwrite.gexf.write_gexf`
+              ``'gml'``               | :func:`networkx.readwrite.gml.write_gml`
+              ``'graphml'``           | :func:`networkx.readwrite.graphml.write_graphml`
+              ``'multiline_adjlist'`` | :func:`networkx.readwrite.multiline_adjlist.write_multiline_adjlist`
+              ``'pajek'``             | :func:`networkx.readwrite.pajek.write_pajek`
 
         .. SEEALSO::
 
@@ -1366,7 +1365,7 @@ def export_to_file(self, filename, format=None, **kwds):
         .. NOTE::
 
             This functions uses the ``write_*`` functions defined in NetworkX
-            (see http://networkx.lanl.gov/reference/readwrite.html).
+            (see :mod:`networkx.readwrite`).
 
         EXAMPLES::
 

src/sage/libs/flint/arith_sage.pyx

@@ -31,6 +31,10 @@ def bell_number(unsigned long n):
 
     See :wikipedia:`Bell_number`.
 
+    ALGORITHM:
+
+    Uses :c:func:`arith_bell_number`.
+
     EXAMPLES::
 
         sage: from sage.libs.flint.arith_sage import bell_number

src/sage/manifolds/differentiable/integrated_curve.py

@@ -949,7 +949,7 @@ def solve(self, step=None, method='odeint', solution_key=None,
           use for the integration of the curve; available algorithms are:
 
           * ``'odeint'`` - makes use of
-            `scipy.integrate.odeint <https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.odeint.html>`_
+            :func:`scipy:scipy.integrate.odeint`
             via Sage solver
             :func:`~sage.calculus.desolvers.desolve_odeint`; ``odeint`` invokes
             the LSODA algorithm of the
@@ -961,9 +961,9 @@ def solve(self, step=None, method='odeint', solution_key=None,
             makes use of Maxima's dynamics package via Sage solver
             :func:`~sage.calculus.desolvers.desolve_system_rk4` (quite slow)
           * ``'dopri5'`` - Dormand-Prince Runge-Kutta of order (4)5 provided by
-            `scipy.integrate.ode <https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.ode.html>`_
+            :obj:`scipy:scipy.integrate.ode`
           * ``'dop853'`` - Dormand-Prince Runge-Kutta of order 8(5,3) provided by
-            `scipy.integrate.ode <https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.ode.html>`_
+            :obj:`scipy:scipy.integrate.ode`
 
           and those provided by ``GSL`` via Sage class
           :class:`~sage.calculus.ode.ode_solver`:
@@ -1425,8 +1425,8 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None,
         Integrate the curve numerically over the domain of integration, with
         the ability to switch chart mid-integration.
 
-        The only supported solver is
-        `scipy.integrate.ode <https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.ode.html>`_, because it supports basic event handling, needed to detect when the
+        The only supported solver is :obj:`scipy:scipy.integrate.ode`,
+        because it supports basic event handling, needed to detect when the
         curve is reaching the frontier of the chart. This is an adaptive step
         solver. So the ``step`` is not the step of integration but instead the
         step used to peak at the current chart, and switch if needed.
@@ -1525,8 +1525,8 @@ def solve_across_charts(self, charts=None, step=None, solution_key=None,
 
         The integration is done as usual, but using the method
         :meth:`solve_across_charts` instead of :meth:`solve`. This forces the
-        use of ``scipy.integrate.ode`` as the solver, because of event handling
-        support.
+        use of :obj:`scipy:scipy.integrate.ode` as the solver, because of event
+        handling support.
 
         The argument ``verbose=True`` will cause the solver to write a small
         message each time it is switching chart::

src/sage/matrix/matrix_double_dense.pyx

@@ -594,8 +594,8 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
 
         ALGORITHM:
 
-        Computation is performed by the ``norm()`` function of
-        the SciPy/NumPy library.
+        Computation is performed by the :func:`~scipy:scipy.linalg.norm`
+        function of the SciPy/NumPy library.
 
         EXAMPLES:
 
@@ -739,7 +739,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
         ALGORITHM:
 
         The singular values come from the SVD decomposition
-        computed by SciPy/NumPy.
+        computed by SciPy/NumPy using :func:`scipy:scipy.linalg.svd`.
 
         EXAMPLES:
 
@@ -1073,17 +1073,17 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
 
           - ``'default'`` - applicable to any matrix
             with double-precision floating point entries.
-            Uses the :meth:`~scipy.linalg.eigvals` method from SciPy.
+            Uses the :func:`~scipy:scipy.linalg.eigvals` function from SciPy.
 
           - ``'symmetric'`` - converts the matrix into a real matrix
             (i.e. with entries from :class:`~sage.rings.real_double.RDF`),
             then applies the algorithm for Hermitian matrices.  This
             algorithm can be significantly faster than the
             ``'default'`` algorithm.
 
-          - ``'hermitian'`` - uses the :meth:`~scipy.linalg.eigh` method
-            from SciPy, which applies only to real symmetric or complex
-            Hermitian matrices.  Since Hermitian is defined as a matrix
+          - ``'hermitian'`` - uses the :func:`~scipy:scipy.linalg.eigh`
+            function from SciPy, which applies only to real symmetric or
+            complex Hermitian matrices.  Since Hermitian is defined as a matrix
             equaling its conjugate-transpose, for a matrix with real
             entries this property is equivalent to being symmetric.
             This algorithm can be significantly faster than the
@@ -1707,6 +1707,10 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
         Find a solution `X` to the equation `A X = B` if ``self`` is a square
         matrix `A`.
 
+        ALGORITHM:
+
+        Uses the function :func:`scipy:scipy.linalg.solve` from SciPy.
+
         TESTS::
 
             sage: # needs sage.symbolic
@@ -1730,6 +1734,10 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
         Compute a least-squares solution `X` to the equation `A X = B` where
         ``self`` is the matrix `A`.
 
+        ALGORITHM:
+
+        Uses the function :func:`scipy:scipy.linalg.lstsq` from SciPy.
+
         TESTS::
 
             sage: A = matrix(RDF, 3, 2, [1, 3, 4, 2, 0, -3])
@@ -1754,7 +1762,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
 
         ALGORITHM:
 
-        Use numpy
+        Uses :func:`scipy:scipy.linalg.det`.
 
         EXAMPLES::
 
@@ -2037,7 +2045,7 @@ cdef class Matrix_double_dense(Matrix_numpy_dense):
 
         ALGORITHM:
 
-        Calls "linalg.qr" from SciPy, which is in turn an
+        Calls :func:`scipy:scipy.linalg.qr` from SciPy, which is in turn an
         interface to LAPACK routines.
 
         EXAMPLES:

src/sage/matroids/matroids_plot_helpers.py

@@ -20,8 +20,9 @@
     via an optimization that gives aesthetically pleasing point placement (in
     some sense. This is not yet implemented).    One can then use
     ``createline`` function to produce sequence of ``100`` points on a smooth
-    curve containing the points in the specified line which inturn uses
-    ``scipy.interpolate.splprep`` and ``scipy.interpolate.splev``.  Then one
+    curve containing the points in the specified line which in turn uses
+    :func:`scipy:scipy.interpolate.splprep` and
+    :func:`scipy:scipy.interpolate.splev`.  Then one
     can use sage's graphics primitives ``line``, ``point``, ``text`` and
     ``points`` to produce graphics object containing points (ground set
     elements) and lines (for a rank 3 matroid, these are flats of rank 2 of

src/sage/modules/vector_double_dense.pyx

@@ -395,8 +395,8 @@ cdef class Vector_double_dense(Vector_numpy_dense):
 
         ALGORITHM:
 
-        Computation is performed by the ``norm()`` function of
-        the SciPy/NumPy library.
+        Computation is performed by the :func:`~scipy:scipy.linalg.norm`
+        function of the SciPy/NumPy library.
 
         EXAMPLES: