Merge branch 'main' into recipe/torch_export_models

Author: agunapal

.github/workflows/build-tutorials.yml

@@ -44,6 +44,8 @@ jobs:
 
       - name: Checkout Tutorials
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Setup Linux
         uses: pytorch/pytorch/.github/actions/setup-linux@main
@@ -115,6 +117,8 @@ jobs:
 
       - name: Checkout Tutorials
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Setup Linux
         uses: pytorch/pytorch/.github/actions/setup-linux@main

.jenkins/insert_last_verified.py

@@ -0,0 +1,160 @@
+import json
+import os
+import subprocess
+import sys
+from datetime import datetime
+
+from bs4 import BeautifulSoup
+
+
+json_file_path = "tutorials-review-data.json"
+
+# paths to skip from the post-processing script
+paths_to_skip = [
+    "beginner/examples_autograd/two_layer_net_custom_function",  # not present in the repo
+    "beginner/examples_nn/two_layer_net_module",  # not present in the repo
+    "beginner/examples_tensor/two_layer_net_numpy",  # not present in the repo
+    "beginner/examples_tensor/two_layer_net_tensor",  # not present in the repo
+    "beginner/examples_autograd/two_layer_net_autograd",  # not present in the repo
+    "beginner/examples_nn/two_layer_net_optim",  # not present in the repo
+    "beginner/examples_nn/two_layer_net_nn",  # not present in the repo
+    "intermediate/coding_ddpg",  # not present in the repo - will delete the carryover
+]
+# Mapping of source directories to build directories
+source_to_build_mapping = {
+    "beginner": "beginner_source",
+    "recipes": "recipes_source",
+    "distributed": "distributed",
+    "intermediate": "intermediate_source",
+    "prototype": "prototype_source",
+    "advanced": "advanced_source",
+    "": "",  # root dir for index.rst
+}
+
+def get_git_log_date(file_path, git_log_args):
+    try:
+        result = subprocess.run(
+            ["git", "log"] + git_log_args + ["--", file_path],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        if result.stdout:
+            date_str = result.stdout.splitlines()[0]
+            return datetime.strptime(date_str, "%a, %d %b %Y %H:%M:%S %z")
+    except subprocess.CalledProcessError:
+        pass
+    raise ValueError(f"Could not find date for {file_path}")
+
+def get_creation_date(file_path):
+    return get_git_log_date(file_path, ["--diff-filter=A", "--format=%aD"]).strftime("%b %d, %Y")
+
+
+def get_last_updated_date(file_path):
+    return get_git_log_date(file_path, ["-1", "--format=%aD"]).strftime("%b %d, %Y")
+
+# Try to find the source file with the given base path and the extensions .rst and .py
+def find_source_file(base_path):
+    for ext in [".rst", ".py"]:
+        source_file_path = base_path + ext
+        if os.path.exists(source_file_path):
+            return source_file_path
+    return None
+
+
+# Function to process a JSON file and insert the "Last Verified" information into the HTML files
+def process_json_file(build_dir , json_file_path):
+    with open(json_file_path, "r", encoding="utf-8") as json_file:
+        json_data = json.load(json_file)
+
+    for entry in json_data:
+        path = entry["Path"]
+        last_verified = entry["Last Verified"]
+        status = entry.get("Status", "")
+        if path in paths_to_skip:
+            print(f"Skipping path: {path}")
+            continue
+        if status in ["needs update", "not verified"]:
+            formatted_last_verified = "Not Verified"
+        elif last_verified:
+            try:
+                last_verified_date = datetime.strptime(last_verified, "%Y-%m-%d")
+                formatted_last_verified = last_verified_date.strftime("%b %d, %Y")
+            except ValueError:
+                formatted_last_verified = "Unknown"
+        else:
+            formatted_last_verified = "Not Verified"
+        if status == "deprecated":
+            formatted_last_verified += "Deprecated"
+
+        for build_subdir, source_subdir in source_to_build_mapping.items():
+            if path.startswith(build_subdir):
+                html_file_path = os.path.join(build_dir, path + ".html")
+                base_source_path = os.path.join(
+                    source_subdir, path[len(build_subdir) + 1 :]
+                )
+                source_file_path = find_source_file(base_source_path)
+                break
+        else:
+            print(f"Warning: No mapping found for path {path}")
+            continue
+
+        if not os.path.exists(html_file_path):
+            print(
+                f"Warning: HTML file not found for path {html_file_path}."
+                "If this is a new tutorial, please add it to the audit JSON file and set the Verified status and todays's date."
+            )
+            continue
+
+        if not source_file_path:
+            print(f"Warning: Source file not found for path {base_source_path}.")
+            continue
+
+        created_on = get_creation_date(source_file_path)
+        last_updated = get_last_updated_date(source_file_path)
+
+        with open(html_file_path, "r", encoding="utf-8") as file:
+            soup = BeautifulSoup(file, "html.parser")
+        # Check if the <p> tag with class "date-info-last-verified" already exists
+        existing_date_info = soup.find("p", {"class": "date-info-last-verified"})
+        if existing_date_info:
+            print(
+                f"Warning: <p> tag with class 'date-info-last-verified' already exists in {html_file_path}"
+            )
+            continue
+
+        h1_tag = soup.find("h1")  # Find the h1 tag to insert the dates
+        if h1_tag:
+            date_info_tag = soup.new_tag("p", **{"class": "date-info-last-verified"})
+            date_info_tag["style"] = "color: #6c6c6d; font-size: small;"
+            # Add the "Created On", "Last Updated", and "Last Verified" information
+            date_info_tag.string = (
+                f"Created On: {created_on} | "
+                f"Last Updated: {last_updated} | "
+                f"Last Verified: {formatted_last_verified}"
+            )
+            # Insert the new tag after the <h1> tag
+            h1_tag.insert_after(date_info_tag)
+            # Save back to the HTML.
+            with open(html_file_path, "w", encoding="utf-8") as file:
+                file.write(str(soup))
+        else:
+            print(f"Warning: <h1> tag not found in {html_file_path}")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Error: Build directory not provided. Exiting.")
+        exit(1)
+    build_dir = sys.argv[1]
+    print(f"Build directory: {build_dir}")
+    process_json_file(build_dir , json_file_path)
+    print(
+        "Finished processing JSON file. Please check the output for any warnings. "
+        "Pages like `nlp/index.html` are generated only during the full `make docs` "
+        "or `make html` build. Warnings about these files when you run `make html-noplot` "
+        "can be ignored."
+    )
+
+if __name__ == "__main__":
+    main()

Makefile

@@ -86,18 +86,29 @@ download:
 	wget https://www.cis.upenn.edu/~jshi/ped_html/PennFudanPed.zip -P $(DATADIR)
 	unzip -o $(DATADIR)/PennFudanPed.zip -d intermediate_source/data/
 
+download-last-reviewed-json:
+	@echo "Downloading tutorials-review-data.json..."
+	curl -o tutorials-review-data.json https://raw.githubusercontent.com/pytorch/tutorials/refs/heads/last-reviewed-data-json/tutorials-review-data.json
+	@echo "Finished downloading tutorials-review-data.json."
 docs:
 	make download
+	make download-last-reviewed-json
 	make html
+	@python .jenkins/insert_last_verified.py $(BUILDDIR)/html
 	rm -rf docs
 	cp -r $(BUILDDIR)/html docs
 	touch docs/.nojekyll
+	rm -rf tutorials-review-data.json
 
 html-noplot:
 	$(SPHINXBUILD) -D plot_gallery=0 -b html $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
 	# bash .jenkins/remove_invisible_code_block_batch.sh "$(BUILDDIR)/html"
 	@echo
+	make download-last-reviewed-json
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Running post-processing script to insert 'Last Verified' dates..."
+	@python .jenkins/insert_last_verified.py $(BUILDDIR)/html
+	rm -rf tutorials-review-data.json
 
 clean-cache:
 	make clean

advanced_source/cpp_custom_ops.rst

@@ -19,6 +19,10 @@ Custom C++ and CUDA Operators
        * PyTorch 2.4 or later
        * Basic understanding of C++ and CUDA programming
 
+.. note::
+
+  This tutorial will also work on AMD ROCm with no additional modifications.
+
 PyTorch offers a large library of operators that work on Tensors (e.g. torch.add, torch.sum, etc).
 However, you may wish to bring a new custom operator to PyTorch. This tutorial demonstrates the
 blessed path to authoring a custom operator written in C++/CUDA.
@@ -63,9 +67,47 @@ Using ``cpp_extension`` is as simple as writing the following ``setup.py``:
 
 If you need to compile CUDA code (for example, ``.cu`` files), then instead use
 `torch.utils.cpp_extension.CUDAExtension <https://pytorch.org/docs/stable/cpp_extension.html#torch.utils.cpp_extension.CUDAExtension>`_.
-Please see how
-`extension-cpp <https://github.com/pytorch/extension-cpp>`_ for an example for
-how this is set up.
+Please see `extension-cpp <https://github.com/pytorch/extension-cpp>`_ for an
+example for how this is set up.
+
+Starting with PyTorch 2.6, you can now build a single wheel for multiple CPython
+versions (similar to what you would do for pure python packages). In particular,
+if your custom library adheres to the `CPython Stable Limited API
+<https://docs.python.org/3/c-api/stable.html>`_ or avoids CPython entirely, you
+can build one Python agnostic wheel against a minimum supported CPython version
+through setuptools' ``py_limited_api`` flag, like so:
+
+.. code-block:: python
+
+  from setuptools import setup, Extension
+  from torch.utils import cpp_extension
+
+  setup(name="extension_cpp",
+        ext_modules=[
+            cpp_extension.CppExtension(
+              "extension_cpp",
+              ["python_agnostic_code.cpp"],
+              py_limited_api=True)],
+        cmdclass={'build_ext': cpp_extension.BuildExtension},
+        options={"bdist_wheel": {"py_limited_api": "cp39"}}
+  )
+
+Note that you must specify ``py_limited_api=True`` both within ``setup``
+and also as an option to the ``"bdist_wheel"`` command with the minimal supported
+Python version (in this case, 3.9). This ``setup`` would build one wheel that could
+be installed across multiple Python versions ``python>=3.9``. Please see
+`torchao <https://github.com/pytorch/ao>`_ for an example.
+
+.. note::
+
+  You must verify independently that the built wheel is truly Python agnostic.
+  Specifying ``py_limited_api`` does not check for any guarantees, so it is possible
+  to build a wheel that looks Python agnostic but will crash, or worse, be silently
+  incorrect, in another Python environment. Take care to avoid using unstable CPython
+  APIs, for example APIs from libtorch_python (in particular pytorch/python bindings,)
+  and to only use APIs from libtorch (aten objects, operators and the dispatcher).
+  For example, to give access to custom ops from Python, the library should register
+  the ops through the dispatcher (covered below!).
 
 Defining the custom op and adding backend implementations
 ---------------------------------------------------------
@@ -177,7 +219,7 @@ operator specifies how to compute the metadata of output tensors given the metad
 The FakeTensor kernel should return dummy Tensors of your choice with
 the correct Tensor metadata (shape/strides/``dtype``/device).
 
-We recommend that this be done from Python via the `torch.library.register_fake` API,
+We recommend that this be done from Python via the ``torch.library.register_fake`` API,
 though it is possible to do this from C++ as well (see
 `The Custom Operators Manual <https://pytorch.org/docs/main/notes/custom_operators.html>`_
 for more details).
@@ -188,7 +230,9 @@ for more details).
   # before calling ``torch.library`` APIs that add registrations for the
   # C++ custom operator(s). The following import loads our
   # C++ custom operator definitions.
