(chore): small doc improvements (#177)

Author: ilan-gold

docs/source/tutorial.rst

@@ -62,26 +62,32 @@ dimensions.
 At the time, *torchquad* offers the following integration methods for
 abritrary dimensionality.
 
-+--------------+-------------------------------------------------+------------+
-| Name         | How it works                                    | Spacing    |
-|              |                                                 |            |
-+==============+=================================================+============+
-| Trapezoid    | Creates a linear interpolant between two |br|   | Equal      |
-| rule         | neighbouring points                             |            |
-+--------------+-------------------------------------------------+------------+
-| Simpson's    | Creates a quadratic interpolant between |br|    | Equal      |
-| rule         | three neighbouring point                        |            |
-+--------------+-------------------------------------------------+------------+
-| Boole's      | Creates a more complex interpolant between |br| | Equal      |
-| rule         | five neighbouring points                        |            |
-+--------------+-------------------------------------------------+------------+
-| Monte Carlo  | Randomly chooses points at which the |br|       | Random     |
-|              | integrand is evaluated                          |            |
-+--------------+-------------------------------------------------+------------+
-| VEGAS        | Adaptive multidimensional Monte Carlo |br|      | Stratified |
-| Enhanced     | integration (VEGAS with adaptive stratified     | |br|       |
-| |br| (VEGAS+)| |br| sampling)                                  | sampling   |
-+--------------+-------------------------------------------------+------------+
++--------------+----------------------------------------------------+------------+
+| Name         | How it works                                       | Spacing    |
+|              |                                                    |            |
++==============+====================================================+============+
+| Trapezoid    | Creates a linear interpolant between two |br|      | Equal      |
+| rule         | neighbouring points                                |            |
++--------------+----------------------------------------------------+------------+
+| Simpson's    | Creates a quadratic interpolant between |br|       | Equal      |
+| rule         | three neighbouring point                           |            |
++--------------+----------------------------------------------------+------------+
+| Boole's      | Creates a more complex interpolant between |br|    | Equal      |
+| rule         | five neighbouring points                           |            |
++--------------+----------------------------------------------------+------------+
+| Gaussian     | Uses orthogonal polynomials to generate a grid     | Unequal    |
+| Quadrature   | of sample points along with corresponding weights. |            |
+|              | A `GaussLegendre` implementation is provided       |            |
+|              | as is a base `Gaussian` class that can be extended |            |
+|              | e.g., to other polynomials.                        |            |
++--------------+----------------------------------------------------+------------+
+| Monte Carlo  | Randomly chooses points at which the |br|          | Random     |
+|              | integrand is evaluated                             |            |
++--------------+----------------------------------------------------+------------+
+| VEGAS        | Adaptive multidimensional Monte Carlo |br|         | Stratified |
+| Enhanced     | integration (VEGAS with adaptive stratified        | |br|       |
+| |br| (VEGAS+)| |br| sampling)                                     | sampling   |
++--------------+----------------------------------------------------+------------+
 
 .. |br| raw:: html
 
@@ -100,6 +106,7 @@ the following way:
 4.  Information on how to select a numerical backend
 5.  Example showing how gradients can be obtained w.r.t. the integration domain with PyTorch
 6.  Methods to speed up the integration
+7.  Custom Integrators
 
 Feel free to test the code on your own computer as we go along.
 
@@ -586,7 +593,8 @@ Compiling the integrate method
 ``````````````````````````````
 
 To speed up the quadrature in situations where it is executed often with the
-same number of points ``N``, dimensionality ``dim``, and shape of the ``integrand``,
+same number of points ``N``, dimensionality ``dim``, and shape of the ``integrand``
+(see :ref:`the next section <multi_dim_integrand>` for more information on integrands),
 we can JIT-compile the performance-relevant parts of the integrate method:
 
 .. code:: ipython3
@@ -724,6 +732,8 @@ sample points for both functions:
 
     print(f"Quadrature results: {integral1}, {integral2}")
 
+.. _multi_dim_integrand:
+
 Multidimensional/Vectorized Integrands
 --------------------------------------
 
@@ -756,6 +766,9 @@ Now let's see how to do this a bit more simply, and in a way that provides signf
 
     torch.all(torch.isclose(result_vectorized, result)) # True!
 
+.. note::
+    VEGAS does not support multi-dimensional integrands.  If you would like this, please consider opening an issue or PR.
+
 Custom Integrators
 ------------------
 

torchquad/integration/gaussian.py

@@ -27,7 +27,7 @@ def __init__(self):
         self._cache = {}
 
     def integrate(self, fn, dim, N=8, integration_domain=None, backend=None):
-        """Integrates the passed function on the passed domain using Simpson's rule.
+        """Integrates the passed function on the passed domain using a Gaussian rule (Gauss-Legendre on [-1,1] as a default).
 
         Args:
             fn (func): The function to integrate over.

torchquad/integration/monte_carlo.py

@@ -27,7 +27,7 @@ def integrate(
 
         Args:
             fn (func): The function to integrate over.
-            dim (int): Dimensionality of the function to integrate.
+            dim (int): Dimensionality of the function's domain over which to integrate.
             N (int, optional): Number of sample points to use for the integration. Defaults to 1000.
             integration_domain (list or backend tensor, optional): Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim. It can also determine the numerical backend.
             seed (int, optional): Random number generation seed to the sampling point creation, only set if provided. Defaults to None.

torchquad/integration/vegas.py

@@ -45,10 +45,11 @@ def integrate(
         """Integrates the passed function on the passed domain using VEGAS.
 
         If the integrand output is far away from zero, i.e. lies within [b, b+c] for a constant b with large absolute value and small constant c, VEGAS does not adapt well to the integrand. Shifting the integrand so that it is close to zero may improve the accuracy of the calculated integral in this case.
+        This method does not support multi-dimensional/vectorized integrands (i.e., integrating an integrand repeatedly over a grid of points).
 
         Args:
             fn (func): The function to integrate over.
-            dim (int): Dimensionality of the function to integrate.
+            dim (int): Dimensionality of the function's domain over which to integrate.
             N (int, optional): Approximate maximum number of function evaluations to use for the integration. This value can be exceeded if the vegas stratification distributes evaluations per hypercube very unevenly. Defaults to 10000.
             integration_domain (list, optional): Integration domain, e.g. [[-1,1],[0,1]]. Defaults to [-1,1]^dim.
             seed (int, optional): Random number generation seed for the sampling point creation; only set if provided. Defaults to None.

torchquad/integration/vegas_map.py

@@ -16,7 +16,7 @@ def __init__(self, N_intervals, dim, backend, dtype, alpha=0.5) -> None:
 
         Args:
             N_intervals (int): Number of intervals per dimension to split the domain in.
-            dim (int): Dimensionality of the integrand.
+            dim (int): Dimensionality of the integration domain.
             backend (string): Numerical backend
             dtype (backend dtype): dtype used for the calculations
             alpha (float, optional): Alpha from the paper, EQ 19. Defaults to 0.5.

torchquad/integration/vegas_stratification.py

@@ -15,7 +15,7 @@ def __init__(self, N_increment, dim, rng, backend, dtype, beta=0.75):
 
         Args:
             N_increment (int): Number of evaluations per iteration.
-            dim (int): Dimensionality
+            dim (int): Dimensionality of the integration domain
             rng (RNG): Random number generator
             backend (string): Numerical backend
             dtype (backend dtype): dtype used for the calculations