Merge branch 'master' into Require-Julia-LTS

devmotion · web-flow · commit e8b422e89052 · 2025-08-18T17:07:11.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -1,4 +1,5 @@
 name: CI
+
 on:
   pull_request:
     branches:
@@ -8,52 +9,50 @@ on:
       - master
     tags: '*'
   workflow_dispatch:
+
+# needed to allow julia-actions/cache to delete old caches that it has created
+permissions:
+  actions: write
+  contents: read
+
 jobs:
   test:
-    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ matrix.version == 'nightly' }}
     strategy:
       fail-fast: false
       matrix:
         version:
+          - 'min'
           - 'lts'
           - '1'
-          # - 'nightly'
         os:
           - ubuntu-latest
-        arch:
-          - x64
+          - windows-latest
+          - macOS-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
-          arch: ${{ matrix.arch }}
-      - uses: actions/cache@v4
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
+      - uses: julia-actions/cache@v2
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
-          file: lcov.info
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true
   docs:
     name: Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
+      - uses: julia-actions/cache@v2
       - run: |
           julia --project=docs -e '
             using Pkg
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "ForwardDiff"
 uuid = "f6369f11-7733-5829-9624-2563aa707210"
-version = "0.11.0-DEV"
+version = "1.0.1"
 
 [deps]
 CommonSubexpressions = "bbf7d656-a473-5ed7-a52c-81e309532950"