-  # See the next section for more details.
+  # Note that if you are striving for Python agnosticism, you should use
+  # the ``load_library(...)`` API call instead. See the next section for
+  # more details.
   from . import _C
 
   @torch.library.register_fake("extension_cpp::mymuladd")
@@ -214,7 +258,10 @@ of two ways:
 1. If you're following this tutorial, importing the Python C extension module
    we created will load the C++ custom operator definitions.
 2. If your C++ custom operator is located in a shared library object, you can
-   also use ``torch.ops.load_library("/path/to/library.so")`` to load it.
+   also use ``torch.ops.load_library("/path/to/library.so")`` to load it. This
+   is the blessed path for Python agnosticism, as you will not have a Python C
+   extension module to import. See `torchao __init__.py <https://github.com/pytorch/ao/blob/881e84b4398eddcea6fee4d911fc329a38b5cd69/torchao/__init__.py#L26-L28>`_
+   for an example.
 
 
 Adding training (autograd) support for an operator

advanced_source/cpp_frontend.rst

@@ -969,15 +969,15 @@ the data loader every epoch and then write the GAN training code:
       discriminator->zero_grad();
       torch::Tensor real_images = batch.data;
       torch::Tensor real_labels = torch::empty(batch.data.size(0)).uniform_(0.8, 1.0);
