1import chainerx
2from chainerx import _docs
3
4
5def set_docs():
6    _docs.set_doc(
7        chainerx.backward,
8        """backward(outputs, *, enable_double_backprop=False)
9Runs backpropagation.
10
11On backpropagation (a.k.a. backprop),
12the computational graph is traversed backward starting from the output arrays,
13up until the root arrays on which :func:`ndarray.require_grad()` have been
14called.
15
16Backpropagation uses :data:`ndarray.grad <chainerx.ndarray.grad>` held by
17the output arrays as the initial gradients.
18You can manually assign them before calling this function.
19Otherwise, they are assumed to be 1.
20
21To enable higher order differentiation, pass ``enable_double_backprop=True``
22so that you can further run backpropagation from the resulting gradient arrays.
23Note that enabling it results in larger memory consumption needed to store the
24gradients w.r.t intermediate arrays that are required for the second gradient
25computation.
26
27Note:
28    The whole process of backpropagation is executed in C++, except those
29    operations whose backward computation falls back to the corresponding
30    Python implementation. Currently this function does not release the GIL at
31    all.
32
33Args:
34    outputs (~chainerx.ndarray or list of ndarrays):
35        Output arrays from which backpropagation starts.
36    enable_double_backprop (bool): If ``True``,
37        a computational trace of the whole backpropagation procedure is
38        recorded to the computational graph so that one can further do
39        backpropagation from the resulting gradients.
40
41.. seealso::
42    * :meth:`chainerx.ndarray.backward`
43""")
44
45    _docs.set_doc(
46        chainerx.grad,
47        """grad(outputs, inputs, *, enable_double_backprop=False)
48Computes and returns the gradients of the outputs w.r.t. the inputs.
49
50This function differs from :func:`chainerx.backward` in the sense that
51gradients are returned instead of being added to the gradients held by the
52inputs. Gradients held by the inputs are not modified. Also, instead of
53traversing through the whole graph starting from the outputs, a sub-graph is
54extracted for computation. This means that is is more efficient, especially
55for larger computational graphs.
56
57Args:
58    outputs (list of ndarrays):
59        Output arrays from which backpropagation starts.
60    inputs (list of ndarrays):
61        Input arrays of which this function computes the gradients w.r.t.
62    enable_double_backprop (bool): If ``True``,
63        a computational trace of the whole backpropagation procedure is
64        recorded to the computational graph so that one can further do
65        backpropagation from the resulting gradients.
66
67Returns:
68    list of :class:`~chainerx.ndarray`\\ s:
69        A list of gradients. The list always has the same length as the number
70        of inputs.
71
72.. seealso::
73    * :func:`chainerx.backward`
74    * :func:`chainer.grad`
75""")
76
77    _docs.set_doc(
78        chainerx.no_backprop_mode,
79        """no_backprop_mode()
80Creates a context manager which temporarily disables backpropagation.
81
82Within this context, no computational graph will be formed unless
83:meth:`~chainerx.force_backprop_mode` is used.
84
85Arrays resulting from operations enclosed with this context will be
86disconnected from the computational graph. Trying to perform backpropagation
87from such arrays would result in an error.
88
89.. code-block:: py
90
91    x = chainerx.array([4, 3], numpy.float32)
92    x.require_grad()
93
94    with chainerx.no_backprop_mode():
95        y = 2 * x + 1
96
97    y.backward()  # ! error
98
99Benefits of ``no_backprop_mode`` include reduced CPU overhead of building
100computational graphs, and reduced consumption of device memory that
101would be otherwise retained for backward propagation.
102
103.. seealso::
104    * :func:`chainerx.force_backprop_mode`
105    * :func:`chainerx.is_backprop_required`
106    * :func:`chainer.no_backprop_mode`
107""")
108
109    _docs.set_doc(
110        chainerx.force_backprop_mode,
111        """force_backprop_mode()
112Creates a context manager which temporarily enables backpropagation.
113
114This context re-enables backpropagation that is disabled by
115any surrounding :func:`~chainerx.no_backprop_mode` context.
116
117.. code-block:: py
118
119    x = chainerx.array([4, 3], numpy.float32)
120    x.require_grad()
121
122    with chainerx.no_backprop_mode():
123        with chainerx.force_backprop_mode():
124            y = 2 * x + 1
125
126    y.backward()
127    x.grad
128    # array([2., 2.], shape=(2,), dtype=float32, device='native:0')
129
130.. seealso::
131    * :func:`chainerx.no_backprop_mode`
132    * :func:`chainerx.is_backprop_required`
133    * :func:`chainer.force_backprop_mode`
134""")
135
136    _docs.set_doc(
137        chainerx.is_backprop_required,
138        """is_backprop_required()
139Returns whether the backpropagation is enabled in the current thread.
140
141The result is affect by :func:`chainerx.no_backprop_mode` and
142:func:`chainerx.force_backprop_mode`.
143
144.. seealso::
145    * :func:`chainerx.no_backprop_mode`
146    * :func:`chainerx.force_backprop_mode`
147""")
148