JuliaDiff / JuliaDiff/DifferentiationInterface.jl

documentation: clarify role of mutable arguments for operators like `jacobian!`

Open
#977 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

core documentation
Dominant language
Julia
Stars
313
Forks
35
PR merge metrics
No merged PRs in 30d

Description

Hi, thanks for the great package.
I have been wondering about the role of mutable arguments for inplace operators based on inplace functions and could not find decisive information in the documentation.
Currently, the documentation only notes that

The positional arguments between f/f! and backend are always mutated, regardless of the bang ! in the operator name. In particular, for in-place functions f!(y, x), every variant of every operator will mutate y.

In a call DI.jacobian!(f!, y, Dy, backend, x), should y be considered just a temporary array? Or does it generally also hold the primal result values (like with DI.value_and_jacobian!)?
This question has been raised as well by @adrhill in #6 but I could not find an answer skimming the superseding issues.
When testing with ForwardDiff the array y holds the result:

import ForwardDiff
import DifferentiationInterface as DI

## out-of-place test function, ℝ³ → ℝ²
f(x) = [ sum(x); sum(abs2, x) ]
## inplace test function, ℝ³ → ℝ²
f!(y, x) = begin
    y[1] = sum(x)
    y[2] = sum(abs2, x)
    return nothing 
end

## test point
x = [1.0, 2.0, 3.0]
## use `ForwardDiff` for testing
bcknd = DI.AutoForwardDiff()

## compute Jacobian inplace, from out-of-place function:
Dy_oop = similar(x, 2, 3)
DI.jacobian!(f, Dy_oop, bcknd, x)

## compute Jacobian inplace, from inplace function:
y_tmp = similar(x, 2)       # scratch?
Dy_ip = similar(x, 2, 3)
DI.jacobian!(f!, y_tmp, Dy_ip, bcknd, x)

## Jacobian result matrices are equal …
@assert Dy_ip == Dy_oop
## … but `y_tmp` also holds correct result
@assert y_tmp == f(x)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Operators documentation, especially the “Warning” section linked in the issue, and reproduce the provided DI.jacobian! example with ForwardDiff. Check the related discussion in #6 and the superseding issues mentioned there. Done means documenting whether mutable arguments such as y retain primal results or serve only as scratch storage, including how this differs from value_and_jacobian!.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.