-      torch::Tensor real_output = discriminator->forward(real_images);
+      torch::Tensor real_output = discriminator->forward(real_images).reshape(real_labels.sizes());
       torch::Tensor d_loss_real = torch::binary_cross_entropy(real_output, real_labels);
       d_loss_real.backward();
 
       // Train discriminator with fake images.
       torch::Tensor noise = torch::randn({batch.data.size(0), kNoiseSize, 1, 1});
       torch::Tensor fake_images = generator->forward(noise);
       torch::Tensor fake_labels = torch::zeros(batch.data.size(0));
-      torch::Tensor fake_output = discriminator->forward(fake_images.detach());
+      torch::Tensor fake_output = discriminator->forward(fake_images.detach()).reshape(fake_labels.sizes());
       torch::Tensor d_loss_fake = torch::binary_cross_entropy(fake_output, fake_labels);
       d_loss_fake.backward();
 
@@ -987,7 +987,7 @@ the data loader every epoch and then write the GAN training code:
       // Train generator.
       generator->zero_grad();
       fake_labels.fill_(1);
-      fake_output = discriminator->forward(fake_images);
+      fake_output = discriminator->forward(fake_images).reshape(fake_labels.sizes());
       torch::Tensor g_loss = torch::binary_cross_entropy(fake_output, fake_labels);
       g_loss.backward();
       generator_optimizer.step();

