Jacobian information for external function

[arn1m]

Hi,
I am currently playing around with using external functions, i.e., writing them in C, compiling a shared library and importing them into CasADi in Matlab.
So far this works very well and I've figured out how to provide the Jacobian information as well.

Just one minor question:
Assume, I define a function f(x, u). After loading it via external in CasADi I get the following information for f.jacobian:
jac_f:(x[2],u[2],out_Dx[2x1,0nz])->(jac_Dx_x[2x2],jac_Dx_u[2x2]) External

What is the meaning of out_Dx[2x1,0nz] in there, which seems to be zeros here as no non-zero entries are expected?

This gets especially interesting when providing Hessian matrix information, i.e., via jac_jac_f ...

For completeness, I have my external function definition attached: system.c

Thanks and regards,
Arnim

[mohammadrezwankhan]

out_Dx is part of CasADi's canonical full-Jacobian function signature; it is not another derivative or a seed.

For an original function

f: (x, u) -> (Dx)

Function::jacobian() constructs a function shaped like

jac_f: (x, u, out_Dx) -> (jac_Dx_x, jac_Dx_u)

CasADi documents that convention directly in Function::jacobian(): the original outputs are appended to the derivative function's inputs, and inputs that the derivative routine does not need are represented as all-zero sparse matrices with the correct dimensions.

So the display

out_Dx[2x1,0nz]

means "a 2-by-1 slot with zero structural nonzeros because this Jacobian routine does not need the already-computed value of Dx." It does not mean that f(x,u) is numerically zero. Your jac_f is therefore right not to dereference that slot.

For the attached function, the mapping is:

arg[0] -> x
arg[1] -> u
arg[2] -> out_Dx (unused here)

res[0] -> d(Dx)/dx
res[1] -> d(Dx)/du

The four entries you write for d(Dx)/dx are also in CasADi's column-major order:

[ 3*x(1)^2,  2
  1,         -2*x(2) ]

becomes {3*x0^2, 1, 2, -2*x1} in the C result buffer, which matches your code.

The same convention recurses for jac_jac_f: it is the Jacobian of jac_f, so its signature contains the inputs and outputs of jac_f before the second-derivative blocks. One important caution is that the current empty implementation

casadi_int jac_jac_f(...) { return 0; }

reports success without populating any result buffers. I would remove that exported symbol until it is fully implemented, or implement its complete input/output metadata, sparsities, and values. Otherwise CasADi may discover it as an available derivative callback and consume uninitialized/incorrect second derivatives. The external-function naming convention is described in the CasADi custom-function guide.

[arn1m]

Hi,
thank you very much for the detailed explanation! That perfectly answers the question.

Kind regards,
Arnim