Add second-derivative functions to interface

Author: gerlero

docs/src/implementer_guide.md

@@ -29,11 +29,14 @@ They are just listed here to help readers figure out the code structure:
   - `derivative` calls `jacobian`
   - `gradient` calls `jacobian`
   - `hessian` calls `jacobian` and `gradient`
+  - `second_derivative` calls `derivative`
   - `value_and_jacobian` calls `jacobian`
   - `value_and_derivative` calls `value_and_jacobian`
   - `value_and_gradient` calls `value_and_jacobian`
   - `value_and_hessian` calls `jacobian` and `gradient`
+  - `value_and_second_derivative` calls `second_derivative`
   - `value_gradient_and_hessian` calls `value_and_jacobian` and `gradient`
+   - `value_and_derivatives` calls `value_and_derivative` and `second_derivative`
   - `pushforward_function` calls `jacobian`
   - `value_and_pushforward_function` calls `pushforward_function`
   - `pullback_function` calls `value_and_pullback_function`

docs/src/user_guide.md

@@ -53,24 +53,27 @@ AbstractDifferentiation.HigherOrderBackend
 
 ## Derivatives
 
-The following list of functions can be used to request the derivative, gradient, Jacobian or Hessian without the function value.
+The following list of functions can be used to request the derivative, second derivative, gradient, Jacobian or Hessian without the function value.
 
 ```@docs
 AbstractDifferentiation.derivative
 AbstractDifferentiation.gradient
 AbstractDifferentiation.jacobian
+AbstractDifferentiation.second_derivative
 AbstractDifferentiation.hessian
 ```
 
 ## Value and derivatives
 
-The following list of functions can be used to request the function value along with its derivative, gradient, Jacobian or Hessian. You can also request the function value, its gradient and Hessian for single-input functions.
+The following list of functions can be used to request the function value along with its derivative, second derivative, gradient, Jacobian or Hessian. You can also request the function value, its gradient and Hessian for single-input functions.
 
 ```@docs
 AbstractDifferentiation.value_and_derivative
 AbstractDifferentiation.value_and_gradient
 AbstractDifferentiation.value_and_jacobian
+AbstractDifferentiation.value_and_second_derivative
 AbstractDifferentiation.value_and_hessian
+AbstractDifferentiation.value_and_derivatives
 AbstractDifferentiation.value_gradient_and_hessian
 ```
 

src/AbstractDifferentiation.jl

@@ -85,6 +85,20 @@ function jacobian(ab::HigherOrderBackend, f, xs...)
     return jacobian(lowest(ab), f, xs...)
 end
 
+"""
+    AD.second_derivative(ab::AD.AbstractBackend, f, xs...)
+
+Compute the second derivatives of `f` with respect to the inputs `xs` using the backend `ab`.
+
+The function returns a `Tuple` of second derivatives, one for each element in `xs`.
+"""
+function second_derivative(ab::AbstractBackend, f, xs...)
+    return derivative(second_lowest(ab), x -> begin
+        d = derivative(lowest(ab), f, x)
+        return d[1] # derivative returns a tuple
+    end, xs...)
+end
+
 """
     AD.hessian(ab::AD.AbstractBackend, f, x)
 
@@ -139,12 +153,23 @@ function value_and_jacobian(ab::AbstractBackend, f, xs...)
     return value, jacs
 end
 
+"""
+    AD.value_and_second_derivative(ab::AD.AbstractBackend, f, x)
+
+Return the tuple `(v, d2)` of the function value `v = f(x)` and the second derivatives `d = AD.derivative(ab, f, x)` and `d2 = AD.hessian(ab, f, x)`.
+
+See also [`AbstractDifferentiation.second_derivative`](@ref)
+"""
+function value_and_second_derivative(ab::AbstractBackend, f, x)
+    return f(x), second_derivative(ab, f, x)[1]
+end
+
 """
     AD.value_and_hessian(ab::AD.AbstractBackend, f, x)
 
 Return the tuple `(v, H)` of the function value `v = f(x)` and the Hessian `H = AD.hessian(ab, f, x)`.
 
-See also [`AbstractDifferentiation.hessian`](@ref).    
+See also [`AbstractDifferentiation.hessian`](@ref). 
 """
 function value_and_hessian(ab::AbstractBackend, f, x)
     if x isa Tuple
@@ -176,6 +201,15 @@ function value_and_hessian(ab::HigherOrderBackend, f, x)
     return value, hess
 end
 
+"""
+    AD.value_and_derivatives(ab::AD.AbstractBackend, f, x)
+
+Return the tuple `(v, d, d2)` of the function value `v = f(x)` and the first and second derivatives `d = AD.derivative(ab, f, x)` and `d2 = AD.second_derivative(ab, f, x)`.
+"""
+function value_and_derivatives(ab::AbstractBackend, f, x)
+    return value_and_derivative(ab, f, x)..., second_derivative(ab, f, x)[1]
+end
+
 """
     AD.value_gradient_and_hessian(ab::AD.AbstractBackend, f, x)