advanced_source/custom_ops_landing_page.rst

@@ -23,6 +23,7 @@ You may wish to author a custom operator from Python (as opposed to C++) if:
   respect to ``torch.compile`` and ``torch.export``.
 - you have some Python bindings to C++/CUDA kernels and want those to compose with PyTorch
   subsystems (like ``torch.compile`` or ``torch.autograd``)
+- you are using Python (and not a C++-only environment like AOTInductor).
 
 Integrating custom C++ and/or CUDA code with PyTorch
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

advanced_source/pendulum.py

@@ -33,9 +33,9 @@
 
   In the process, we will touch three crucial components of TorchRL:
 
-* `environments <https://pytorch.org/rl/reference/envs.html>`__
-* `transforms <https://pytorch.org/rl/reference/envs.html#transforms>`__
-* `models (policy and value function) <https://pytorch.org/rl/reference/modules.html>`__
+* `environments <https://pytorch.org/rl/stable/reference/envs.html>`__
+* `transforms <https://pytorch.org/rl/stable/reference/envs.html#transforms>`__
+* `models (policy and value function) <https://pytorch.org/rl/stable/reference/modules.html>`__
 
 """
 
@@ -384,7 +384,7 @@ def _reset(self, tensordict):
 # convenient shortcuts to the content of the output and input spec containers.
 #
 # TorchRL offers multiple :class:`~torchrl.data.TensorSpec`
-# `subclasses <https://pytorch.org/rl/reference/data.html#tensorspec>`_ to
+# `subclasses <https://pytorch.org/rl/stable/reference/data.html#tensorspec>`_ to
 # encode the environment's input and output characteristics.
 #
 # Specs shape

advanced_source/python_custom_ops.py

@@ -3,7 +3,7 @@
 """
 .. _python-custom-ops-tutorial:
 
-Python Custom Operators
+Custom Python Operators
 =======================
 
 .. grid:: 2
@@ -30,6 +30,12 @@
   into the function).
 - Adding training support to an arbitrary Python function
 
+Use :func:`torch.library.custom_op` to create Python custom operators.
+Use the C++ ``TORCH_LIBRARY`` APIs to create C++ custom operators (these
+work in Python-less environments).
+See the `Custom Operators Landing Page <https://pytorch.org/tutorials/advanced/custom_ops_landing_page.html>`_
+for more details.
+
 Please note that if your operation can be expressed as a composition of
 existing PyTorch operators, then there is usually no need to use the custom operator
 API -- everything (for example ``torch.compile``, training support) should