diff --git a/README.md b/README.md
@@ -1,11 +1,19 @@
-[![CI](https://github.com/JuliaDiff/ForwardDiff.jl/workflows/CI/badge.svg)](https://github.com/JuliaDiff/ForwardDiff.jl/actions/workflows/ci.yml)
-[![Coverage Status](https://coveralls.io/repos/JuliaDiff/ForwardDiff.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/JuliaDiff/ForwardDiff.jl?branch=master)
+[![CI](https://github.com/JuliaDiff/ForwardDiff.jl/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/JuliaDiff/ForwardDiff.jl/actions/workflows/ci.yml?query=branch%3Amaster)
+[![codecov](https://codecov.io/gh/JuliaDiff/ForwardDiff.jl/graph/badge.svg?token=SzHfhyoxUa)](https://codecov.io/gh/JuliaDiff/ForwardDiff.jl)
 
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliadiff.org/ForwardDiff.jl/stable)
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliadiff.org/ForwardDiff.jl/dev)
 
 # ForwardDiff.jl
 
+## Upgrading to ForwardDiff.jl 1.0
+
+Equality (`==`) on `Dual` numbers now requires both the real and dual part to match (https://github.com/JuliaDiff/ForwardDiff.jl/pull/481).
+This removes a large number of bugs where the "structure" of e.g, non-zero values in an array was inspected, leading to erroneous derivatives.
+This might cause slightly different behavior in programs but should in general be more correct than previously.
+
+---------------------------
+
 ForwardDiff implements methods to take **derivatives**, **gradients**, **Jacobians**, **Hessians**, and higher-order derivatives of native Julia functions (or any callable object, really) using **forward mode automatic differentiation (AD)**.
 
 While performance can vary depending on the functions you evaluate, the algorithms implemented by ForwardDiff generally outperform non-AD algorithms (such as finite-differencing) in both speed and accuracy.
diff --git a/docs/src/dev/how_it_works.md b/docs/src/dev/how_it_works.md
@@ -56,8 +56,9 @@ learn about [hyper-dual numbers](https://arc.aiaa.org/doi/abs/10.2514/6.2011-886
 which extend dual numbers to higher orders by introducing extra ``\epsilon`` terms that can
 cross-multiply. ForwardDiff's `Dual` number implementation naturally supports hyper-dual
 numbers without additional code by allowing instances of the `Dual` type to nest within each
-other. For example, a second-order hyper-dual number has the type `Dual{T,Dual{S,V,M},N}`, a
-third-order hyper-dual number has the type `Dual{T,Dual{S,Dual{R,V,K},M},N}`, and so on.
+other. For example, a second-order hyper-dual number has the type `Dual{T,Dual{S,V,M},N}`,
+and can be formed as follows: `Dual(Dual(x, one(eltype(x))), one(eltype(x)))`. A third-order
+hyper-dual number has the type `Dual{T,Dual{S,Dual{R,V,K},M},N}`, and so on.
 
 ## ForwardDiff's API
 
diff --git a/docs/src/user/limitations.md b/docs/src/user/limitations.md
@@ -7,6 +7,8 @@ function being differentiated):
 
 - **The target function can only be composed of generic Julia functions.** ForwardDiff cannot propagate derivative information through non-Julia code. Thus, your function may not work if it makes calls to external, non-Julia programs, e.g. uses explicit BLAS calls instead of `Ax_mul_Bx`-style functions.
 
+- **The target function must be a composition of differentiable functions.** ForwardDiff can have issues to compute derivatives of functions, which are composed of at least one function, which is not differentiable in the point the derivative should be evaluated, even if the target function itself is differentiable. A simple example is `f(x) = norm(x)^2`, where `ForwardDiff.gradient(f, zeros(2))` returns a vector of `NaN`s since the Euclidean norm is not differentiable in zero. A possible solution to this issue is to, e.g., define `f(x) = sum(abs2, x)` instead. In situations, where rewriting the target function only as a composition of differentiable functions is more complicated (e.g. `f(x) = (1 + norm(x))exp(-norm(x))`)), one would need to define a custom derivative rule (see [this comment](https://github.com/JuliaDiff/ForwardDiff.jl/issues/303#issuecomment-2977990425)).
+
 - **The target function must be unary (i.e., only accept a single argument).** [`ForwardDiff.jacobian`](@ref) is an exception to this rule.
 
 - **The target function must be written generically enough to accept numbers of type `T<:Real` as input (or arrays of these numbers).** The function doesn't require a specific type signature, as long as the type signature is generic enough to avoid breaking this rule. This also means that any storage assigned used within the function must be generic as well (see [this comment](https://github.com/JuliaDiff/ForwardDiff.jl/issues/136#issuecomment-237941790) for an example).
diff --git a/ext/ForwardDiffStaticArraysExt.jl b/ext/ForwardDiffStaticArraysExt.jl
@@ -103,16 +103,16 @@ end
     T = typeof(Tag(f, eltype(x)))
     ydual = static_dual_eval(T, f, x)
     result = DiffResults.jacobian!(result, extract_jacobian(T, ydual, x))
-    result = DiffResults.value!(d -> value(T,d), result, ydual)
+    result = DiffResults.value!(Base.Fix1(value, T), result, ydual)
     return result
 end
 
 # Hessian
-ForwardDiff.hessian(f::F, x::StaticArray) where {F} = jacobian(y -> gradient(f, y), x)
+ForwardDiff.hessian(f::F, x::StaticArray) where {F} = jacobian(Base.Fix1(gradient, f), x)
 ForwardDiff.hessian(f::F, x::StaticArray, cfg::HessianConfig) where {F} = hessian(f, x)
 ForwardDiff.hessian(f::F, x::StaticArray, cfg::HessianConfig, ::Val) where {F} = hessian(f, x)
 
-ForwardDiff.hessian!(result::AbstractArray, f::F, x::StaticArray) where {F} = jacobian!(result, y -> gradient(f, y), x)
+ForwardDiff.hessian!(result::AbstractArray, f::F, x::StaticArray) where {F} = jacobian!(result, Base.Fix1(gradient, f), x)
 
 ForwardDiff.hessian!(result::MutableDiffResult, f::F, x::StaticArray) where {F} = hessian!(result, f, x, HessianConfig(f, result, x))
 
diff --git a/src/apiutils.jl b/src/apiutils.jl
@@ -40,32 +40,68 @@ end
     return Expr(:tuple, [:(single_seed(Partials{N,V}, Val{$i}())) for i in 1:N]...)
 end
 
+# Only seed indices that are structurally non-zero
+structural_eachindex(x::AbstractArray) = structural_eachindex(x, x)
+function structural_eachindex(x::AbstractArray, y::AbstractArray)
+    require_one_based_indexing(x, y)
+    eachindex(x, y)
+end
+function structural_eachindex(x::UpperTriangular, y::AbstractArray)
+    require_one_based_indexing(x, y)
+    if size(x) != size(y)
+        throw(DimensionMismatch())
+    end
+    n = size(x, 1)
+    return (CartesianIndex(i, j) for j in 1:n for i in 1:j)
+end
+function structural_eachindex(x::LowerTriangular, y::AbstractArray)
+    require_one_based_indexing(x, y)
+    if size(x) != size(y)
+        throw(DimensionMismatch())
+    end
+    n = size(x, 1)
+    return (CartesianIndex(i, j) for j in 1:n for i in j:n)
+end
+function structural_eachindex(x::Diagonal, y::AbstractArray)
+    require_one_based_indexing(x, y)
+    if size(x) != size(y)
+        throw(DimensionMismatch())
+    end
+    return diagind(x)
+end
+
 function seed!(duals::AbstractArray{Dual{T,V,N}}, x,
                seed::Partials{N,V} = zero(Partials{N,V})) where {T,V,N}
-    duals .= Dual{T,V,N}.(x, Ref(seed))
+    for idx in structural_eachindex(duals, x)
+        duals[idx] = Dual{T,V,N}(x[idx], seed)
+    end
     return duals
 end
 
 function seed!(duals::AbstractArray{Dual{T,V,N}}, x,
                seeds::NTuple{N,Partials{N,V}}) where {T,V,N}
-    dual_inds = 1:N
-    duals[dual_inds] .= Dual{T,V,N}.(view(x,dual_inds), seeds)
+    for (i, idx) in zip(1:N, structural_eachindex(duals, x))
+        duals[idx] = Dual{T,V,N}(x[idx], seeds[i])
+    end
     return duals
 end
 
 function seed!(duals::AbstractArray{Dual{T,V,N}}, x, index,
                seed::Partials{N,V} = zero(Partials{N,V})) where {T,V,N}
     offset = index - 1
-    dual_inds = (1:N) .+ offset
-    duals[dual_inds] .= Dual{T,V,N}.(view(x, dual_inds), Ref(seed))
+    idxs = Iterators.drop(structural_eachindex(duals, x), offset)
+    for idx in idxs
+        duals[idx] = Dual{T,V,N}(x[idx], seed)
+    end
     return duals
 end
 
 function seed!(duals::AbstractArray{Dual{T,V,N}}, x, index,
                seeds::NTuple{N,Partials{N,V}}, chunksize = N) where {T,V,N}
     offset = index - 1
-    seed_inds = 1:chunksize
-    dual_inds = seed_inds .+ offset
-    duals[dual_inds] .= Dual{T,V,N}.(view(x, dual_inds), getindex.(Ref(seeds), seed_inds))
+    idxs = Iterators.drop(structural_eachindex(duals, x), offset)
+    for (i, idx) in zip(1:chunksize, idxs)
+        duals[idx] = Dual{T,V,N}(x[idx], seeds[i])
+    end
     return duals
 end
diff --git a/src/config.jl b/src/config.jl
@@ -64,10 +64,10 @@ struct DerivativeConfig{T,D} <: AbstractConfig{1}
 end
 
 """
-    ForwardDiff.DerivativeConfig(f!, y::AbstractArray, x::AbstractArray)
+    ForwardDiff.DerivativeConfig(f!, y::AbstractArray, x::Real)
 
 Return a `DerivativeConfig` instance based on the type of `f!`, and the types/shapes of the
-output vector `y` and the input vector `x`.
+output vector `y` and the input value `x`.
 
 The returned `DerivativeConfig` instance contains all the work buffers required by
 `ForwardDiff.derivative` and `ForwardDiff.derivative!` when the target function takes the form
diff --git a/src/gradient.jl b/src/gradient.jl
@@ -16,7 +16,7 @@ Set `check` to `Val{false}()` to disable tag checking. This can lead to perturba
 function gradient(f::F, x::AbstractArray, cfg::GradientConfig{T} = GradientConfig(f, x), ::Val{CHK}=Val{true}()) where {F, T, CHK}
     require_one_based_indexing(x)
     CHK && checktag(T, f, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         return vector_mode_gradient(f, x, cfg)
     else
         return chunk_mode_gradient(f, x, cfg)
@@ -35,7 +35,7 @@ This method assumes that `isa(f(x), Real)`.
 function gradient!(result::Union{AbstractArray,DiffResult}, f::F, x::AbstractArray, cfg::GradientConfig{T} = GradientConfig(f, x), ::Val{CHK}=Val{true}()) where {T, CHK, F}
     result isa DiffResult ? require_one_based_indexing(x) : require_one_based_indexing(result, x)
     CHK && checktag(T, f, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         vector_mode_gradient!(result, f, x, cfg)
     else
         chunk_mode_gradient!(result, f, x, cfg)
@@ -63,12 +63,19 @@ function extract_gradient!(::Type{T}, result::DiffResult, dual::Dual) where {T}
 end
 
 extract_gradient!(::Type{T}, result::AbstractArray, y::Real) where {T} = fill!(result, zero(y))
-extract_gradient!(::Type{T}, result::AbstractArray, dual::Dual) where {T}= copyto!(result, partials(T, dual))
+function extract_gradient!(::Type{T}, result::AbstractArray, dual::Dual) where {T}
+    idxs = structural_eachindex(result)
+    for (i, idx) in zip(1:npartials(dual), idxs)
+        result[idx] = partials(T, dual, i)
+    end
+    return result
+end
 
 function extract_gradient_chunk!(::Type{T}, result, dual, index, chunksize) where {T}
     offset = index - 1
-    for i in 1:chunksize
-        result[i + offset] = partials(T, dual, i)
+    idxs = Iterators.drop(structural_eachindex(result), offset)
+    for (i, idx) in zip(1:chunksize, idxs)
+        result[idx] = partials(T, dual, i)
     end
     return result
 end
@@ -106,10 +113,10 @@ end
 
 function chunk_mode_gradient_expr(result_definition::Expr)
     return quote
-        @assert length(x) >= N "chunk size cannot be greater than length(x) ($(N) > $(length(x)))"
+        @assert structural_length(x) >= N "chunk size cannot be greater than ForwardDiff.structural_length(x) ($(N) > $(structural_length(x)))"
 
         # precalculate loop bounds
-        xlen = length(x)
+        xlen = structural_length(x)
         remainder = xlen % N
         lastchunksize = ifelse(remainder == 0, N, remainder)
         lastchunkindex = xlen - lastchunksize + 1
diff --git a/src/jacobian.jl b/src/jacobian.jl
@@ -18,7 +18,7 @@ Set `check` to `Val{false}()` to disable tag checking. This can lead to perturba
 function jacobian(f::F, x::AbstractArray, cfg::JacobianConfig{T} = JacobianConfig(f, x), ::Val{CHK}=Val{true}()) where {F,T,CHK}
     require_one_based_indexing(x)
     CHK && checktag(T, f, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         return vector_mode_jacobian(f, x, cfg)
     else
         return chunk_mode_jacobian(f, x, cfg)
@@ -36,7 +36,7 @@ Set `check` to `Val{false}()` to disable tag checking. This can lead to perturba
 function jacobian(f!::F, y::AbstractArray, x::AbstractArray, cfg::JacobianConfig{T} = JacobianConfig(f!, y, x), ::Val{CHK}=Val{true}()) where {F,T, CHK}
     require_one_based_indexing(y, x)
     CHK && checktag(T, f!, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         return vector_mode_jacobian(f!, y, x, cfg)
     else
         return chunk_mode_jacobian(f!, y, x, cfg)
@@ -57,7 +57,7 @@ Set `check` to `Val{false}()` to disable tag checking. This can lead to perturba
 function jacobian!(result::Union{AbstractArray,DiffResult}, f::F, x::AbstractArray, cfg::JacobianConfig{T} = JacobianConfig(f, x), ::Val{CHK}=Val{true}()) where {F,T, CHK}
     result isa DiffResult ? require_one_based_indexing(x) : require_one_based_indexing(result, x)
     CHK && checktag(T, f, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         vector_mode_jacobian!(result, f, x, cfg)
     else
         chunk_mode_jacobian!(result, f, x, cfg)
@@ -78,7 +78,7 @@ Set `check` to `Val{false}()` to disable tag checking. This can lead to perturba
 function jacobian!(result::Union{AbstractArray,DiffResult}, f!::F, y::AbstractArray, x::AbstractArray, cfg::JacobianConfig{T} = JacobianConfig(f!, y, x), ::Val{CHK}=Val{true}()) where {F,T,CHK}
     result isa DiffResult ? require_one_based_indexing(y, x) : require_one_based_indexing(result, y, x)
     CHK && checktag(T, f!, x)
-    if chunksize(cfg) == length(x)
+    if chunksize(cfg) == structural_length(x)
         vector_mode_jacobian!(result, f!, y, x, cfg)
     else
         chunk_mode_jacobian!(result, f!, y, x, cfg)
@@ -169,10 +169,10 @@ const JACOBIAN_ERROR = DimensionMismatch("jacobian(f, x) expects that f(x) is an
 function jacobian_chunk_mode_expr(work_array_definition::Expr, compute_ydual::Expr,
                                   result_definition::Expr, y_definition::Expr)
     return quote
-        @assert length(x) >= N "chunk size cannot be greater than length(x) ($(N) > $(length(x)))"
+        @assert structural_length(x) >= N "chunk size cannot be greater than ForwardDiff.structural_length(x) ($(N) > $(structural_length(x)))"
 
         # precalculate loop bounds
-        xlen = length(x)
+        xlen = structural_length(x)
         remainder = xlen % N
         lastchunksize = ifelse(remainder == 0, N, remainder)
         lastchunkindex = xlen - lastchunksize + 1
diff --git a/src/prelude.jl b/src/prelude.jl
@@ -12,8 +12,15 @@ function Chunk(input_length::Integer, threshold::Integer = DEFAULT_CHUNK_THRESHO
     Base.@nif 12 d->(N == d) d->(Chunk{d}()) d->(Chunk{N}())
 end
 
+structural_length(x::AbstractArray) = length(x)
+function structural_length(x::Union{LowerTriangular,UpperTriangular})
+    n = size(x, 1)
+    return (n * (n + 1)) >> 1
+end
+structural_length(x::Diagonal) = size(x, 1)
+
 function Chunk(x::AbstractArray, threshold::Integer = DEFAULT_CHUNK_THRESHOLD)
-    return Chunk(length(x), threshold)
+    return Chunk(structural_length(x), threshold)
 end
 
 # Constrained to `N <= threshold`, minimize (in order of priority):
diff --git a/test/AllocationsTest.jl b/test/AllocationsTest.jl
@@ -24,20 +24,12 @@ convert_test_574() = convert(ForwardDiff.Dual{Nothing,ForwardDiff.Dual{Nothing,F
     index = 1
     alloc = @allocated ForwardDiff.seed!(duals, x, index, seeds)
     alloc = @allocated ForwardDiff.seed!(duals, x, index, seeds)
-    if VERSION >= v"1.11"
-        @test alloc == 0
-    else
-        @test_broken alloc == 0
-    end
+    @test alloc == 0
 
     index = 1
     alloc = @allocated ForwardDiff.seed!(duals, x, index, seed)
     alloc = @allocated ForwardDiff.seed!(duals, x, index, seed)
-    if VERSION >= v"1.11"
-        @test alloc == 0
-    else
-        @test_broken alloc == 0
-    end
+    @test alloc == 0
 
     alloc = @allocated convert_test_574()
     alloc = @allocated convert_test_574()
diff --git a/test/GradientTest.jl b/test/GradientTest.jl
diff --git a/test/JacobianTest.jl b/test/JacobianTest.jl
