Merge remote-tracking branch 'origin/main' into version-0.5

# Conflicts: # .github/workflows/wheels.yml
pytorch · vmoens · Jul 10, 2024 · Jul 3, 2024 · Jul 5, 2024 · Jul 9, 2024
commit 53645959143ed9781e3d22c33995ae63a5b260da
diff --git a/.github/workflows/build-wheels-linux.yml b/.github/workflows/build-wheels-linux.yml
@@ -0,0 +1,47 @@
+name: Build Linux Wheels
+
+on:
+  pull_request:
+  push:
+    branches:
+      - nightly
+      - main
+      - release/*
+    tags:
+        # NOTE: Binary build pipelines should only get triggered on release candidate builds
+        # Release candidate tags look like: v1.11.0-rc1
+        - v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  generate-matrix:
+    uses: pytorch/test-infra/.github/workflows/generate_binary_build_matrix.yml@main
+    with:
+      package-type: wheel
+      os: linux
+      test-infra-repository: pytorch/test-infra
+      test-infra-ref: main
+  build:
+    needs: generate-matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - repository: pytorch/rl
+            smoke-test-script: test/smoke_test.py
+            package-name: torchrl
+    name: pytorch/rl
+    uses: pytorch/test-infra/.github/workflows/build_wheels_linux.yml@main
+    with:
+      repository: ${{ matrix.repository }}
+      ref: ""
+      test-infra-repository: pytorch/test-infra
+      test-infra-ref: main
+      build-matrix: ${{ needs.generate-matrix.outputs.matrix }}
+      package-name: ${{ matrix.package-name }}
+      smoke-test-script: ${{ matrix.smoke-test-script }}
+      trigger-event: ${{ github.event_name }}
diff --git a/.github/workflows/build-wheels-windows.yml b/.github/workflows/build-wheels-windows.yml
@@ -0,0 +1,48 @@
+name: Build Windows Wheels
+
+on:
+  pull_request:
+  push:
+    branches:
+      - nightly
+      - main
+      - release/*
+    tags:
+        # NOTE: Binary build pipelines should only get triggered on release candidate builds
+        # Release candidate tags look like: v1.11.0-rc1
+        - v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  generate-matrix:
+    uses: pytorch/test-infra/.github/workflows/generate_binary_build_matrix.yml@main
+    with:
+      package-type: wheel
+      os: windows
+      test-infra-repository: pytorch/test-infra
+      test-infra-ref: main
+  build:
+    needs: generate-matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - repository: pytorch/rl
+            post-script: "python packaging/wheel/relocate.py"
+            smoke-test-script: test/smoke_test.py
+            package-name: torchrl
+    name: pytorch/rl
+    uses: pytorch/test-infra/.github/workflows/build_wheels_windows.yml@main
+    with:
+      repository: ${{ matrix.repository }}
+      ref: ""
+      test-infra-repository: pytorch/test-infra
+      test-infra-ref: main
+      build-matrix: ${{ needs.generate-matrix.outputs.matrix }}
+      package-name: ${{ matrix.package-name }}
+      smoke-test-script: ${{ matrix.smoke-test-script }}
+      trigger-event: ${{ github.event_name }}
diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml
@@ -1,193 +0,0 @@
-name: Wheels
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-  push:
-    branches:
-      - release/*
-
-concurrency:
-  # Documentation suggests ${{ github.head_ref }}, but that's only available on pull_request/pull_request_target triggers, so using ${{ github.ref }}.
-  # On master, we want all builds to complete even if merging happens faster to make it easier to discover at which point something broke.
-  group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && format('ci-master-{0}', github.sha) || format('ci-{0}', github.ref) }}
-  cancel-in-progress: true
-
-jobs:
-
-  build-wheel-linux:
-    runs-on: ubuntu-20.04
-    strategy:
-      matrix:
-        python_version: [["3.8", "cp38-cp38"], ["3.9", "cp39-cp39"], ["3.10", "cp310-cp310"], ["3.11", "cp311-cp311"]]
-        cuda_support: [["", "--index-url https://download.pytorch.org/whl/cpu", "\"['cpu', '11.3', '11.6']\"", "cpu"]]
-    container: pytorch/manylinux-${{ matrix.cuda_support[3] }}
-    steps:
-      - name: Checkout torchrl
-        uses: actions/checkout@v2
-      - name: Install PyTorch RC
-        run: |
-          export PATH="/opt/python/${{ matrix.python_version[1] }}/bin:$PATH"
-          python3 -mpip install torch ${{ matrix.cuda_support[1] }}
-      - name: Build wheel
-        run: |
-          export PATH="/opt/python/${{ matrix.python_version[1] }}/bin:$PATH"
-          python3 -mpip install wheel
-          TORCHRL_BUILD_VERSION=0.5.0 python3 setup.py bdist_wheel
-          # NB: wheels have the linux_x86_64 tag so we rename to manylinux1
-          # find . -name 'dist/*whl' -exec bash -c ' mv $0 ${0/linux/manylinux1}' {} \;
-      # pytorch/pytorch binaries are also manylinux_2_17 compliant but they
-      # pretend that they're manylinux1 compliant so we do the same.
-      - name: Show auditwheel output; confirm 2-17
-        run: |
-          python3 -mpip install auditwheel
-          auditwheel show dist/*
-      - name: Upload wheel for the test-wheel job
-        uses: actions/upload-artifact@v2
-        with:
-          name: torchrl-linux-${{ matrix.python_version[0] }}.whl
-          path: dist/torchrl-*.whl
-      - name: Upload wheel for download
-        uses: actions/upload-artifact@v2
-        with:
-          name: torchrl-batch.whl
-          path: dist/*.whl
-
-  build-wheel-windows:
-    runs-on: windows-latest
-    strategy:
-      matrix:
-        python_version: [["3.8", "3.8"], ["3.9", "3.9"], ["3.10", "3.10.3"], ["3.11", "3.11"]]
-    steps:
-      - name: Setup Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python_version[1] }}
-      - name: Checkout torchrl
-        uses: actions/checkout@v2
-      - name: Install PyTorch RC
-        shell: bash
-        run: |
-          python3 -mpip install torch --index-url https://download.pytorch.org/whl/cpu
-      - name: Build wheel
-        shell: bash
-        run: |
-            python3 -mpip install wheel
-            TORCHRL_BUILD_VERSION=0.5.0 python3 setup.py bdist_wheel
-      - name: Upload wheel for the test-wheel job
-        uses: actions/upload-artifact@v2
-        with:
-          name: torchrl-win-${{ matrix.python_version[0] }}.whl
-          path: dist/torchrl-*.whl
-      - name: Upload wheel for download
-        uses: actions/upload-artifact@v2
-        with:
-          name: torchrl-batch.whl
-          path: dist/*.whl
-
-
-  test-wheel:
-    needs: [build-wheel-linux]
-    strategy:
-      matrix:
-        os: [["linux", "ubuntu-20.04"]]
-        python_version: [ "3.8", "3.9", "3.10", "3.11" ]
-    runs-on: ${{ matrix.os[1] }}
-    steps:
-      - name: Setup Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python_version }}
-          architecture: x64
-      - name: Checkout torchrl
-        uses: actions/checkout@v2
-      - name: Install PyTorch RC
-        run: |
-          python3 -mpip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
-      - name: Upgrade pip
-        run: |
-          python3 -mpip install --upgrade pip
-      - name: Install tensordict
-        run: |
-          python3 -mpip install git+https://github.com/pytorch/tensordict.git
-      - name: Install test dependencies
-        run: |
-          python3 -mpip install numpy pytest pytest-cov codecov unittest-xml-reporting pillow>=4.1.1 scipy av networkx expecttest pyyaml
-      - name: Download built wheels
-        uses: actions/download-artifact@v2
-        with:
-          name: torchrl-${{ matrix.os[0] }}-${{ matrix.python_version }}.whl
-          path: /tmp/wheels
-      - name: Install built wheels
-        run: |
-          python3 -mpip install /tmp/wheels/*
-      - name: Log version string
-        run: |
-          # Avoid ambiguity of "import torchrl" by deleting the source files.
-          rm -rf torchrl/
-          python -c "import torchrl; print(torchrl.__version__)"
-      - name: Run tests
-        run: |
-          set -e
-          export IN_CI=1
-          mkdir test-reports
-          python -m torch.utils.collect_env
-          python -c "import torchrl; print(torchrl.__version__)"
-          EXIT_STATUS=0
-          pytest test/smoke_test.py -v --durations 200
-          exit $EXIT_STATUS
-
-  test-wheel-windows:
-    needs: build-wheel-windows
-    strategy:
-      matrix:
-        python_version: [ "3.8", "3.9", "3.10", "3.11" ]
-    runs-on: windows-latest
-    steps:
-      - name: Setup Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: ${{ matrix.python_version }}
-      - name: Checkout torchrl
-        uses: actions/checkout@v2
-      - name: Install PyTorch RC
-        shell: bash
-        run: |
-          python3 -mpip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
-      - name: Upgrade pip
-        shell: bash
-        run: |
-          python3 -mpip install --upgrade pip
-      - name: Install tensordict
-        shell: bash
-        run: |
-          python3 -mpip install git+https://github.com/pytorch/tensordict.git
-      - name: Install test dependencies
-        shell: bash
-        run: |
-          python3 -mpip install numpy pytest pytest-cov codecov unittest-xml-reporting pillow>=4.1.1 scipy av networkx expecttest pyyaml
-      - name: Download built wheels
-        uses: actions/download-artifact@v2
-        with:
-          name: torchrl-win-${{ matrix.python_version }}.whl
-          path: wheels
-      - name: Install built wheels
-        shell: bash
-        run: |
-          python3 -mpip install wheels/*
-      - name: Log version string
-        shell: bash
-        run: |
-          # Avoid ambiguity of "import torchrl" by deleting the source files.
-          rm -rf torchrl/
-          python -c "import torchrl; print(torchrl.__version__)"
-      - name: Run tests
-        shell: bash
-        run: |
-          set -e
-          export IN_CI=1
-          mkdir test-reports
-          python -m torch.utils.collect_env
-          python -c "import torchrl; print(torchrl.__version__)"
-          EXIT_STATUS=0
-          pytest test/smoke_test.py -v --durations 200
-          exit $EXIT_STATUS

diff --git a/docs/source/_static/js/theme.js b/docs/source/_static/js/theme.js
@@ -946,7 +946,7 @@ if (downloadNote.length >= 1) {
         tutorialUrlArray[0] = tutorialUrlArray[0] + "/sphinx-tutorials"
 
     var githubLink = "https://github.com/pytorch/rl/blob/main/" + tutorialUrlArray.join("/") + ".py",
-        notebookLink = $(".reference.download")[1].href,
+        notebookLink = $(".sphx-glr-download-jupyter").find(".download.reference")[0].href,
         notebookDownloadPath = notebookLink.split('_downloads')[1],
         colabLink = "https://colab.research.google.com/github/pytorch/rl/blob/gh-pages/main/_downloads" + notebookDownloadPath;
 

diff --git a/docs/source/_static/js/torchrl_theme.js b/docs/source/_static/js/torchrl_theme.js
@@ -945,7 +945,7 @@ if (downloadNote.length >= 1) {
     var tutorialUrlArray = $("#tutorial-type").text().split('/');
 
     var githubLink = "https://github.com/pytorch/rl/tree/tutorial_py_dup/sphinx-tutorials/" + tutorialUrlArray[tutorialUrlArray.length - 1] + ".py",
-        notebookLink = $(".reference.download")[1].href,
+        notebookLink = $(".sphx-glr-download-jupyter").find(".download.reference")[0].href,
         notebookDownloadPath = notebookLink.split('_downloads')[1],
         colabLink = "https://colab.research.google.com/github/pytorch/rl/blob/gh-pages/_downloads" + notebookDownloadPath;
 

diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
@@ -61,7 +61,7 @@
 	  if (downloadNote.length >= 1) {
 	      var tutorialUrl = $("#tutorial-type").text();
 	      var githubLink = "https://github.com/pytorch/rl/blob/main/tutorials/sphinx-tutorials/"  + tutorialUrl + ".py",
-		  notebookLink = $(".reference.download")[1].href,
+		  notebookLink = $(".sphx-glr-download-jupyter").find(".download.reference")[0].href,
 		  notebookDownloadPath = notebookLink.split('_downloads')[1],
 		  colabLink = "https://colab.research.google.com/github/pytorch/rl/blob/gh-pages/main/_downloads" + notebookDownloadPath;
 

diff --git a/docs/source/reference/knowledge_base.rst b/docs/source/reference/knowledge_base.rst
@@ -1,6 +1,8 @@
 Knowledge Base
 ==============
 
+.. _ref_knowledge_base:
+
 .. include:: ../../../knowledge_base/README.md
    :start-line: 1
    :parser: myst_parser.sphinx_

diff --git a/knowledge_base/VIDEO_CUSTOMISATION.md b/knowledge_base/VIDEO_CUSTOMISATION.md
@@ -0,0 +1,58 @@
+# Customising Video Renders
+
+## Tweaking Video Rendering Settings
+TorchRL relies heavily on the [torchvision.io](https://pytorch.org/vision/main/io.html) 
+and [PyAV](https://github.com/PyAV-Org/PyAV) modules for its video logging 
+capabilities. Though these libraries are quite convenient and powerful, it is 
+not easy to access the variety of knobs and settings at your disposal. 
+
+This guide hopes to clarify what appear to be the general principles behind
+customising video rendering, and show you how you can manually adjust your 
+rollouts' rendering settings to your liking.
+
+## General Principles
+Ultimately, [torchvision.io](https://pytorch.org/vision/main/io.html) and 
+[PyAV](https://github.com/PyAV-Org/PyAV) make calls to [FFmpeg](https://ffmpeg.org/)
+libraries in order to render videos. 
+
+In other words:
+
+- Whatever can be fed into [FFmpeg](https://ffmpeg.org/), we can also feed 
+into TorchRL's `Loggers`.
+- For any custom settings we wish to use, we must reference them from 
+[FFmpeg's documentation](https://trac.ffmpeg.org/)
+
+## Video Rendering Customization Example
+
+Suppose the following snippet gave us extremely blurry videos, even though 
+we provided it clear, frame-by-frame images to stitch together:
+```python
+from torchrl.envs import GymEnv, TransformedEnv
+from torchrl.record import CSVLogger, VideoRecorder
+
+logger = CSVLogger(exp_name="my_exp")
+env = GymEnv("CartPole-v1", from_pixels=True, pixels_only=False)
+
+recorder = VideoRecorder(logger, tag="my_video")
+record_env = TransformedEnv(env, recorder)
+rollout = record_env.rollout(max_steps=3)
+recorder.dump()
+```
+
+Since TorchRL's default video codec is [H264](https://trac.ffmpeg.org/wiki/Encode/H.264),
+the settings that we must change should be in there.
+
+For the purposes of this example, let us choose a 
+[Constant Rate Factor (CRF)](https://trac.ffmpeg.org/wiki/Encode/H.264#crf) of 
+`17` and a [preset](https://trac.ffmpeg.org/wiki/Encode/H.264#Preset) of `slow`,
+as advised by the documentation.
+
+We can improve the video quality by appending all our desired settings 
+(as keyword arguments) to `recorder` like so:
+```python
+# The arguments' types don't appear to matter too much, as long as they are
+# appropriate for Python.
+# For example, this would work as well:
+# logger = CSVLogger(exp_name="my_exp", crf=17, preset="slow")
+logger = CSVLogger(exp_name="my_exp", crf="17", preset="slow")
+```