Merge branch 'master' of https://github.com/JuliaDiff/ForwardDiff.jl …

…into patch-1
JuliaDiff · Aug 7, 2023 · 59c9cd1 · 59c9cd1
2 parents 94db0b5 + 16417ec
commit 59c9cd1
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 0 deletions.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -12,4 +12,54 @@ ForwardDiff is a registered Julia package, so it can be installed by running:
 julia> Pkg.add("ForwardDiff")
 ```
 
+Here's a simple example showing the package in action:
+
+```julia
+julia> using ForwardDiff
+
+julia> f(x::Vector) = sin(x[1]) + prod(x[2:end]);  # returns a scalar
+
+julia> x = vcat(pi/4, 2:4)
+4-element Vector{Float64}:
+ 0.7853981633974483
+ 2.0
+ 3.0
+ 4.0
+
+julia> ForwardDiff.gradient(f, x)
+4-element Vector{Float64}:
+  0.7071067811865476
+ 12.0
+  8.0
+  6.0
+
+julia> ForwardDiff.hessian(f, x)
+4×4 Matrix{Float64}:
+ -0.707107  0.0  0.0  0.0
+  0.0       0.0  4.0  3.0
+  0.0       4.0  0.0  2.0
+  0.0       3.0  2.0  0.0
+```
+
+Functions like `f` which map a vector to a scalar are the best case for reverse-mode automatic differentiation,
+but ForwardDiff may still be a good choice if `x` is not too large, as it is much simpler.
+The best case for forward-mode differentiation is a function which maps a scalar to a vector, like this `g`:
+
+```julia
+julia> g(y::Real) = [sin(y), cos(y), tan(y)];  # returns a vector
+
+julia> ForwardDiff.derivative(g, pi/4)
+3-element Vector{Float64}:
+  0.7071067811865476
+ -0.7071067811865475
+  1.9999999999999998
+
+julia> ForwardDiff.jacobian(x) do x  # anonymous function, returns a length-2 vector
+         [sin(x[1]), prod(x[2:end])]
+       end
+2×4 Matrix{Float64}:
+ 0.707107   0.0  0.0  0.0
+ 0.0       12.0  8.0  6.0
+```
+
 If you find ForwardDiff useful in your work, we kindly request that you cite [our paper](https://arxiv.org/abs/1607.07892). The relevant [BibLaTex is available in ForwardDiff's README](https://github.com/JuliaDiff/ForwardDiff.jl#publications) (not included here because BibLaTex doesn't play nice with Documenter/Jekyll).
diff --git a/test/MiscTest.jl b/test/MiscTest.jl
@@ -159,6 +159,9 @@ end
 @test ForwardDiff.derivative(x -> rem2pi(x, RoundUp), rand()) == 1
 @test ForwardDiff.derivative(x -> rem2pi(x, RoundDown), rand()) == 1
 
+# example from https://github.com/JuliaDiff/DiffRules.jl/pull/98#issuecomment-1574420052
+@test only(ForwardDiff.hessian(t -> abs(t[1])^2, [0.0])) == 2
+
 #issue 651, using Measurements
 #one(x::Measurement{T}) where T = one(T) != oneunit(x)
 f651(x) = 2.1*x + 1