README example

[willtebbutt]

At present the main example in the README is:

using DifferentiationInterface
import ForwardDiff, Enzyme, Zygote  # AD backends you want to use 

f(x) = sum(abs2, x)

x = [1.0, 2.0]

value_and_gradient(f, AutoForwardDiff(), x) # returns (5.0, [2.0, 4.0]) with ForwardDiff.jl
value_and_gradient(f, AutoEnzyme(),      x) # returns (5.0, [2.0, 4.0]) with Enzyme.jl
value_and_gradient(f, AutoZygote(),      x) # returns (5.0, [2.0, 4.0]) with Zygote.jl

Would it be better to make this example one which includes the extras = prepare_gradient(f, backend, x) etc stuff?

I'm just thinking about the issue we had on Tapir.jl the other day, where a user didn't realise that you should really be using prepare_gradient in general. My general point is: if a user sees one example, maybe they should see one which we think is likely to give best performance across all backends?

[gdalle]

Good point. Then again many people use ForwardDiff without even knowing about config and chunks, and it's still decently fast. Preparation features prominently in the tutorial and overview pages of the docs, so I am torn as to whether it belongs in the README. @adrhill thoughts?

[adrhill]

The point of the current README is to demonstrate to the average, time-deprived developer that DI is an easy to use, unified interface for Julia's many AD backends. I personally wouldn't want to complicate this example too much.

We follow it up by the disclaimer "For more performance, take a look at the DifferentiationInterface tutorial", which implies sub-optimal performance in the code example. I guess we could further emphasize this disclaimer and possibly add a short second code block demonstrating preparation?

maybe [users] should see one [example] which we think is likely to give best performance across all backends?

PR #255 introduces additional preparation functions for static points of linearization, so the optimal operator preparation is about to be problem dependent.

[adrhill]

I guess we could further emphasize this disclaimer and possibly add a short second code block demonstrating preparation?

I should stress that my preferred approach would be to direct users to the documentation, which they should definitely read.
Maybe something like this could be the solution?

To improve your performance by up to an order of magnitude compared to this example, take a look at the DifferentiationInterface tutorial.

[willtebbutt]

I should stress that my preferred approach would be to direct users to the documentation, which they should definitely read. Maybe something like this could be the solution?

I really like this. Perhaps you could strengthen then statement even more though? In the case of Tapir, not preparing can yield many orders of magnitude worse performance.

[gdalle]

By the way I also really liked it when the README was tested @adrhill, we could reintroduce that as well

[willtebbutt]

For the record -- I think basically any of the solutions proposed here are great, so I will not be offended if you close this issue without further consulting me!