Merge pull request #3397 from asi1024/optuna-docs

Add documentation for `cupyx.optimizing.optimize`

cupyx/optimizing/_optimize.py

@@ -43,6 +43,37 @@ def objective(trial):
 
 @contextlib.contextmanager
 def optimize(*, key=None, **config_dict):
+    """Context manager that optimizes kernel launch parameters.
+
+    In this context, CuPy's routines find the best kernel launch parameter
+    values (e.g., the number of threads and blocks). The found values are
+    cached and reused with keys as the shapes, strides and dtypes of the
+    given inputs arrays.
+
+    Args:
+        key (string or None): The cache key of optimizations.
+        max_trials (int): The number of trials that defaults to 100.
+        timeout (float):
+            Stops study after the given number of seconds. Default is 1.
+        max_total_time_per_trial (float):
+            Repeats measuring the execution time of the routine for the
+            given number of seconds. Default is 0.1.
+
+    Examples
+    --------
+    >>> import cupy
+    >>> from cupyx import optimizing
+    >>>
+    >>> x = cupy.arange(100)
+    >>> with optimizing.optimize():
+    ...     cupy.sum(x)
+    ...
+    array(4950)
+
+    .. note::
+      Optuna (https://optuna.org) installation is required.
+      Currently it works for reduction operations only.
+    """
     if not _optuna_available:
         raise RuntimeError(
             'Optuna is required to run optimization. '

docs/source/reference/index.rst

@@ -27,6 +27,7 @@ This is the official reference of CuPy, a multi-dimensional array on CUDA with a
    cuda
    memoize
    kernel
+   optimize
    interoperability
    testing
    prof

docs/source/reference/optimize.rst

@@ -0,0 +1,10 @@
+.. module:: cupyx.optimizing
+
+Automatic Kernel Parameters Optimizations
+=========================================
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   cupyx.optimizing.optimize