From 6f4f32390ad1d4a66df83e38ac14440f6c5fb010 Mon Sep 17 00:00:00 2001
From: TerryCE <100383566+TerryCE@users.noreply.github.com>
Date: Tue, 24 May 2022 18:27:05 -0700
Subject: [PATCH 1/6] Create
2022-5-24-how-computational-graphs-are-executed-in-pytorch.md
---
...tational-graphs-are-executed-in-pytorch.md | 1094 +++++++++++++++++
1 file changed, 1094 insertions(+)
create mode 100644 _posts/2022-5-24-how-computational-graphs-are-executed-in-pytorch.md
diff --git a/_posts/2022-5-24-how-computational-graphs-are-executed-in-pytorch.md b/_posts/2022-5-24-how-computational-graphs-are-executed-in-pytorch.md
new file mode 100644
index 000000000000..e1e50c5e1d4c
--- /dev/null
+++ b/_posts/2022-5-24-how-computational-graphs-are-executed-in-pytorch.md
@@ -0,0 +1,1094 @@
+---
+layout: blog_detail
+title: "How Computational Graphs are Executed in PyTorch"
+author: Preferred Networks
+featured-img: ""
+---
+
+Welcome to the last entry into understanding the autograd engine of PyTorch series!
+If you haven’t read parts [1](https://pytorch.org/blog/overview-of-pytorch-autograd-engine/) & [2](https://pytorch.org/blog/computational-graphs-constructed-in-pytorch/) check them now to understand how PyTorch creates the computational graph for the backward pass!
+
+This post is based on PyTorch v1.11, so some highlighted parts may differ across versions.
+
+# PyTorch autograd graph execution
+
+The last post showed how PyTorch constructs the graph to calculate the outputs' derivatives w.r.t. the inputs when executing the forward pass. Now we will see how the execution of the backward pass is coordinated and done by looking at the whole process, starting from Python down to the lower C++ level internals.
+
+# What Happens when Calling `backward()`/`grad()` from Python
+## Using `variable.backward()`
+
+After doing all our calculations with an input set to require the gradient, we call `.backward()` on the result to initiate the backward pass execution.
+
+```python
+>>> x = torch.tensor([0.5, 0.75], requires_grad=True)
+>>> y = torch.exp(x).sum()
+>>> y.backward()
+```
+
+Calling [`.backward()`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/_tensor.py#L307-L363) on a tensor results in a call to [`torch.autograd.backward()`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/autograd/__init__.py#L85-L175).
+```python
+# torch/_tensor.py
+
+def backward(self, gradient=None, retain_graph=None, create_graph=False, inputs=None):
+ …
+ torch.autograd.backward(self, gradient, retain_graph, create_graph, inputs=inputs)
+
+```
+`torch.autograd.backward()` checks the arguments and calls the autograd engine in the C++ layer.
+
+``` python
+def backward(
+ tensors: _TensorOrTensors,
+ grad_tensors: Optional[_TensorOrTensors] = None,
+ retain_graph: Optional[bool] = None,
+ create_graph: bool = False,
+ grad_variables: Optional[_TensorOrTensors] = None,
+ inputs: Optional[_TensorOrTensors] = None,
+) -> None:
+ …
+
+ if inputs is not None and len(inputs) == 0:
+ raise RuntimeError("'inputs' argument to backward() cannot be empty.")
+
+ tensors = (tensors,) if isinstance(tensors, torch.Tensor) else tuple(tensors)
+ inputs = (inputs,) if isinstance(inputs, torch.Tensor) else \
+ tuple(inputs) if inputs is not None else tuple()
+
+ grad_tensors_ = _tensor_or_tensors_to_tuple(grad_tensors, len(tensors))
+ grad_tensors_ = _make_grads(tensors, grad_tensors_)
+ if retain_graph is None:
+ retain_graph = create_graph
+
+ Variable._execution_engine.run_backward(
+ tensors, grad_tensors_, retain_graph, create_graph, inputs,
+ allow_unreachable=True, accumulate_grad=True) # allow_unreachable flag
+
+```
+First, whether the `grad_tensors` argument was specified or not, there is a call to the [`_make_grads`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/autograd/__init__.py#L30-L74) function. This is used to check the provided `grad_tensors` or to specify the default value for them by looking at the `tensors` argument values’ shapes. Check the first blog post for details on the default value for the `grad_tensors` of the backward pass. This function just provides the vector of the vector jacobian product if it was not initially specified.
+
+In the above code, `Variable` has an `_execution_engine` attribute that is defined in [`torch.autograd.variable`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/autograd/variable.py#L14) to be of type `ImperativeEngine`; the C++ engine exported to python and declared in [`torch/csrc/autograd/python_engine.cpp`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/python_engine.cpp#L384). In the following sections, we explain in detail how this object executes the backward pass.
+
+Note that the `torch.autograd.backward` function has an `inputs` optional argument. This argument is used when we want to calculate the `.grad` field of only a subset of input tensors in the forward pass.
+
+```python
+>>> x = torch.tensor([0.5, 0.75], requires_grad=True)
+>>> y = torch.tensor([0.1, 0.90], requires_grad=True)
+>>> z = torch.exp(x * y).sum()
+>>> torch.autograd.backward([z], inputs=[x])
+>>> x.grad
+tensor([0.1051, 1.7676])
+>>> y.grad # None
+>>>
+
+```
+## Using `torch.autograd.grad`
+
+An alternative to `backward()` is to use [`torch.autograd.grad()`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/autograd/__init__.py#L177-L277). The main difference to `backward()` is that `grad()` returns a tuple of tensors with the gradients of the `outputs` w.r.t. the `inputs` kwargs instead of storing them in the `.grad` field of the tensors. As you can see, the `grad()` code shown below is very similar to backward.
+
+```python
+def grad(
+ outputs: _TensorOrTensors,
+ inputs: _TensorOrTensors,
+ grad_outputs: Optional[_TensorOrTensors] = None,
+ retain_graph: Optional[bool] = None,
+ create_graph: bool = False,
+ only_inputs: bool = True,
+ allow_unused: bool = False,
+ is_grads_batched: bool = False
+) -> Tuple[torch.Tensor, ...]:
+
+ outputs = (outputs,) if isinstance(outputs, torch.Tensor) else tuple(outputs)
+ inputs = (inputs,) if isinstance(inputs, torch.Tensor) else tuple(inputs)
+ overridable_args = outputs + inputs
+ if has_torch_function(overridable_args):
+ return handle_torch_function(
+ grad,
+ overridable_args,
+ outputs,
+ inputs,
+ grad_outputs=grad_outputs,
+ retain_graph=retain_graph,
+ create_graph=create_graph,
+ only_inputs=only_inputs,
+ allow_unused=allow_unused,
+ )
+
+ grad_outputs_ = _tensor_or_tensors_to_tuple(grad_outputs, len(outputs))
+ grad_outputs_ = _make_grads(outputs, grad_outputs_)
+
+ if retain_graph is None:
+ retain_graph = create_graph
+
+ if is_grads_batched:
+ # …. It will not be covered here
+ else:
+ return Variable._execution_engine.run_backward(
+ outputs, grad_outputs_, retain_graph, create_graph, inputs,
+ allow_unused, accumulate_grad=False) # Calls into the C++ engine to run the backward pass
+
+```
+
+Figure 1 shows the computational graph with the `backward()` and `grad()` arguments highlighted in red and blue, respectively:
+
+
+ 
+
+
+
+Fgiure 1: Correspondence of `backward`/`grad` arguments in the graphs.
+
+
+# Going Inside the Autograd Engine
+
+## Refreshing Concepts: Nodes and Edges
+
+As we saw in [2](https://pytorch.org/blog/computational-graphs-constructed-in-pytorch/)
+The computational graph comprises `Node` and `Edge` objects. Please read that post if you haven’t done it yet.
+
+### Nodes
+
+`Node` objects are defined in [`torch/csrc/autograd/function.h`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/function.h#L105-L176), and they provide an overload of `operator()` for the associated function and a list of edges to do the graph traversal. Note that `Node` is a base class that autograd functions inherit from and override the `apply` method to execute the backward function.
+```c++
+struct TORCH_API Node : std::enable_shared_from_this {
+ ...
+ /// Evaluates the function on the given inputs and returns the result of the
+ /// function call.
+ variable_list operator()(variable_list&& inputs) {
+ ...
+ }
+
+protected:
+ /// Performs the `Node`'s actual operation.
+ virtual variable_list apply(variable_list&& inputs) = 0;
+ …
+ edge_list next_edges_;
+ uint64_t topological_nr_ = 0;
+ …
+
+```
+
+There is an attribute called [`topological_nr_`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/function.h#L481) in every node object. This number is used to optimize the graph execution as it allows to discard of graph branches under certain conditions. The topological number is the longest distance between this node and any leaf node and it is shown in Figure 2. Its main property is that for any pair of nodes `x`, `y` in a directed graph `topo_nr(x) < topo_nr(y)` means that there is no path from `x` to `y`. So this allows for reducing the number of paths in the graph in need of traversal. Check the [topological_nr](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/function.h#L314-L343)
+) method comment for further details.
+
+
+ 
+
+
+
+Figure 2: Example of the Topological Number calculation
+
+
+### Edges
+
+The [`Edge`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/edge.h#L14-L39) object links `Node`s together, and its implementation is straightforward.
+
+```c++
+struct Edge {
+ ...
+ /// The function this `Edge` points to.
+ std::shared_ptr function;
+ /// The identifier of a particular input to the function.
+ uint32_t input_nr;
+};
+
+```
+
+It only requires a function pointer to the `Node` and an input number that is the index of the output from the forward function this edge points to. When preparing the set of gradients before calling "function", we know that what is flowing from this edge should be accumulated in the "input_nr"th argument. Note that the input/output name is flipped here and this is the input to the backward function.
+ `Edge` objects are constructed using the [`gradient_edge`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/variable.cpp#L221-L233) function method.
+
+```c++
+ Edge gradient_edge(const Variable& self) {
+ if (const auto& gradient = self.grad_fn()) {
+ return Edge(gradient, self.output_nr());
+ } else {
+ return Edge(grad_accumulator(self), 0);
+ }
+ }
+
+```
+## Entering the C++ Realm
+
+Once that `torch.autograd.backward()` has been invoked, the
+[`THPEngine_run_backward`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/python_engine.cpp#L152-L286) routine starts the graph traversal. Following is a schema of the function body:
+```c++
+PyObject *THPEngine_run_backward(PyObject *self, PyObject *args, PyObject *kwargs)
+{
+ HANDLE_TH_ERRORS
+ PyObject *tensors = nullptr;
+ PyObject *grad_tensors = nullptr;
+ unsigned char keep_graph = 0;
+ unsigned char create_graph = 0;
+ PyObject *inputs = nullptr;
+
+ // Convert the python arguments to C++ objects
+ const char *accepted_kwargs[] = { // NOLINT
+ "tensors", "grad_tensors", "keep_graph", "create_graph", "inputs",
+ "allow_unreachable", "accumulate_grad", nullptr
+ };
+ if (!PyArg_ParseTupleAndKeywords(args, kwargs, "OObb|Obb", (char**)accepted_kwargs,
+ &tensors, &grad_tensors, &keep_graph, &create_graph, &inputs, &allow_unreachable, &accumulate_grad))
+
+ // Prepare arguments
+ for(const auto i : c10::irange(num_tensors)) {
+ // Check that the tensors require gradients
+ }
+
+ std::vector output_edges;
+ if (inputs != nullptr) {
+ // Prepare outputs
+ }
+
+ {
+ // Calls the actual autograd engine
+ pybind11::gil_scoped_release no_gil;
+ outputs = engine.execute(roots, grads, keep_graph, create_graph, accumulate_grad, output_edges);
+ }
+ // Clean up and finish
+}
+
+```
+
+First, we prepare the input arguments after converting the `PyObject` arguments to actual C++ objects. The `tensors` list contains the tensors from which we start the backward pass. These tensors are converted to edges using `torch::autograd::impl::gradient_edge` and added to a list called `roots` where the graph traversal starts.
+
+
+```c++
+ edge_list roots;
+ roots.reserve(num_tensors);
+ variable_list grads;
+ grads.reserve(num_tensors);
+ for(const auto i : c10::irange(num_tensors)) {
+ PyObject *_tensor = PyTuple_GET_ITEM(tensors, i);
+ const auto& variable = THPVariable_Unpack(_tensor);
+ auto gradient_edge = torch::autograd::impl::gradient_edge(variable);
+ roots.push_back(std::move(gradient_edge));
+
+ PyObject *grad = PyTuple_GET_ITEM(grad_tensors, i);
+ if (THPVariable_Check(grad)) {
+ const Variable& grad_var = THPVariable_Unpack(grad);
+ grads.push_back(grad_var);
+ }
+ }
+
+```
+
+Now, if the `inputs` argument was specified in `backward` or we used the `torch.autograd.grad` api, the following code creates a list of edges to accumulate the gradients in the specified tensors at the end of the computation. The engine uses this later to optimize the execution as it doesn’t add the gradients in all the leaf nodes, just the specified ones.
+
+```c++
+ std::vector output_edges;
+ if (inputs != nullptr) {
+ int num_inputs = PyTuple_GET_SIZE(inputs);
+ output_edges.reserve(num_inputs);
+ for (const auto i : c10::irange(num_inputs)) {
+ PyObject *input = PyTuple_GET_ITEM(inputs, i);
+ const auto& tensor = THPVariable_Unpack(input);
+ const auto output_nr = tensor.output_nr();
+ auto grad_fn = tensor.grad_fn();
+ if (!grad_fn) {
+ grad_fn = torch::autograd::impl::try_get_grad_accumulator(tensor);
+ }
+ if (accumulate_grad) {
+ tensor.retain_grad();
+ }
+ if (!grad_fn) {
+ output_edges.emplace_back(std::make_shared(), 0);
+ } else {
+ output_edges.emplace_back(grad_fn, output_nr);
+ }
+ }
+ }
+
+```
+
+The next step is the actual graph traversal and node function execution, and finally, the cleanup and return.
+
+```c++
+ {
+ // Calls the actual autograd engine
+ pybind11::gil_scoped_release no_gil;
+ auto& engine = python::PythonEngine::get_python_engine();
+ outputs = engine.execute(roots, grads, keep_graph, create_graph, accumulate_grad, output_edges);
+ }
+ // Clean up and finish
+}
+
+```
+
+# Starting the Real Execution
+
+`engine.execute`is present in [torch/csrc/autograd/engine.cpp](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L969-L1044)
+
+There are two differentiated steps here:
+
+Analyze the graph to find dependencies between functions
+Create worker threads that traverse the graph
+
+## Data Structures Used for the Execution
+
+### GraphTask
+
+All the execution metadata is managed by the [`GraphTask`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L51-L196) class in [torch/csrc/autograd/engine.h](https://github.com/pytorch/pytorch/blob/release/1.11/torch/csrc/autograd/engine.h)
+
+```c++
+struct GraphTask: std::enable_shared_from_this {
+ std::atomic outstanding_tasks_{0};
+ // …
+ std::unordered_map not_ready_;
+ std::unordered_map dependencies_;
+
+ struct ExecInfo {
+ // …
+ };
+ std::unordered_map exec_info_;
+ std::vector captured_vars_;
+ // …
+ std::shared_ptr cpu_ready_queue_;
+};
+
+```
+
+Here we see a series of variables dedicated to maintaining the execution state.
+`outstanding_tasks_` tracks the number of tasks left to be executed for the backward pass to complete. `not_ready_` holds the input arguments for the `Node`s that are not ready to be executed. `dependencies_` track the number of predecessors that a `Node` has. As the count reaches `0`, the `Node` is ready for execution; it is placed in a ready queue to be retrieved and executed later.
+
+`exec_info_` and the associated `ExecInfo` struct are used only when the `inputs` argument is specified or it is a call to `autograd.grad()`. They allow filter paths on the graph that are not needeed since only the gradients are calculated only for the variables in the `inputs` list.
+
+ `captured_vars_` is where the results of the graph execution are temporarily stored if we used the `torch.autograd.grad()` api instead of `torch.autograd.backward()` since `grad()` returns the gradients as tensors instead of just filling the `.grad` field of the inputs.
+
+
+### NodeTask
+
+The [`NodeTask`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L210-L242) struct is a basic class that holds an `fn_` pointer to the node to execute, and an `inputs_` buffer to store the input arguments to this function. Note that the functions executed by the backward pass are the derivatives specified in the `derivatives.yaml` file. or the user provided backward function when using custom functions as described in the second blog post.
+
+The `inputs_` buffer is also where the output gradients of the previously executed functions are aggregated, and it is defined as a [`std::vector` container](https://github.com/pytorch/pytorch/blob/release/1.10/torch/csrc/autograd/input_buffer.h) with facilities to accumulate values at a given position.
+
+```c++
+struct NodeTask {
+ std::weak_ptr base_;
+ std::shared_ptr fn_;
+ // This buffer serves as an implicit "addition" node for all of the
+ // gradients flowing here. Once all the dependencies are finished, we
+ // use the contents of this buffer to run the function.
+ InputBuffer inputs_;
+};
+
+```
+### GraphRoot
+
+The [`GraphRoot`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/functions/basic_ops.h#L72-L89) is a special function used to hold multiple input variables in a single place. The code is pretty simple as it only acts as a container of variables.
+
+```c++
+struct TORCH_API GraphRoot : public Node {
+ GraphRoot(edge_list functions, variable_list inputs)
+ : Node(std::move(functions)),
+ outputs(std::move(inputs)) {
+ for (const auto& t : outputs) {
+ add_input_metadata(t);
+ }
+ }
+
+ variable_list apply(variable_list&& inputs) override {
+ return outputs;
+ }
+
+```
+
+### AccumulateGrad
+
+This function is set during the graph creation in `gradient_edge` when the `Variable` object doesn’t have a `grad_fn`. This is, it is a leaf node.
+
+```c++
+ if (const auto& gradient = self.grad_fn()) {
+ // …
+ } else {
+ return Edge(grad_accumulator(self), 0);
+ }
+
+```
+
+The function body is defined in [`torch/csrc/autograd/functions/accumulate_grad.cpp`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/functions/accumulate_grad.cpp#L25-L63) and it essentially accumulates the input grads in the object’s `.grad` attribute.
+
+```c++
+auto AccumulateGrad::apply(variable_list&& grads) -> variable_list {
+ check_input_variables("AccumulateGrad", grads, 1, 0);
+ …
+
+ at::Tensor new_grad = callHooks(variable, std::move(grads[0]));
+ std::lock_guard lock(mutex_);
+
+ at::Tensor& grad = variable.mutable_grad();
+ accumulateGrad(
+ variable,
+ grad,
+ new_grad,
+ 1 + !post_hooks().empty() /* num_expected_refs */,
+ [&grad](at::Tensor&& grad_update) { grad = std::move(grad_update); });
+ return variable_list();
+}
+}} // namespace torch::autograd
+
+
+
+```
+
+[`accumulateGrad`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/functions/accumulate_grad.h#L100)
+does several checks on the tensors format and eventually performs the `variable_grad += new_grad;` accumulation.
+
+## Preparing the graph for execution
+
+Now, let’s walk through [`Engine::execute`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L969-L1126). The first thing to do besides arguments consistency checks is to create the actual `GraphTask` object we described above. This object keeps all the metadata of the graph execution.
+
+```c++
+auto Engine::execute(const edge_list& roots,
+ const variable_list& inputs,
+ bool keep_graph,
+ bool create_graph,
+ bool accumulate_grad,
+ const edge_list& outputs) -> variable_list {
+
+ validate_outputs(roots, const_cast(inputs), [](const std::string& msg) {
+ return msg;
+ });
+
+ // Checks
+
+ auto graph_task = std::make_shared(
+ /* keep_graph */ keep_graph,
+ /* create_graph */ create_graph,
+ /* depth */ not_reentrant_backward_call ? 0 : total_depth + 1,
+ /* cpu_ready_queue */ local_ready_queue);
+
+ // If we receive a single root, skip creating extra root node
+ // …
+ // Prepare graph by computing dependencies
+ // …
+ // Queue the root
+ // …
+ // launch execution
+ // …
+}
+
+```
+
+After creating the `GraphTask`, we use its associated function if we only have one root node. If we have multiple root nodes, we create a special `GraphRoot` object as described before.
+
+```c++
+ bool skip_dummy_node = roots.size() == 1;
+ auto graph_root = skip_dummy_node ?
+ roots.at(0).function :
+ std::make_shared(roots, inputs);
+
+```
+
+The next step is to fill the `dependencies_` map in the `GraphTask` object since the engine must know when it can execute a task. The `outputs` here is the `inputs` argument passed to the `torch.autograd.backward()` call in Python. But here, we have reversed the names since the gradients w.r.t. the inputs of the forward pass are now the outputs of the backward pass. And from now on, there is no concept of forward/backward, but only graph traversal and execution.
+
+```c++
+ auto min_topo_nr = compute_min_topological_nr(outputs);
+ // Now compute the dependencies for all executable functions
+ compute_dependencies(graph_root.get(), *graph_task, min_topo_nr);
+
+ if (!outputs.empty()) {
+ graph_task->init_to_execute(*graph_root, outputs, accumulate_grad, min_topo_nr);
+ }
+
+```
+
+Here we preprocess the graph for the execution of the nodes. First, [`compute_min_topological_nr`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L922-L933) is called to to obtain the minimum topological number of the tensors specified in `outputs` (0 if no `inputs` kwarg was supplied to `.backward` or `input` for `.grad`). This computation prunes paths in the graph that lead to input variables of which we don’t want/need to calculate the grads.
+
+Second, is the [`compute_dependencies`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L935-L967) call. This function is a very simple graph traversal that starts with the root `Node`, and for each of the edges in `node.next_edges()` it increments the counter in `dependencies_`. Figure 3 shows the result of the dependencies calculation for the example graph. Note that the number of dependencies of any node is just the number of edges arriving at it.
+
+
+ 
+
+
+
+Figure 3: Number of dependencies for each node
+
+
+Finally, the [`init_to_execute`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1281-L1383) call, this is the one that populates the `GraphTask::exec_info_` map in case that `inputs` were specified in the python `backward` call. It iterates the graph again, starting from the root, and records in the `exec_info_` map the intermediate nodes needed to calculate only the given `inputs` gradients.
+
+```c++
+ // Queue the root
+ if (skip_dummy_node) {
+ InputBuffer input_buffer(roots.at(0).function->num_inputs());
+ auto input = inputs.at(0);
+
+
+ input_buffer.add(roots.at(0).input_nr,
+ std::move(input),
+ input_stream,
+ opt_next_stream);
+
+ execute_with_graph_task(graph_task, graph_root, std::move(input_buffer));
+ } else {
+ execute_with_graph_task(graph_task, graph_root, InputBuffer(variable_list()));
+ }
+ // Avoid a refcount bump for the Future, since we check for refcount in
+ // DistEngine (see TORCH_INTERNAL_ASSERT(futureGrads.use_count() == 1)
+ // in dist_engine.cpp).
+ auto& fut = graph_task->future_result_;
+ fut->wait();
+ return fut->value().toTensorVector();
+}
+
+```
+
+And now, we are ready to start the actual execution by creating the `InputBuffer`. In case we only have one root variable, we begin by copying the value of the `inputs` tensor (this is the `gradients` passed to python `backward`) in position 0 of the input_buffer. This is a small optimization that avoids running the `RootNode` for no reason. Also, if the rest of the graph is not on the cpu, we directly start on that worker while the `RootNode` is always placed on the cpu ready queue. Details of the workers and ready queues are explained in the section below.
+
+On the other hand, if we have multiple roots, the `GraphRoot` object also holds the inputs, so it is enough to pass it an empty `InputBuffer`.
+
+## Graph Traversal and Node Execution
+### Devices, Threads and Queues
+
+Before diving into the actual execution, we need to see how the engine is structured.
+
+First of all, the engine is multithreaded with one thread per device. For example, the caller thread is associated with the CPU while additional threads are created and associated with each GPU or other devices available in the system. Each thread tracks its device using thread-local storage in the [`worker_device`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L69) variable. In addition, the threads have a queue of tasks to be executed also located in thread-local storage, the [`local_ready_queue`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L103-L104). This is where work is queued for this thread to execute in the `thread_main` function that is explained later.
+You will wonder how the device where a task should be executed is decided. The `InputBuffer` class has a [`device()`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/input_buffer.cpp#L173-L189) function that returns the first non-cpu device of all its tensors.
+This function is used together with [`Engine::ready_queue`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1181-L1190) to select the queue to queue a task.
+
+```c++
+auto Engine::ready_queue(std::shared_ptr cpu_ready_queue, at::Device device) -> std::shared_ptr{
+ if (device.type() == at::kCPU || device.type() == at::DeviceType::Meta) {
+ return cpu_ready_queue;
+ } else {
+ // See Note [Allocating GPUs to autograd threads]
+ return device_ready_queues_.at(device.index());
+ }
+}
+
+```
+
+The [`ReadyQueue`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L245-L283) object is defined in `torch/csrc/autograd/engine.h` and it is a simple wrapper over `std::priority_queue` that allows a thread to [wait for a task](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L219) if it’s empty. One interesting property of the `ReadyQueue` is that it increases the [`GraphTask::outstanding_tasks_`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L195) value used to determine if the execution has completed or not.
+
+```c++
+auto ReadyQueue::push(NodeTask item, bool incrementOutstandingTasks) -> void {
+ {
+ std::lock_guard lock(mutex_);
+ if (incrementOutstandingTasks) {
+ std::shared_ptr graph_task = item.base_.lock();
+ ++graph_task->outstanding_tasks_;
+ }
+ heap_.push(std::move(item));
+ }
+ not_empty_.notify_one();
+}
+
+auto ReadyQueue::pop() -> NodeTask {
+ std::unique_lock lock(mutex_);
+ not_empty_.wait(lock, [this]{ return !heap_.empty(); });
+ auto task = std::move(const_cast(heap_.top())); heap_.pop();
+ return task;
+}
+
+```
+
+### Reentrant Backward
+
+A reentrant backward happens when one of the tasks in a backward pass calls again `backward`. It is not a very common case, but it can be used to reduce memory utilization as it could potentially avoid saving intermediate results. For more information, check this [PyTorch forum post](https://discuss.pytorch.org/t/what-is-the-scenario-of-reentrant-backwards-in-pytorch-source-code/19330/2).
+
+```python
+class ReentrantBackward(torch.autograd.Function):
+ @staticmethod
+ def forward(ctx, input):
+ return input.sum()
+
+ @staticmethod
+ def backward(ctx, input):
+ # Let's compute the backward by using autograd
+ input = input.detach().requires_grad_()
+ with torch.enable_grad():
+ out = input.sum()
+ out.backward() # REENTRANT CALL!!
+ return out.detach()
+
+```
+
+Here, we call `backward()` inside `backward()` for a user custom-defined autograd function.
+This situation can lead to deadlocks because the first backward needs to wait for the second one to complete. But some internal implementation details can prevent the second backward from completing as it is explained in the dedicated subsection.
+## Thread Initialization
+
+[`execute_with_graph_task`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1054-L1126) is in charge of initializing the threads taking care of the computation and placing the `root` node in the queue of the device that produced it.
+
+```c++
+c10::intrusive_ptr Engine::execute_with_graph_task(
+ const std::shared_ptr& graph_task,
+ std::shared_ptr graph_root,
+ InputBuffer&& input_buffer) {
+
+ initialize_device_threads_pool();
+ // Lock mutex for GraphTask.
+ std::unique_lock lock(graph_task->mutex_);
+
+ auto queue = ready_queue(graph_task->cpu_ready_queue_, input_buffer.device());
+
+ if (worker_device == NO_DEVICE) {
+ set_device(CPU_DEVICE);
+ graph_task->owner_ = worker_device;
+ queue->push(NodeTask(graph_task, std::move(graph_root), std::move(input_buffer)));
+ lock.unlock();
+ thread_main(graph_task);
+ worker_device = NO_DEVICE;
+ } else {
+ // This deals with reentrant backwards, we will see it later.
+ }
+ return graph_task->future_result_;
+}
+
+```
+
+First, this function initializes several threads (one per device) calling [` initialize_device_threads_pool()`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1046-L1052) where several things happen:
+One `ReadyQueue` per device is created.
+One thread per non-cpu device is created.
+A thread local `worker_device` variable is set to track the current device associated with the thread.
+`thread_main` function is called, and threads wait for tasks to be put in their queues.
+
+Then it retrieves the queue to place the root node based on the device that holds the tensors present in the `input_buffer` using the `ready_queue` function. Now, the main thread (the one also executing the Python interpreter) has its `worker_device` set to `NO_DEVICE`, and it is in charge of executing functions with all its tensors living in the cpu. If `worker_device` is set to any other value, the graph execution is already started, and `.backward()` was called inside a running `Node`, creating a reentrant backward call. This is explained later. For now,
+the main thread places the task in the queue and call `thread_main`.
+## Where the Magic Happens
+
+It’s been a long way, but finally, we are ready to traverse the graph and execute the nodes. Each of the spawned threads, and the main thread call [`thread_main`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L377-L464).
+
+```c++
+auto Engine::thread_main(const std::shared_ptr& graph_task) -> void {
+
+ while (graph_task == nullptr || !graph_task->future_result_->completed()) {
+ std::shared_ptr local_graph_task;
+ {
+ NodeTask task = local_ready_queue->pop();
+
+ if (task.isShutdownTask_) {
+ break;
+ }
+
+ if (!(local_graph_task = task.base_.lock())) {
+ // GraphTask for function is no longer valid, skipping further
+ // execution.
+ continue;
+ }
+
+ if (task.fn_ && !local_graph_task->has_error_.load()) {
+ at::ThreadLocalStateGuard tls_guard(local_graph_task->thread_locals_);
+
+ try {
+ GraphTaskGuard guard(local_graph_task);
+ NodeGuard ndguard(task.fn_);
+ {
+ evaluate_function(
+ local_graph_task,
+ task.fn_.get(),
+ task.inputs_,
+ local_graph_task->cpu_ready_queue_);
+ }
+ } catch (std::exception& e) {
+ thread_on_exception(local_graph_task, task.fn_, e);
+ }
+ }
+ }
+
+ // Decrement the outstanding tasks.
+ --local_graph_task->outstanding_tasks_;
+
+ // Check if we've completed execution.
+ if (local_graph_task->completed()) {
+ local_graph_task->mark_as_completed_and_run_post_processing();
+ auto base_owner = local_graph_task->owner_;
+ if (worker_device != base_owner) {
+ std::atomic_thread_fence(std::memory_order_release);
+ ready_queue_by_index(local_graph_task->cpu_ready_queue_, base_owner)
+ ->push(NodeTask(local_graph_task, nullptr, InputBuffer(0)));
+ }
+ }
+ }
+}
+
+```
+
+The code here is simple, given the `local_ready_queue` assigned to each thread in thread-local storage. The threads loop until there are no tasks left to execute in the graph. Note that for device-associated threads, the passed `graph_task` argument is [`nullptr`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L326-L327), and they block in `local_ready_queue->pop()` until a task is pushed in their queue. After some consistency checks (the task type is shutdown, or the graph is still valid). We get to the actual function invocation in `evaluate_function`.
+
+```c++
+ try {
+ GraphTaskGuard guard(local_graph_task);
+ NodeGuard ndguard(task.fn_);
+ {
+ evaluate_function(
+ local_graph_task,
+ task.fn_.get(),
+ task.inputs_,
+ local_graph_task->cpu_ready_queue_);
+ }
+ } catch (std::exception& e) {
+ thread_on_exception(local_graph_task, task.fn_, e);
+ }
+ }
+
+```
+
+After calling `evaluate_function`, we check if the `graph_task` execution is complete by looking the `outstanding_tasks_` number. This number increases when a task is pushed to a queue and is decreased in `local_graph_task->completed()` when a task is executed. When the execution is done, we return the results that are be in the `captured_vars_` in case we called `torch.autograd.grad()` instead of `torch.autograd.backward()` as this function returns tensors instead of storing them in the `.grad` attribute of the inputs. Finally we wake up the main thread if it’s waiting by sending a dummy task.
+
+```c++
+ // Decrement the outstanding tasks.
+ --local_graph_task->outstanding_tasks_;
+
+ // Check if we've completed execution.
+ if (local_graph_task->completed()) {
+ local_graph_task->mark_as_completed_and_run_post_processing();
+ auto base_owner = local_graph_task->owner_;
+ if (worker_device != base_owner) {
+ std::atomic_thread_fence(std::memory_order_release);
+ ready_queue_by_index(local_graph_task->cpu_ready_queue_, base_owner)
+ ->push(NodeTask(local_graph_task, nullptr, InputBuffer(0)));
+ }
+ }
+
+```
+
+## Calling the Function and Unlocking New Tasks
+
+[`evaluate_function`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L786-L920) serves three purposes:
+
+Run the function.
+Accumulate its results in the next node `InputBuffers`.
+Decrease the dependencies counter of the next nodes and enqueues the tasks reaching 0 to be executed.
+
+```c++
+void Engine::evaluate_function(
+ std::shared_ptr& graph_task,
+ Node* func,
+ InputBuffer& inputs,
+ const std::shared_ptr& cpu_ready_queue) {
+
+ // If exec_info_ is not empty, we have to instrument the execution
+ auto& exec_info_ = graph_task->exec_info_;
+ if (!exec_info_.empty()) {
+ // Checks if the function needs to be executed
+ if (!fn_info.needed_) {
+ // Skip execution if we don't need to execute the function.
+ return;
+ }
+ }
+
+ auto outputs = call_function(graph_task, func, inputs);
+
+ auto& fn = *func;
+ if (!graph_task->keep_graph_) {
+ fn.release_variables();
+ }
+
+```
+
+Initially, we check the `exec_info_` map of the `GraphTask` structure to determine if the current node needs to be executed. Remember that if this map is empty, all the nodes are executed because we are calculating the grads for all the inputs of the forward pass.
+
+After this check, the function is executed by running [`call_function`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L735-L784). Its implementation is very straightforward and calls the actual derivative function and registered hooks if any.
+
+```c++
+ int num_outputs = outputs.size();
+ if (num_outputs == 0) {
+ // Records leaf stream (if applicable)
+ return;
+ }
+
+ if (AnomalyMode::is_enabled()) {
+ // check for nan values in result
+ }
+
+```
+
+Next, we check the outputs of the function after `call_function` is done. If the number of outputs is 0, there are no following nodes to be executed so we can safely return. This is the case of the `AccumulateGrad` node associated with the leaf nodes.
+
+ Also, the check for `NaN` values in the gradients is done here if requested.
+```c++
+
+ std::lock_guard lock(graph_task->mutex_);
+ for (const auto i : c10::irange(num_outputs)) {
+ auto& output = outputs[i];
+ const auto& next = fn.next_edge(i);
+
+ if (!next.is_valid()) continue;
+
+
+
+```
+
+We have now executed a `grad_fn` that has returned one gradient per each of the associated forward pass function inputs. As we saw in the [previous blog post](https://pytorch.org/blog/computational-graphs-constructed-in-pytorch/#linking-nodes-together), we have an `Edge` object per each of these input tensors, and the `grad_fn` of the function producing them in the forward pass. Essentially, Output[0] of the node in the backward pass, corresponds to the first argument of the forward pass associated function. Figure 4 shows how the outputs of a backward function are related to the inputs of the forward function. See that the outputs of `grad_fn C` are the gradients of `z` w.r.t. the inputs of `Function C`
+
+
+ 
+
+
+
+Figure 4: Correspondence between forward and backward functions inputs and outputs
+
+
+We now iterate through these edges and check if the associated functions are ready to be executed.
+
+```c++
+ // Check if the next function is ready to be computed
+ bool is_ready = false;
+ auto& dependencies = graph_task->dependencies_;
+ auto it = dependencies.find(next.function.get());
+
+ if (it == dependencies.end()) {
+ auto name = next.function->name();
+ throw std::runtime_error(std::string("dependency not found for ") + name);
+ } else if (--it->second == 0) {
+ dependencies.erase(it);
+ is_ready = true;
+ }
+
+ auto& not_ready = graph_task->not_ready_;
+ auto not_ready_it = not_ready.find(next.function.get());
+
+```
+
+For this, we check the `graph_task->dependencies_` map. We decrement the counter, and if it reaches 0, we mark the function pointed by the edge ready to be executed. Following, we prepare the input buffers of the tasks indicated by the next edges.
+
+```c++
+ if (not_ready_it == not_ready.end()) {
+ if (!exec_info_.empty()) {
+ // Skip functions that aren't supposed to be executed
+ }
+
+ // Creates an InputBuffer and moves the output to the corresponding input position
+ InputBuffer input_buffer(next.function->num_inputs());
+ input_buffer.add(next.input_nr,
+ std::move(output),
+ opt_parent_stream,
+ opt_next_stream);
+
+ if (is_ready) {
+ auto queue = ready_queue(cpu_ready_queue, input_buffer.device());
+ queue->push(
+ NodeTask(graph_task, next.function, std::move(input_buffer)));
+ } else {
+ not_ready.emplace(next.function.get(), std::move(input_buffer));
+ }
+
+```
+
+Here, we look for the task in the `graph_task->not_ready_` map. If it is not present, we create a new `InputBuffer` object and set the current output in the `input_nr` position of the buffer associated with the edge. If the task is ready to be executed, we enqueue it in the appropriate device `ready_queue` and complete the execution. However, if the task is not ready and we have seen it before, it is present in the `not_ready_map_`.
+
+```c++
+ } else {
+ // The function already has a buffer
+ auto &input_buffer = not_ready_it->second;
+ // Accumulates into buffer
+ input_buffer.add(next.input_nr,
+ std::move(output),
+ opt_parent_stream,
+ opt_next_stream);
+ if (is_ready) {
+ auto queue = ready_queue(cpu_ready_queue, input_buffer.device());
+ queue->push(NodeTask(graph_task, next.function, std::move(input_buffer)));
+ not_ready.erase(not_ready_it);
+ }
+ }
+ }
+}
+
+```
+
+In this case, we accumulate the output in the existing `input_buffer` instead of creating a new one. Once all the tasks are processed, the worker thread exits the loop and complete.
+All this process is summarized in the animation in Figure 5. We see how a thread peeks at the tasks in the ready queue and decrements the next nodes' dependencies, unlocking them for execution.
+
+
+ 
+
+
+
+Figure 5: Animation of the execution of the computational graph
+
+
+## Flow with Reentrant Backward
+
+As we saw above, the reentrant backward problem is when the currently executed function does a nested call to `backward`. When this happens, the thread running this function goes all the way down to `execute_with_graph_task` as in the non-reentrant case, but here is when things are different.
+
+```c++
+c10::intrusive_ptr Engine::execute_with_graph_task(
+ const std::shared_ptr& graph_task,
+ std::shared_ptr graph_root,
+ InputBuffer&& input_buffer) {
+
+ initialize_device_threads_pool();
+ // Lock mutex for GraphTask.
+ std::unique_lock lock(graph_task->mutex_);
+
+ auto queue = ready_queue(graph_task->cpu_ready_queue_, input_buffer.device());
+
+ if (worker_device == NO_DEVICE) {
+ //Regular case
+ } else {
+ // If worker_device is any devices (i.e. CPU, CUDA): this is a re-entrant
+ // backward call from that device.
+ graph_task->owner_ = worker_device;
+
+ // Now that all the non-thread safe fields of the graph_task have been populated,
+ // we can enqueue it.
+ queue->push(NodeTask(graph_task, std::move(graph_root), std::move(input_buffer)));
+
+ if (current_depth >= max_recursion_depth_) {
+ // If reached the max depth, switch to a different thread
+ add_thread_pool_task(graph_task);
+ } else {
+ ++total_depth;
+ ++current_depth;
+ lock.unlock();
+ thread_main(graph_task);
+ --current_depth;
+ --total_depth;
+ }
+ }
+ return graph_task->future_result_;
+}
+
+```
+
+Here, `execute_with_graph_task` detects this as a reentrant call and then looks for the current number of nested calls. If it exceeds the limit, we create a new thread to take care of the execution of this graph, and if not, we execute this reentrant call regularly.
+The limit of nested calls was originally set to avoid stack overflow due to reentrant calls creating very large call stacks. However, the number was further reduced when sanitizer tests were added because of the maximum amount of locks a thread can hold at a given moment. This can be seen in [`torch/csrc/autograd/engine.h`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L36-L42).
+
+
+When this maximum depth is exceeded, a new thread is created with the [`add_thread_pool_task`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1239-L1255) function.
+
+```c++
+void Engine::add_thread_pool_task(const std::weak_ptr& graph_task) {
+ std::unique_lock lck(thread_pool_shared_->mutex_);
+ // if we have pending graph_task objects to be processed, create a worker.
+ bool create_thread = (thread_pool_shared_->num_workers_ <= thread_pool_shared_->graphtasks_queue_.size());
+ thread_pool_shared_->graphtasks_queue_.push(graph_task);
+
+
+ lck.unlock();
+ if (create_thread) {
+ std::thread t(&Engine::reentrant_thread_init, this);
+ t.detach();
+ }
+
+ thread_pool_shared_->work_.notify_one();
+}
+
+
+
+```
+
+Before going in-depth, let's look at the `thread_pool_shared_` object in the [`Engine`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L421) which manages all the information related to the threads associated to the reentrant backward calls.
+
+```c++
+ struct ThreadPoolShared {
+ unsigned int num_workers_;
+ std::condition_variable work_;
+ std::mutex mutex_;
+ std::queue> graphtasks_queue_;
+
+ // NOLINTNEXTLINE(cppcoreguidelines-pro-type-member-init)
+ ThreadPoolShared() : num_workers_(0) {}
+ };
+
+
+
+ ```
+
+[`ThreadPoolShared`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.h#L398-L414) is a simple container holding a queue of `GraphTask` objects with synchronization mechanisms and the number of current workers.
+
+Now it is easy to understand how `add_thread_pool_task` creates a thread when there are `graph_task` objects enqueued and insufficient workers to process them.
+
+`add_thread_pool_task` initializes a thread by executing [`reentrant_thread_init`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L471-L493)
+
+```c++
+void Engine::reentrant_thread_init() {
+ at::init_num_threads();
+ auto tp_shared = thread_pool_shared_;
+ while(true) {
+ std::unique_lock lk(tp_shared->mutex_);
+ ++thread_pool_shared_->num_workers_;
+ tp_shared->work_.wait(lk, [&tp_shared]{ return !tp_shared->graphtasks_queue_.empty();});
+ --thread_pool_shared_->num_workers_;
+ auto task = tp_shared->graphtasks_queue_.front();
+ tp_shared->graphtasks_queue_.pop();
+ lk.unlock();
+ std::shared_ptr graph_task;
+ if (!(graph_task = task.lock())) {
+ continue;
+ }
+ set_device(graph_task->owner_);
+ // set the local_ready_queue to the ready queue on the graph_task->owner_ device
+ local_ready_queue = ready_queue_by_index(graph_task->cpu_ready_queue_, graph_task->owner_);
+ total_depth = graph_task->reentrant_depth_;
+ thread_main(graph_task);
+ }
+}
+
+
+
+```
+
+The code is straightforward. The newly created thread waits on the `thread_pool_shared->graphtasks_queue_` for reentrant backward graphs to be available and executes them. Notice that this thread uses the task-ready queue associated with the device of the thread that started this call by accessing the `graph_task->owner_` field set in the [`execute_with_graph_task`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L1092) function.
+
+## Error Handling
+
+Whenever an error happens in one of the worker threads. It will be propagated to the `backward` calling thread.
+
+To achieve this, there is a try/catch block in the [`thread_main`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L415-L438) that catches any exception in the `Node` function call and sets it to the associated `GraphTask` object.
+
+
+```c++
+ try {
+ …
+ GraphTaskGuard guard(local_graph_task);
+ NodeGuard ndguard(task.fn_);
+ {
+ evaluate_function(
+ …
+ }
+ } catch (std::exception& e) {
+ thread_on_exception(local_graph_task, task.fn_, e);
+ }
+ }
+ }
+
+```
+
+[`thread_on_exception`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L495-L500) and the [functions it calls](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/torch/csrc/autograd/engine.cpp#L605-L621) end up setting the exception in the `local_graph_task` object.
+
+```c++
+void Engine::thread_on_exception(
+ std::shared_ptr graph_task,
+ const std::shared_ptr& fn,
+ std::exception& e) {
+ graph_task->set_exception(std::current_exception(), fn);
+}
+
+void GraphTask::set_exception_without_signal(const std::shared_ptr& fn) {
+ if (!has_error_.exchange(true)) {
+ if (AnomalyMode::is_enabled() && fn) {
+ fn->metadata()->print_stack(fn->name());
+ }
+ }
+}
+
+void GraphTask::set_exception(
+ std::exception_ptr eptr,
+ const std::shared_ptr& fn) {
+ set_exception_without_signal(fn);
+ if (!future_completed_.exchange(true)) {
+ // NOLINTNEXTLINE(performance-move-const-arg)
+ future_result_->setError(std::move(eptr));
+ }
+}
+
+```
+
+In `set_exception` it sets the `has_error_` flag to `true` and it calls the [`setError`]()
+function of the [`future_result_`](https://github.com/pytorch/pytorch/blob/bc2c6edaf163b1a1330e37a6e34caf8c553e4755/aten/src/ATen/core/ivalue_inl.h#L770-L1322) object. This will make the error to be re-thrown at the caller thread when `future_result_->value()` is accessed.
+
+```c++
+ IValue value() {
+ std::unique_lock lock(mutex_);
+ AT_ASSERT(completed());
+ if (eptr_) {
+ std::rethrow_exception(eptr_);
+ }
+ return value_;
+ }
+
+```
+
+# Closing Remarks
+
+This has been the last post of this series covering how PyTorch does the auto differentiation. We hope you enjoyed reading it and that now you are familiar enough with PyTorch internals to start contributing in PyTorch development!
From ba158b74ebaa76fc411673ef2701641c4db74f44 Mon Sep 17 00:00:00 2001
From: TerryCE <100383566+TerryCE@users.noreply.github.com>
Date: Wed, 25 May 2022 11:19:48 -0700
Subject: [PATCH 2/6] Add files via upload
---
assets/images/backward-grad-fig-1.png | Bin 0 -> 444425 bytes
assets/images/computation-animation-fig-5.gif | Bin 0 -> 612644 bytes
.../images/forward-backward-function-fig-4.png | Bin 0 -> 418870 bytes
assets/images/node-fig-3.png | Bin 0 -> 209709 bytes
assets/images/topological-number-fig-2.png | Bin 0 -> 215908 bytes
5 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 assets/images/backward-grad-fig-1.png
create mode 100644 assets/images/computation-animation-fig-5.gif
create mode 100644 assets/images/forward-backward-function-fig-4.png
create mode 100644 assets/images/node-fig-3.png
create mode 100644 assets/images/topological-number-fig-2.png
diff --git a/assets/images/backward-grad-fig-1.png b/assets/images/backward-grad-fig-1.png
new file mode 100644
index 0000000000000000000000000000000000000000..f5a62257a8934d0d04f7bad7dfb50b2f55e1cf2b
GIT binary patch
literal 444425
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