Add placeholder for the User Guide #159379

svekars · 2025-07-29T16:51:53Z

Add pytorch_overview.md
Add pytorch_main_components.md
Reorganize top nav to have Get Started, User Guide, Reference API, Community, Tutorials
Move notes under user guide

- Add pytorch_overview.md - Add pytorch_main_components.md - Reorganize top nav to have Get Started, User Guide, Reference API, COmmunity, Tutorials - Move notes under user guide

pytorch-bot · 2025-07-29T16:51:57Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/159379

📄 Preview Python docs built from this PR
📄 Preview C++ docs built from this PR
❓ Need help or want to give feedback on the CI? Visit the bot commands wiki or our office hours

Note: Links to docs will display an error until the docs builds have been completed.

✅ You can merge normally! (4 Unrelated Failures)

As of commit bfbe0fd with merge base 59e261b ():

FLAKY - The following jobs failed but were likely due to flakiness present on trunk:

pull / linux-jammy-py3.10-clang18-asan / test (default, 5, 6, lf.linux.4xlarge) (gh) (disabled by #136125, #137026, #137027)
inductor/test_extension_backend.py::ExtensionBackendTests::test_open_device_registration
pull / linux-jammy-py3.13-clang12 / test (default, 2, 5, lf.linux.4xlarge) (gh) (disabled by #136125, #137026, #137027)
inductor/test_extension_backend.py::ExtensionBackendTests::test_open_device_registration
pull / linux-jammy-py3.9-clang12 / test (default, 5, 5, lf.linux.4xlarge) (gh) (disabled by #136125, #137026, #137027)
inductor/test_extension_backend.py::ExtensionBackendTests::test_open_device_registration
pull / linux-jammy-py3.9-gcc11 / test (default, 5, 5, lf.linux.2xlarge) (gh) (detected as infra flaky with no log or failing log classifier)

This comment was automatically generated by Dr. CI and updates every 15 minutes.

malfet · 2025-07-29T18:16:40Z

docs/source/user_guide/pytorch_overview.md

+
+# What is PyTorch?
+
+PyTorch, or torch, is an open-source machine learning library written in Python that


written in Python seems misleading...

+1, probably just drop this

zou3519 · 2025-07-30T21:46:38Z

docs/source/user_guide/pytorch_overview.md

+process can be represented as:
+
+```{math}
+\theta_{\text{new}} = \theta_{\text{old}} - \alpha \nabla_{\theta} J(\theta)


@albanD 's our mathemetician, I just look at formulas and they look approximately fine to me lol

zou3519 · 2025-07-30T21:47:34Z

docs/source/user_guide/pytorch_overview.md

+
+PyTorch can do so much more beyond the basic alarithmetic operations. It supports complex neural network architectures through
+its {mod}`torch.nn` module, provides efficient data loading utilities with {mod}
+`torch.utils.data`, and offers a suite of optimization algorithms in {mod}`torch.


torch.utils.data, torch.optim not rendering correctly

zou3519 · 2025-07-30T21:48:02Z

docs/source/user_guide/pytorch_overview.md

+```{code-cell}
+@torch.compile
+def compute(x):
+    return x**2 + 3*x
+
+x = torch.tensor([1.0, 2.0], requires_grad=True)
+y = compute(x)
+y.backward(torch.ones_like(x))
+print(y)
+print(x.grad)
+```


tf32 warning by default is not good

how should we change the code above to not have it =)?

Would adding this to the example help? Or is that doing too much?
import torch

torch.backends.cuda.matmul.fp32_precision = "tf32"
torch.backends.cudnn.conv.fp32_precision = "tf32"

zou3519 · 2025-07-30T21:48:44Z

docs/source/user_guide/pytorch_overview.md

+
+Learn more about torch.compile in the {ref}`torch.compiler_overview` section.
+
+## GPU Acceleration


I'd probably list this above torch.compile, GPU acceleration is more core to pytorch than compile.

zou3519 · 2025-07-30T21:49:13Z

docs/source/user_guide/pytorch_overview.md

+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+print(f"Using device: {device}")


If the CI runner does CPU then we should just not evaluate the code cell

zou3519 · 2025-07-30T21:49:42Z

docs/source/user_guide/pytorch_overview.md

+x = torch.randn(1000, 1000)
+x = x.to(device)


nit: Probably better to just construct it on the right device torch.randn(1000, 1000, device=device) instead of doing the movement.

zou3519 · 2025-07-30T21:50:16Z

docs/source/index.md

@@ -23,17 +23,10 @@ The APIs and performance characteristics of these features may change.
 :glob:
 :maxdepth: 2

+Get Started <https://pytorch.org/get-started/locally/>


This should be "install pytorch" or something, I don't know what "get started means"

zou3519 · 2025-07-30T21:51:53Z

docs/source/user_guide/pytorch_main_components.md

+
+* **Autograd** - PyTorch's automatic differentiation engine that tracks operations performed on tensors and builds a computational graph dynamically. It enables efficient gradient computation for backpropagation during model training with minimal overhead.
+
+* **Neural Network API** - A modular framework for building neural networks with pre-defined layers, activation functions, and loss functions. The `nn.Module` base class provides a clean interface for creating custom network architectures with parameter management.


nn.Module should link back to torch.nn.Module API somehow

zou3519 · 2025-07-30T21:52:17Z

docs/source/user_guide/pytorch_main_components.md

+  * **torch.compile** - Just-in-Time (JIT) compilation for accelerated execution. torch.compile transforms PyTorch code into optimized computational graphs at runtime. It can provide significant speedups with minimal code changes by analyzing execution patterns and applying hardware-specific optimizations.
+  * **torch.export** - Exporting models for deployment in resource-constrained environments. torch.export generates standalone artifacts that can run without the PyTorch runtime. It supports various deployment targets, including mobile, embedded, and cloud.


Ideally these link to the torch.compile API and the torch.export API, respectively. There should be some way to do this with myst-markdown

zou3519 · 2025-07-30T21:52:37Z

docs/source/user_guide/pytorch_main_components.md

+  * **Distributed Training** -  Includes data parallelism (`DistributedDataParallel`), model parallelism, and pipeline parallelism options. Supports communication backends like NCCL and Gloo for efficient multi-node training. **`Fully Sharded Data Parallel`(FSDP2)** provides memory-efficient training for large models by sharding model parameters, gradients, and optimizer states across devices while maintaining training efficiency.
+  * **Profiling and Monitoring** - Tools like `torch.profiler` help identify bottlenecks, visualize execution traces, and monitor resource utilization during training and inference.


Ditto here- DDP, torch.profiler, should link back to their doc pages.

docs/source/user_guide/pytorch_main_components.md

malfet · 2025-07-31T19:52:23Z

docs/source/user_guide/pytorch_main_components.md

+
+* **Tensors** ({class}`torch.tensor`)- N-dimensional arrays that serve as PyTorch's fundamental
+data structure. They support automatic differentiation, GPU acceleration, and provide a comprehensive
+API for mathematical operations. Tensors can seamlessly move between CPU and GPU for


Tensors can seamlessly move between CPU and GPU

Not sure I agree with that statement

I don't either. Let's delete it

malfet · 2025-07-31T19:53:51Z

docs/source/user_guide/pytorch_main_components.md

+## PyTorch Components for Production-Grade Performance and Deployment
+
+PyTorch extends beyond basic deep learning capabilities with advanced features designed for
+production-grade performance and deployment. These components optimize model execution,
+reduce resource requirements, and enable scaling across multiple compute devices.
+These components include:


Should we remove this section and just leave torch.compile here?

malfet · 2025-07-31T19:54:43Z

docs/source/user_guide/pytorch_main_components.md

+resource-constrained environments. torch.export generates standalone artifacts
+that can run without the PyTorch runtime. It supports various deployment targets,
+including mobile, embedded, and cloud.
+* **Inductor** ([TorchInductor](../torch.compiler_inductor_profiling.html))- The default backend


Why it needs to be there? I.e. aren't inductor a compiler internal implementation details that could be added later?

I'm fine with deleting Inductor and AOTInductor together

malfet · 2025-07-31T19:55:23Z

docs/source/user_guide/pytorch_main_components.md

+* **AOTInductor** ({ref}`torch.compiler_aot_inductor`)- Compiles models Ahead-Of-Time (AOT) for deployment environments
+where JIT compilation isn't feasible. **AOTInductor** generates standalone artifacts
+that can run without the PyTorch runtime.


cc: @albanD
Shouldn't it be called something else? (Or again, may be removed from top-level menu?)

malfet · 2025-07-31T19:57:07Z

docs/source/user_guide/pytorch_main_components.md

+where JIT compilation isn't feasible. **AOTInductor** generates standalone artifacts
+that can run without the PyTorch runtime.
+
+### Deployment and Optimization


Should it be called something else? At least I don't see a single deployment framework/technology/API mentioned there

albanD

What in this PR is causing the top bar to change between this and trunk?

docs/source/index.md

albanD · 2025-08-01T18:53:17Z

docs/source/user_guide/index.md

+ecosystem of tools and libraries. Whether you are a beginner or an
+experienced practitioner, this guide will help you harness the power
+of PyTorch to create and deploy machine learning models effectively.


Suggested change

ecosystem of tools and libraries. Whether you are a beginner or an

experienced practitioner, this guide will help you harness the power

of PyTorch to create and deploy machine learning models effectively.

ecosystem of tools and libraries.

albanD · 2025-08-01T18:56:53Z

docs/source/user_guide/pytorch_overview.md

@@ -0,0 +1,107 @@
+---


I would remove this page and point to the tutorial intro: as done below: https://docs.pytorch.org/tutorials/beginner/basics/intro.html

The overall intro the done more in depth there and the two particular examples here don't really work right now and I don't think it's worth blocking this page on fixing them.

I think keeping this actually helps (assuming fixing the examples isnt a big issue). This doc provides a quick overview without getting too lost in the weeds especially for those users who dont need to go into ML basics but want a quick overview of PyTorch. The page does still link to Learn the basics for those who need it and as suck the two complement each other.

Plus for seo purposes this is one more thing that can surface and bring users to the necessary pages.

If fixing the examples would take a lot, we could take those out for now since it is a work in progress anyways.

The specific examples here look very weird and I expect will be a lot of work to cleanup.
You can make this just a link to the starting tutorial if you want though.

@albanD took the examples out and just left a basic overview. I do think an overview with basic examples would be good but I agree that we cant let the examples hold up landing his and getting work done on it. Let me know what you think.

albanD · 2025-08-01T18:58:08Z

docs/source/user_guide/pytorch_main_components.md

+
+* **Tensors** ({class}`torch.tensor`)- N-dimensional arrays that serve as PyTorch's fundamental
+data structure. They support automatic differentiation, GPU acceleration, and provide a comprehensive
+API for mathematical operations. Tensors can seamlessly move between CPU and GPU for


I don't either. Let's delete it

albanD · 2025-08-01T18:58:47Z

docs/source/user_guide/pytorch_main_components.md

+
+Some of the basic PyTorch components include:
+
+* **Tensors** ({class}`torch.tensor`)- N-dimensional arrays that serve as PyTorch's fundamental


not sure what the class/module below try to do but these don't work. Let's remove

albanD · 2025-08-01T18:59:56Z

docs/source/user_guide/pytorch_main_components.md

+graph dynamically. It enables efficient gradient computation for backpropagation
+during model training with minimal overhead.


Suggested change

graph dynamically. It enables efficient gradient computation for backpropagation

during model training with minimal overhead.

graph dynamically to be able to compute gradients.

albanD · 2025-08-01T19:00:19Z

docs/source/user_guide/pytorch_main_components.md

+during model training with minimal overhead.
+
+* **Neural Network API** ({mod}`nn.Module`)- A modular framework for building neural networks with pre-defined layers,
+activation functions, and loss functions. The {mod}`nn.Module` base class provides a clean interface


these don't really work as links. Not sure if that's expected

Removed them for now

albanD · 2025-08-01T19:01:05Z

docs/source/user_guide/pytorch_main_components.md

+
+## PyTorch Components for Production-Grade Performance and Deployment
+
+PyTorch extends beyond basic deep learning capabilities with advanced features designed for
+production-grade performance and deployment. These components optimize model execution,
+reduce resource requirements, and enable scaling across multiple compute devices.
+These components include:


Suggested change

## PyTorch Components for Production-Grade Performance and Deployment

PyTorch extends beyond basic deep learning capabilities with advanced features designed for

production-grade performance and deployment. These components optimize model execution,

reduce resource requirements, and enable scaling across multiple compute devices.

These components include:

agreed with Nikita, that doesn't exist today

albanD · 2025-08-01T19:01:49Z

docs/source/user_guide/pytorch_main_components.md

+reduce resource requirements. It includes:
+* **torch.compile** ({func}`torch.compile`)- Just-in-Time (JIT) compilation for accelerated execution.
+torch.compile transforms PyTorch code into optimized computational graphs at runtime.
+It can provide significant speedups with minimal code changes by analyzing execution
+patterns and applying hardware-specific optimizations.
+* **torch.export** ({func}`torch.export`)- Exporting models for deployment in
+resource-constrained environments. torch.export generates standalone artifacts
+that can run without the PyTorch runtime. It supports various deployment targets,
+including mobile, embedded, and cloud.
+* **Inductor** ([TorchInductor](../torch.compiler_inductor_profiling.html))- The default backend
+for {func}`torch.compile` that converts PyTorch operations
+into efficient machine code. Uses TorchIR as an intermediate representation to apply
+optimizations like operator fusion, memory planning, and loop transformations.
+* **AOTInductor** ({ref}`torch.compiler_aot_inductor`)- Compiles models Ahead-Of-Time (AOT) for deployment environments
+where JIT compilation isn't feasible. **AOTInductor** generates standalone artifacts
+that can run without the PyTorch runtime.


Suggested change

reduce resource requirements. It includes:

* **torch.compile** ({func}`torch.compile`)- Just-in-Time (JIT) compilation for accelerated execution.

torch.compile transforms PyTorch code into optimized computational graphs at runtime.

It can provide significant speedups with minimal code changes by analyzing execution

patterns and applying hardware-specific optimizations.

* **torch.export** ({func}`torch.export`)- Exporting models for deployment in

resource-constrained environments. torch.export generates standalone artifacts

that can run without the PyTorch runtime. It supports various deployment targets,

including mobile, embedded, and cloud.

* **Inductor** ([TorchInductor](../torch.compiler_inductor_profiling.html))- The default backend

for {func}`torch.compile` that converts PyTorch operations

into efficient machine code. Uses TorchIR as an intermediate representation to apply

optimizations like operator fusion, memory planning, and loop transformations.

* **AOTInductor** ({ref}`torch.compiler_aot_inductor`)- Compiles models Ahead-Of-Time (AOT) for deployment environments

where JIT compilation isn't feasible. **AOTInductor** generates standalone artifacts

that can run without the PyTorch runtime.

reduce resource requirements.

Let's just link to the compiler page from here.

albanD · 2025-08-01T19:04:12Z

docs/source/user_guide/pytorch_main_components.md

+### Deployment and Optimization
+
+PyTorch provides tools for optimizing model performance and deployment in various environments. These include:
+
+* **Quantization** ([torchao](https://docs.pytorch.org/ao/stable/index.html))- Precision-reduction
+techniques for model efficiency. Qunatization features of PyTorch reduce model precision
+from 32-bit to 8-bit or lower formats. They support post-training quantization, quantization-aware training, and dynamic
+quantization to balance accuracy and efficiency.
+* **Edge Deployment** ([Executorch](../index.html))- ExecuTorch is a PyTorch-compatible library that supports
+resource-constrained environments.
+* **Distributed Training** ([torch.distributed](../distributed.html)) -  Includes data parallelism (`DistributedDataParallel`),
+model parallelism, and pipeline parallelism options. Supports communication backends
+like NCCL and Gloo for efficient multi-node training. **`Fully Sharded Data Parallel`(FSDP2)** provides
+memory-efficient training for large models by sharding model parameters, gradients,
+and optimizer states across devices while maintaining training efficiency.
+* **Profiling and Monitoring** - Tools like {class}`torch.profiler` help identify bottlenecks,
+visualize execution traces, and monitor resource utilization during training and inference.


Suggested change

### Deployment and Optimization

PyTorch provides tools for optimizing model performance and deployment in various environments. These include:

* **Quantization** ([torchao](https://docs.pytorch.org/ao/stable/index.html))- Precision-reduction

techniques for model efficiency. Qunatization features of PyTorch reduce model precision

from 32-bit to 8-bit or lower formats. They support post-training quantization, quantization-aware training, and dynamic

quantization to balance accuracy and efficiency.

* **Edge Deployment** ([Executorch](../index.html))- ExecuTorch is a PyTorch-compatible library that supports

resource-constrained environments.

* **Distributed Training** ([torch.distributed](../distributed.html)) - Includes data parallelism (`DistributedDataParallel`),

model parallelism, and pipeline parallelism options. Supports communication backends

like NCCL and Gloo for efficient multi-node training. **`Fully Sharded Data Parallel`(FSDP2)** provides

memory-efficient training for large models by sharding model parameters, gradients,

and optimizer states across devices while maintaining training efficiency.

* **Profiling and Monitoring** - Tools like {class}`torch.profiler` help identify bottlenecks,

visualize execution traces, and monitor resource utilization during training and inference.

Not sure what we're trying to do here, let's delete for v0 and we can discuss later to add things back

Co-authored-by: Nikita Shulga <2453524+malfet@users.noreply.github.com>

albanD

Final rendering looks off ?

albanD · 2025-08-05T17:35:36Z

docs/source/user_guide/pytorch_overview.md

@@ -0,0 +1,107 @@
+---


The specific examples here look very weird and I expect will be a lot of work to cleanup.
You can make this just a link to the starting tutorial if you want though.

albanD

Thanks!

Add placeholder for the User Guide

4dddf07

- Add pytorch_overview.md - Add pytorch_main_components.md - Reorganize top nav to have Get Started, User Guide, Reference API, COmmunity, Tutorials - Move notes under user guide

svekars requested review from zou3519 and albanD July 29, 2025 16:51

svekars added the topic: not user facing topic category label Jul 29, 2025

svekars added module: docs Related to our documentation, both in docs/ and docblocks topic: docs topic category labels Jul 29, 2025

malfet reviewed Jul 29, 2025

View reviewed changes

Update

8c8ae0e

svekars force-pushed the add-user-guide-structure branch from ee86c94 to 8c8ae0e Compare July 29, 2025 23:29

svekars added 3 commits July 29, 2025 18:13

Fix lint

df39c71

Update

7ede97b

Update index.md

7e6d84d

zou3519 reviewed Jul 30, 2025

View reviewed changes

svekars added 3 commits July 30, 2025 14:56

Update pytorch_overview.md

7cf97d2

Update index.md

24f0a6a

Addressed comments - added links to corresponding docs

72ec1e4

malfet reviewed Jul 31, 2025

View reviewed changes

albanD reviewed Aug 1, 2025

View reviewed changes

docs/source/index.md Show resolved Hide resolved

albanD reviewed Aug 1, 2025

View reviewed changes

Update docs/source/user_guide/pytorch_main_components.md

30d65d3

Co-authored-by: Nikita Shulga <2453524+malfet@users.noreply.github.com>

sekyondaMeta added 3 commits August 4, 2025 10:22

Update index.md

16c070f

Update pytorch_main_components.md

6328675

Update index.md

cf19dc1

albanD reviewed Aug 5, 2025

View reviewed changes

sekyondaMeta added 5 commits August 7, 2025 15:25

Update pytorch_overview.md

0840b2c

Update pytorch_overview.md

838b85d

Update pytorch_main_components.md

2621566

Update index.md

b7adca6

Delete docs/source/user_guide/pytorch_overview.md

bfbe0fd

albanD approved these changes Aug 12, 2025

View reviewed changes


		# What is PyTorch?

		PyTorch, or torch, is an open-source machine learning library written in Python that


		Learn more about torch.compile in the {ref}`torch.compiler_overview` section.

		## GPU Acceleration

		device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
		print(f"Using device: {device}")


		* Autograd - PyTorch's automatic differentiation engine that tracks operations performed on tensors and builds a computational graph dynamically. It enables efficient gradient computation for backpropagation during model training with minimal overhead.

		* Neural Network API - A modular framework for building neural networks with pre-defined layers, activation functions, and loss functions. The `nn.Module` base class provides a clean interface for creating custom network architectures with parameter management.

		* torch.compile - Just-in-Time (JIT) compilation for accelerated execution. torch.compile transforms PyTorch code into optimized computational graphs at runtime. It can provide significant speedups with minimal code changes by analyzing execution patterns and applying hardware-specific optimizations.
		* torch.export - Exporting models for deployment in resource-constrained environments. torch.export generates standalone artifacts that can run without the PyTorch runtime. It supports various deployment targets, including mobile, embedded, and cloud.

		* Distributed Training - Includes data parallelism (`DistributedDataParallel`), model parallelism, and pipeline parallelism options. Supports communication backends like NCCL and Gloo for efficient multi-node training. `Fully Sharded Data Parallel`(FSDP2) provides memory-efficient training for large models by sharding model parameters, gradients, and optimizer states across devices while maintaining training efficiency.
		* Profiling and Monitoring - Tools like `torch.profiler` help identify bottlenecks, visualize execution traces, and monitor resource utilization during training and inference.


		Some of the basic PyTorch components include:

		* Tensors ({class}`torch.tensor`)- N-dimensional arrays that serve as PyTorch's fundamental

		graph dynamically. It enables efficient gradient computation for backpropagation
		during model training with minimal overhead.

	graph dynamically. It enables efficient gradient computation for backpropagation
	during model training with minimal overhead.
	graph dynamically to be able to compute gradients.

Add placeholder for the User Guide #159379

Are you sure you want to change the base?

Add placeholder for the User Guide #159379

Conversation

svekars commented Jul 29, 2025 • edited by pytorch-bot bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pytorch-bot bot commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/159379

✅ You can merge normally! (4 Unrelated Failures)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

albanD left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

svekars commented Jul 29, 2025 •

edited by pytorch-bot bot

Loading

pytorch-bot bot commented Jul 29, 2025 •

edited

Loading