Improve cross referencing

Author: nicolasvasilache

docs/source/framework/pytorch_integration/python_api.rst

@@ -13,6 +13,32 @@ Comprehensions.
 
 .. autofunction:: make_autograd
 
+The :func:`define` function provides an implicit compilation caching
+functionality which alleviates the need to implement a caching mechanism at
+the user-facing level. The question still remains which :class:`~tclib.MappingOptions`
+to use to compile. Since this is still an open problem, we provide support
+for user-defined functions to specify this behavior. We require a user
+of the :func:`define` function to provide a :class:`~tclib.MappingOptions` generator
+function whose sole purpose is to determine the options with which to compile
+a particular TC def for particular input sizes.
+
+To facilitate usage we provide the following generators:
+		  
+.. autofunction:: make_naive_options_factory
+		  
+.. autofunction:: make_load_from_cache_options_factory
+		  
+.. autofunction:: make_autotuned_options_factory	 
+
+Custom behavior to select :class:`~tclib.MappingOptions` may be implemented
+in addition to the provided defaults. The signature of custom generators must
+match:
+
+.. code-block:: python
+		
+   def some_generator(tc: str, entry_point: str, *inputs: torch.Tensor)
+       -> MappingOptions:
+           ...
 
 Low-level API
 -------------
@@ -31,7 +57,7 @@ generally useful for benchmarking.
 
 .. autofunction:: autotune_and_compile
 
-Additionally the :code:`assert_almost_equal` helper function is useful in
+Additionally the :func:`assert_almost_equal` helper function is useful in
 performing numerical checks.
 
 .. autofunction:: assert_almost_equal

docs/source/framework/pytorch_integration/writing_layers.rst

@@ -1,17 +1,19 @@
 Writing TC operations
 =====================
 
+.. automodule:: tensor_comprehensions
+
 This document focuses on writing TC operations using the high-level API.
 For examples of using the low-level API, see the Python API documentation.
 
 To create a CUDA kernel implementing an operation backed by TC, one should:
 
 1. Create a callable TC object by calling :func:`define`
 2. Create input PyTorch Tensors
-3. Call the helper object with the input PyTorch Tensors
+3. Call the TC object with the input PyTorch Tensors
 
 When running, the backend ensures the TC is compiled and memoized for the
-given input tensor sizes (see the documentation for :func:`define` for more detals).
+given input tensor sizes (see the documentation for :func:`define` for more details).
 Calling the object returned by :func:`define` executes the
 corresponding operation and returns a list of outputs.
 If the operation has already been compiled, in the following runs, the TC
@@ -23,11 +25,11 @@ Example
 
 The following example demonstrates the steps above.
 We use the :func:`make_naive_options_factory` builder function to provide
-naive :class:`MappingOptions`.  Naive options result in poor performance.
-At this time, there is no notion of a default :class:`MappingOptions`.
+naive :class:`~tclib.MappingOptions`.  Naive options result in poor performance.
+At this time, there is no notion of a default :class:`~tclib.MappingOptions`.
 Instead one should use the autotuner to perform an evolutionary search
-starting from an initial :class:`MappingOptions` object and return a better
-:class:`MappingOptions` object for a given TC function and sizes (more on this
+starting from an initial :class:`~tclib.MappingOptions` object and return a better
+:class:`~tclib.MappingOptions` object for a given TC function and sizes (more on this
 below).
 
     .. code-block:: python
@@ -50,19 +52,19 @@ below).
 Specifying MappingOptions
 -------------------------
 
-There are three ways to construct :class:`MappingOptions` when defining a TC:
+There are three ways to construct :class:`~tclib.MappingOptions` when defining a TC:
 
 * **Naive MappingOptions**:
 
   * :code:`naive`: this is provided to create a basic GPU mapping strategy with
     3-D tiling by 32x32x32, mapping to 256x256 blocks 32x8 threads. This
     should by no means be considered a good baseline but just a point to
     get started using TC. Once a correct TC is written, we recommend either
-    using options loaded from a :class:`MappingOptionsCache` or resulting from
-    a tuning run. One can also modify a :class:`MappingOptions` object
+    using options loaded from a :class:`~tclib.MappingOptionsCache` or resulting from
+    a tuning run. One can also modify a :class:`~tclib.MappingOptions` object
     programmatically (see the API documentation).
 
-* **Loading from MappingOptionsCache**: a :class:`MappingOptionsCache` provides
+* **Loading from MappingOptionsCache**: a :class:`~tclib.MappingOptionsCache` provides
   a simple interface to load the best options from a previous tuning run.
 
 * **Autotuning**: A kernel can be autotuned for fixed input tensor sizes.
@@ -73,7 +75,7 @@ There are three ways to construct :class:`MappingOptions` when defining a TC:
 Loading from cache
 ------------------
 
-Loading the best options from a previously serialized :class:`MappingOptionsCache`
+Loading the best options from a previously serialized :class:`~tclib.MappingOptionsCache`
 can be achieved by making a factory function with
 :func:`make_load_from_cache_options_factory` and passing it as an argument to the
 :func:`define` function:
