derivative for in-place functions of the form f!(::AbstractArray, ::Real) (#219)

Author: jrevels

docs/_rst/source/basic_api.rst

@@ -8,15 +8,22 @@ Use ``ForwardDiff.derivative`` to differentiate functions of the form ``f(::Real
 
 .. function:: ForwardDiff.derivative!(out, f, x)
 
-    Compute :math:`f'(x)`, storing the output in ``out``. If ``x`` is a ``Tuple``,
-    then ``f`` will be called as ``f(x...)`` and the derivatives with respect to
-    each element in `x` will be stored in the respective element of ``out`` (which
-    should also be a ``Tuple``).
+    Compute :math:`f'(x)`, storing the output in ``out``.
+
+.. function:: ForwardDiff.derivative!(out, f!, y, x, cfg = ForwardDiff.DerivativeConfig(f!, y, x))
+
+    Compute and return :math:`f'(x)`, storing the output in ```out``. This form assumes that
+    :math:`f'(x)` can be called as ``f!(y, x)`` such that the value result is stored in
+    ``y``.
 
 .. function:: ForwardDiff.derivative(f, x)
 
-    Compute and return :math:`f'(x)`. If ``x`` is a ``Tuple``, ``f`` will be
-    called as ``f(x...)``, and a ``Tuple`` of derivatives will be returned.
+    Compute and return :math:`f'(x)`.
+
+.. function:: ForwardDiff.derivative(f!, y, x, cfg = ForwardDiff.DerivativeConfig(f!, y, x))
+
+    Compute and return :math:`f'(x)`. This form assumes that :math:`f'(x)` can be called as
+    ``f!(y, x)`` such that the value result is stored in ``y``.
 
 Gradients of :math:`f(x) : \mathbb{R}^{n_1} \times \dots \times \mathbb{R}^{n_k} \to \mathbb{R}`
 ------------------------------------------------------------------------------------------------

docs/_sources/basic_api.txt

@@ -8,15 +8,22 @@ Use ``ForwardDiff.derivative`` to differentiate functions of the form ``f(::Real
 
 .. function:: ForwardDiff.derivative!(out, f, x)
 
-    Compute :math:`f'(x)`, storing the output in ``out``. If ``x`` is a ``Tuple``,
-    then ``f`` will be called as ``f(x...)`` and the derivatives with respect to
-    each element in `x` will be stored in the respective element of ``out`` (which
-    should also be a ``Tuple``).
+    Compute :math:`f'(x)`, storing the output in ``out``.
+
+.. function:: ForwardDiff.derivative!(out, f!, y, x, cfg = ForwardDiff.DerivativeConfig(f!, y, x))
+
+    Compute and return :math:`f'(x)`, storing the output in ```out``. This form assumes that
+    :math:`f'(x)` can be called as ``f!(y, x)`` such that the value result is stored in
+    ``y``.
 
 .. function:: ForwardDiff.derivative(f, x)
 
-    Compute and return :math:`f'(x)`. If ``x`` is a ``Tuple``, ``f`` will be
-    called as ``f(x...)``, and a ``Tuple`` of derivatives will be returned.
+    Compute and return :math:`f'(x)`.
+
+.. function:: ForwardDiff.derivative(f!, y, x, cfg = ForwardDiff.DerivativeConfig(f!, y, x))
+
+    Compute and return :math:`f'(x)`. This form assumes that :math:`f'(x)` can be called as
+    ``f!(y, x)`` such that the value result is stored in ``y``.
 
 Gradients of :math:`f(x) : \mathbb{R}^{n_1} \times \dots \times \mathbb{R}^{n_k} \to \mathbb{R}`
 ------------------------------------------------------------------------------------------------

docs/basic_api.html

@@ -152,17 +152,28 @@ <h2>Derivatives of <span class="math">\(f(x) : \mathbb{R} \to \mathbb{R}^{n_1} \
 <dl class="function">
 <dt>
 <code class="descname">ForwardDiff.derivative!(out, f, x)</code></dt>
-<dd><p>Compute <span class="math">\(f'(x)\)</span>, storing the output in <code class="docutils literal"><span class="pre">out</span></code>. If <code class="docutils literal"><span class="pre">x</span></code> is a <code class="docutils literal"><span class="pre">Tuple</span></code>,
-then <code class="docutils literal"><span class="pre">f</span></code> will be called as <code class="docutils literal"><span class="pre">f(x...)</span></code> and the derivatives with respect to
-each element in <cite>x</cite> will be stored in the respective element of <code class="docutils literal"><span class="pre">out</span></code> (which
-should also be a <code class="docutils literal"><span class="pre">Tuple</span></code>).</p>
+<dd><p>Compute <span class="math">\(f'(x)\)</span>, storing the output in <code class="docutils literal"><span class="pre">out</span></code>.</p>
+</dd></dl>
+
+<dl class="function">
+<dt>
+<code class="descname">ForwardDiff.derivative!(out, f!, y, x, cfg = ForwardDiff.DerivativeConfig(f!, y, x))</code></dt>
+<dd><p>Compute and return <span class="math">\(f'(x)\)</span>, storing the output in <code class="docutils literal"><span class="pre">`out</span></code>. This form assumes that
+<span class="math">\(f'(x)\)</span> can be called as <code class="docutils literal"><span class="pre">f!(y,</span> <span class="pre">x)</span></code> such that the value result is stored in
+<code class="docutils literal"><span class="pre">y</span></code>.</p>
 </dd></dl>
 
 <dl class="function">
 <dt id="ForwardDiff.derivative">
 <code class="descclassname">ForwardDiff.</code><code class="descname">derivative</code><span class="sig-paren">(</span><em>f</em>, <em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#ForwardDiff.derivative" title="Permalink to this definition">¶</a></dt>
-<dd><p>Compute and return <span class="math">\(f'(x)\)</span>. If <code class="docutils literal"><span class="pre">x</span></code> is a <code class="docutils literal"><span class="pre">Tuple</span></code>, <code class="docutils literal"><span class="pre">f</span></code> will be
-called as <code class="docutils literal"><span class="pre">f(x...)</span></code>, and a <code class="docutils literal"><span class="pre">Tuple</span></code> of derivatives will be returned.</p>
+<dd><p>Compute and return <span class="math">\(f'(x)\)</span>.</p>
+</dd></dl>
+
+<dl class="function">
+<dt>
+<code class="descclassname">ForwardDiff.</code><code class="descname">derivative</code><span class="sig-paren">(</span><em>f!</em>, <em>y</em>, <em>x</em>, <em>cfg = ForwardDiff.DerivativeConfig(f!</em>, <em>y</em>, <em>x)</em><span class="sig-paren">)</span></dt>
+<dd><p>Compute and return <span class="math">\(f'(x)\)</span>. This form assumes that <span class="math">\(f'(x)\)</span> can be called as
+<code class="docutils literal"><span class="pre">f!(y,</span> <span class="pre">x)</span></code> such that the value result is stored in <code class="docutils literal"><span class="pre">y</span></code>.</p>
 </dd></dl>
 
 </div>

docs/genindex.html

@@ -145,7 +145,7 @@ <h2 id="F">F</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%" valign="top"><dl>
 
-  <dt><a href="basic_api.html#ForwardDiff.derivative">ForwardDiff.derivative() (built-in function)</a>
+  <dt><a href="basic_api.html#ForwardDiff.derivative">ForwardDiff.derivative() (built-in function)</a>, <a href="basic_api.html#ForwardDiff.derivative">[1]</a>
   </dt>