Update operator doc strings (#347)

* Document alternative pushforward and pb names

* Document operator preparation

* Add `document_preparation` helper

* Document preparation everywhere

Author: adrhill

DifferentiationInterface/src/DifferentiationInterface.jl

@@ -54,6 +54,7 @@ include("utils/batch.jl")
 include("utils/check.jl")
 include("utils/exceptions.jl")
 include("utils/maybe.jl")
+include("utils/printing.jl")
 
 include("first_order/pushforward.jl")
 include("first_order/pushforward_batched.jl")
@@ -77,8 +78,6 @@ include("misc/differentiate_with.jl")
 include("misc/sparsity_detector.jl")
 include("misc/from_primitive.jl")
 
-include("utils/printing.jl")
-
 function __init__()
     @require_extensions
 end

DifferentiationInterface/src/first_order/derivative.jl

@@ -17,6 +17,8 @@ function prepare_derivative end
     value_and_derivative(f!, y, backend, x, [extras]) -> (y, der)
 
 Compute the value and the derivative of the function `f` at point `x`.
+
+$(document_preparation("derivative"))
 """
 function value_and_derivative end
 
@@ -25,14 +27,18 @@ function value_and_derivative end
     value_and_derivative!(f!, y, der, backend, x, [extras]) -> (y, der)
 
 Compute the value and the derivative of the function `f` at point `x`, overwriting `der`.
-    """
+
+$(document_preparation("derivative"))
+"""
 function value_and_derivative! end
 
 """
     derivative(f,     backend, x, [extras]) -> der
     derivative(f!, y, backend, x, [extras]) -> der
 
 Compute the derivative of the function `f` at point `x`.
+
+$(document_preparation("derivative"))
 """
 function derivative end
 
@@ -41,6 +47,8 @@ function derivative end
     derivative!(f!, y, der, backend, x, [extras]) -> der
 
 Compute the derivative of the function `f` at point `x`, overwriting `der`.
+
+$(document_preparation("derivative"))
 """
 function derivative! end
 

DifferentiationInterface/src/first_order/gradient.jl

@@ -14,27 +14,35 @@ function prepare_gradient end
     value_and_gradient(f, backend, x, [extras]) -> (y, grad)
 
 Compute the value and the gradient of the function `f` at point `x`.
+
+$(document_preparation("gradient"))
 """
 function value_and_gradient end
 
 """
     value_and_gradient!(f, grad, backend, x, [extras]) -> (y, grad)
 
 Compute the value and the gradient of the function `f` at point `x`, overwriting `grad`.
+
+$(document_preparation("gradient"))
 """
 function value_and_gradient! end
 
 """
     gradient(f, backend, x, [extras]) -> grad
 
 Compute the gradient of the function `f` at point `x`.
+
+$(document_preparation("gradient"))
 """
 function gradient end
 
 """
     gradient!(f, grad, backend, x, [extras]) -> grad
 
 Compute the gradient of the function `f` at point `x`, overwriting `grad`.
+
+$(document_preparation("gradient"))
 """
 function gradient! end
 

DifferentiationInterface/src/first_order/jacobian.jl

@@ -17,6 +17,8 @@ function prepare_jacobian end
     value_and_jacobian(f!, y, backend, x, [extras]) -> (y, jac)
 
 Compute the value and the Jacobian matrix of the function `f` at point `x`.
+
+$(document_preparation("jacobian"))
 """
 function value_and_jacobian end
 
@@ -25,6 +27,8 @@ function value_and_jacobian end
     value_and_jacobian!(f!, y, jac, backend, x, [extras]) -> (y, jac)
 
 Compute the value and the Jacobian matrix of the function `f` at point `x`, overwriting `jac`.
+    
+$(document_preparation("jacobian"))
 """
 function value_and_jacobian! end
 
@@ -33,6 +37,8 @@ function value_and_jacobian! end
     jacobian(f!, y, backend, x, [extras]) -> jac
 
 Compute the Jacobian matrix of the function `f` at point `x`.
+
+$(document_preparation("jacobian"))
 """
 function jacobian end
 
@@ -41,6 +47,8 @@ function jacobian end
     jacobian!(f!, y, jac, backend, x, [extras]) -> jac
 
 Compute the Jacobian matrix of the function `f` at point `x`, overwriting `jac`.
+
+$(document_preparation("jacobian"))
 """
 function jacobian! end
 

DifferentiationInterface/src/first_order/pullback.jl

@@ -30,6 +30,12 @@ function prepare_pullback_same_point end
 
 Compute the value and the pullback of the function `f` at point `x` with seed `dy`.
 
+$(document_preparation("pullback"; same_point=true))
+
+!!! tip 
+    Pullbacks are also commonly called vector-Jacobian products or VJPs.
+    This function could have been named `value_and_vjp`.
+
 !!! info
     Required primitive for reverse mode backends.
 """
@@ -40,6 +46,12 @@ function value_and_pullback end
     value_and_pullback!(f!, y, dx, backend, x, dy, [extras]) -> (y, dx)
 
 Compute the value and the pullback of the function `f` at point `x` with seed `dy`, overwriting `dx`.
+
+$(document_preparation("pullback"; same_point=true))
+
+!!! tip 
+    Pullbacks are also commonly called vector-Jacobian products or VJPs.
+    This function could have been named `value_and_vjp!`.
 """
 function value_and_pullback! end
 
@@ -48,6 +60,12 @@ function value_and_pullback! end
     pullback(f!, y, backend, x, dy, [extras]) -> dx
 
 Compute the pullback of the function `f` at point `x` with seed `dy`.
+
+$(document_preparation("pullback"; same_point=true))
+
+!!! tip 
+    Pullbacks are also commonly called vector-Jacobian products or VJPs.
+    This function could have been named `vjp`.
 """
 function pullback end
 
@@ -56,6 +74,12 @@ function pullback end
     pullback!(f!, y, dx, backend, x, dy, [extras]) -> dx
 
 Compute the pullback of the function `f` at point `x` with seed `dy`, overwriting `dx`.
+
+$(document_preparation("pullback"; same_point=true))
+
+!!! tip 
+    Pullbacks are also commonly called vector-Jacobian products or VJPs.
+    This function could have been named `vjp!`.
 """
 function pullback! end
 

DifferentiationInterface/src/first_order/pushforward.jl

@@ -30,6 +30,12 @@ function prepare_pushforward_same_point end
 
 Compute the value and the pushforward of the function `f` at point `x` with seed `dx`.
 
+$(document_preparation("pushforward"; same_point=true))
+
+!!! tip 
+    Pushforwards are also commonly called Jacobian-vector products or JVPs.
+    This function could have been named `value_and_jvp`.
+
 !!! info
     Required primitive for forward mode backends.
 """
@@ -40,6 +46,12 @@ function value_and_pushforward end
     value_and_pushforward!(f!, y, dy, backend, x, dx, [extras]) -> (y, dy)
 
 Compute the value and the pushforward of the function `f` at point `x` with seed `dx`, overwriting `dy`.
+
+$(document_preparation("pushforward"; same_point=true))
+
+!!! tip 
+    Pushforwards are also commonly called Jacobian-vector products or JVPs.
+    This function could have been named `value_and_jvp!`.
 """
 function value_and_pushforward! end
 
@@ -48,6 +60,12 @@ function value_and_pushforward! end
     pushforward(f!, y, backend, x, dx, [extras]) -> dy
 
 Compute the pushforward of the function `f` at point `x` with seed `dx`.
+
+$(document_preparation("pushforward"; same_point=true))
+
+!!! tip 
+    Pushforwards are also commonly called Jacobian-vector products or JVPs.
+    This function could have been named `jvp`.
 """
 function pushforward end
 
@@ -56,6 +74,12 @@ function pushforward end
     pushforward!(f!, y, dy, backend, x, dx, [extras]) -> dy
 
 Compute the pushforward of the function `f` at point `x` with seed `dx`, overwriting `dy`.
+
+$(document_preparation("pushforward"; same_point=true))
+
+!!! tip 
+    Pushforwards are also commonly called Jacobian-vector products or JVPs.
+    This function could have been named `jvp!`.
 """
 function pushforward! end
 

DifferentiationInterface/src/second_order/hessian.jl

@@ -14,27 +14,35 @@ function prepare_hessian end
     hessian(f, backend, x, [extras]) -> hess
 
 Compute the Hessian matrix of the function `f` at point `x`.
+
+$(document_preparation("hessian"))
 """
 function hessian end
 
 """
     hessian!(f, hess, backend, x, [extras]) -> hess
 
 Compute the Hessian matrix of the function `f` at point `x`, overwriting `hess`.
+
+$(document_preparation("hessian"))
 """
 function hessian! end
 
 """
     value_gradient_and_hessian(f, backend, x, [extras]) -> (y, grad, hess)
 
 Compute the value, gradient vector and Hessian matrix of the function `f` at point `x`.
+
+$(document_preparation("hessian"))
 """
 function value_gradient_and_hessian end
 
 """
     value_gradient_and_hessian!(f, grad, hess, backend, x, [extras]) -> (y, grad, hess)
 
 Compute the value, gradient vector and Hessian matrix of the function `f` at point `x`, overwriting `grad` and `hess`.
+
+$(document_preparation("hessian"))
 """
 function value_gradient_and_hessian! end
 

DifferentiationInterface/src/second_order/hvp.jl

@@ -24,13 +24,17 @@ function prepare_hvp_same_point end
     hvp(f, backend, x, dx, [extras]) -> dg
 
 Compute the Hessian-vector product of `f` at point `x` with seed `dx`.
+
+$(document_preparation("hvp"; same_point=true))
 """
 function hvp end
 
 """
     hvp!(f, dg, backend, x, dx, [extras]) -> dg
 
 Compute the Hessian-vector product of `f` at point `x` with seed `dx`, overwriting `dg`.
+
+$(document_preparation("hvp"; same_point=true))
 """
 function hvp! end
 

DifferentiationInterface/src/second_order/second_derivative.jl

@@ -14,27 +14,35 @@ function prepare_second_derivative end
     second_derivative(f, backend, x, [extras]) -> der2
 
 Compute the second derivative of the function `f` at point `x`.
+
+$(document_preparation("second_derivative"))
 """
 function second_derivative end
 
 """
     second_derivative!(f, der2, backend, x, [extras]) -> der2
 
 Compute the second derivative of the function `f` at point `x`, overwriting `der2`.
+
+$(document_preparation("second_derivative"))
 """
 function second_derivative! end
 
 """
     value_derivative_and_second_derivative(f, backend, x, [extras]) -> (y, der, der2)
 
 Compute the value, first derivative and second derivative of the function `f` at point `x`.
+
+$(document_preparation("second_derivative"))
 """
 function value_derivative_and_second_derivative end
 
 """
     value_derivative_and_second_derivative!(f, der, der2, backend, x, [extras]) -> (y, der, der2)
 
 Compute the value, first derivative and second derivative of the function `f` at point `x`, overwriting `der` and `der2`.
+
+$(document_preparation("second_derivative"))
 """
 function value_derivative_and_second_derivative! end
 

DifferentiationInterface/src/utils/printing.jl

@@ -9,3 +9,11 @@ function package_name(b::AbstractADType)
 end
 
 package_name(b::AutoSparse) = package_name(dense_ad(b))
+
+function document_preparation(operator_name::AbstractString; same_point=false)
+    if same_point
+        return "To improve performance via operator preparation, refer to [`prepare_$(operator_name)`](@ref) and [`prepare_$(operator_name)_same_point`](@ref)."
+    else
+        return "To improve performance via operator preparation, refer to [`prepare_$(operator_name)`](@ref)."
+    end
+end