What does "multi point derivatives" mean?

[gdalle]

I'm not sure I understand what this function does: https://docs.sciml.ai/FiniteDiff/stable/#Multi-Point-Derivatives

[ChrisRackauckas]

That's just a header? I'm not sure what you're pointing to since that's just a header for derivatives, gradients, and jacobians.

[gdalle]

I pointed to the function finite_difference_derivative when applied to an array input.

In the docs the following list of headers exists:

• scalar derivatives
• "multi point derivatives"
• gradients
• jacobians
• hessians

The term derivative usually applies to a function $f: R \to R$, or more generally $R \to R^m$, but in any case it takes a scalar input point.
Reading "multi point derivative" I imagine we have to supply several input points $x^{(1)},x^{(2)},x^{(3)}$ to this routine, and we get several derivatives, one at each point $f'(x^{(1)}),f'(x^{(2)}),f'(x^{(3)})$.
The source code gives me confirmation of that, but for lack of docstrings I was a bit confused when only reading the docs.

FiniteDiff.jl/src/derivatives.jl

Lines 71 to 74 in be7777f

	#=
	Compute the derivative df of a scalar-valued map f at a collection of points x.
	=#
	function finite_difference_derivative(

[ChrisRackauckas]

They are different levels of headers. That's an H2 while the others are H3.

[gdalle]

If "multi point derivatives" is intended to be one level lower than derivative, gradient, jacobian and hessian, then that will make it much clearer indeed. But the toc doesn't suggest it

[ChrisRackauckas]

It should just be multi-dimensional derivatives. I edited that already, and subsetting the header I thought was done already.

[gdalle]

Okay thanks. But that might be confusing for another reason: "multi dimensional derivative" to me evokes the idea of a function $f: R \to R^m$, where the derivative is a vector. To get that we have to use finite_difference_gradient in FiniteDiff:

Gradients are either a vector->scalar map f(x), or a scalar->vector map f(fx,x) if inplace=Val{true} and fx=f(x) if inplace=Val{false}.

IIUC the section we are discussing would be better off with the original name "multi point derivative", or something like "multi input derivative", because is instead about several derivatives at different points of a function $f: R \to R$. The nesting will already improve matters :)

[ChrisRackauckas]

I'm happy to consider any wording change you PR. Call it a partial derivative of a function with one variable, the total derivative optimized to the scalar input case, or whatnot. I'm happy to go with the words others consider easiest to understand, just write it out in full in a PR

[gdalle]

Will do, thanks, just wanted to make sure I understood what it was first 😊

[gdalle]

I decided to roll up my sleeves and make a proper documentation in the process. Now the multipoint derivative is clarified in the docstrings of #182, among other things