@@ -91,7 +93,7 @@ can be achieved by making a factory function with
             torch.randn(G, D, device='cuda'))
         Sum, SumSq, O = T.group_normalization(I, gamma, beta)
 
-One can also use the low-level :class:`MappingOptionsCache`.
+One can also use the low-level :class:`~tclib.MappingOptionsCache`.
 
 Autotuning
 ----------
@@ -121,10 +123,10 @@ Tuning can be achieved by making a factory function with
        that case, the compilation and evaluation jobs currently in flight will
        be flushed, but no new compilation job will be created. Once the jobs in
        flight are flushed, saving to cache occurs (if requested) and the best
-       :class:`MappingOptions` found so far will be returned.
+       :class:`~tclib.MappingOptions` found so far will be returned.
 
 Tuning behavior can be modified by defining the TC with an optional
-:class:`TunerConfig` parameter constructed as such:
+:class:`~tclib.TunerConfig` parameter constructed as such:
 :code:`tuner_config=tc.TunerConfig().threads(5).generations(3).pop_size(5)`.
 
     .. note::

tensor_comprehensions/__init__.py

@@ -166,9 +166,9 @@ def autotune(tc: str,
         :param inputs: PyTorch Tensors that TC should tune for. The inputs must be
             passed in the order they are also passed in the definition of
             the TC function.
-        :param starting_options: :code:`MappingOptions` from which tuning should start.
-        :param tuner_config: :code:`TunerConfig` to control the behavior of the autotuner.
-        :param load_from_cache: Get the starting MappingOptions by loading from
+        :param starting_options: :class:`~tclib.MappingOptions` from which tuning should start.
+        :param tuner_config: :class:`~tclib.TunerConfig` to control the behavior of the autotuner.
+        :param load_from_cache: Get the starting :class:`~tclib.MappingOptions` by loading from
             :code:`cache_filename`. If loading fails to recover an entry
             from the cache file for the given input sizes an assertion error
             will trigger.
@@ -256,13 +256,13 @@ def autotune_and_compile(
 
 def make_naive_options_factory() -> (
         Callable[[str, str, Iterable[torch.Tensor]], MappingOptions]):
-    r"""Return a factory that always generates naive :class:`MappingOptions`.
+    r"""Return a factory that always generates naive :class:`~tclib.MappingOptions`.
 
         For easily getting started with TC and debugging purposes only.
 
         :rtype: a function that takes a string with multiple
             TC defs, an entry_point and input PyTorch Tensors and produces a
-            :class:`MappingOptions`.
+            :class:`~tclib.MappingOptions`.
     """
     def generate(tc: str,
                  entry_point: str,
@@ -273,12 +273,12 @@ def generate(tc: str,
 
 def make_load_from_cache_options_factory(cache_filename: str) -> (
         Callable[[str, str, Iterable[torch.Tensor]], MappingOptions]):
-    r"""Return a factory that loads :class:`MappingOptions` from a cache file.
+    r"""Return a factory that loads :class:`~tclib.MappingOptions` from a cache file.
 
         :param cache_filename: the filename
         :rtype: a function that takes a string with multiple
             TC defs, an entry_point and input PyTorch Tensors and produces a
-            :class:`MappingOptions`.
+            :class:`~tclib.MappingOptions`.
     """
     def generate(tc: str,
                  entry_point: str,
@@ -298,14 +298,14 @@ def make_autotuned_options_factory(
         load_from_cache: Optional[bool] = False,
         store_to_cache: Optional[bool] = False) -> (
             Callable[[str, str, Iterable[torch.Tensor]], MappingOptions]):
-    r"""Return a factory that runs autotuning to determine the best :class:`MappingOptions`.
+    r"""Return a factory that runs autotuning to determine the best :class:`~tclib.MappingOptions`.
 
         The returned factory just calls the :func:`autotune` function, see
-        it documentation for more information.
+        its documentation for more information.
 
         :rtype: a function that takes a string with multiple
             TC defs, an entry_point and input PyTorch Tensors and produces a
-            :class:`MappingOptions`.
+            :class:`~tclib.MappingOptions`.
     """
     def generate(tc: str,
                  entry_point: str,
@@ -408,7 +408,7 @@ def define(tc: str,
     with PyTorch Tensors of new sizes. The returned :class:`TC` helper class is
     backed by a compilation cache which memoizes the results of compilation and
     avoids spurious recompilations. In order to determine the
-    :class:`MappingOptions`, used for JIT compiling a particular TC def on
+    :class:`~tclib.MappingOptions`, used for JIT compiling a particular TC def on
     inputs of particular sizes, the :code:`mapping_options_factory`
     function is called. We provide the factory builder functions
     :func:`make_naive_options_factory`,
@@ -427,7 +427,7 @@ def define(tc: str,
     :param tc: a string containing one of more TC defs.
     :param mapping_options_factory: a function that takes a string with multiple
         TC defs, an entry_point and input PyTorch Tensors and produces a
-        :class:`MappingOptions`.
+        :class:`~tclib.MappingOptions`.
     :rtype: a Callable helper object with methods corresponding to the TC def
         names and backed by a compilation cache.