D.9.1 kinsol input parameters

Functions whose names are of the form xd_zzzzz take an argument of the form (f,(i,o)), and functions whose names are of the form xj_zzzzz take an argument of the form ((f,j),(i,o)). The parameters have these interpretations.

• f is a function to be optimized, expressed in virtual machine code. It takes a list of real numbers as input and returns a list of real numbers as output. The numbers must be in floating point format as described in math.
• j is a function in virtual machine code that computes the Jacobian or partial derivatives of f for a given list of input numbers. The exact calling convention for j depends on the optimization algorithm selected, as explained below.
• i is a list of real numbers suitable as an input for f. The exact values of the numbers in i are not crucial but the length of i is taken as an indication of the required length for any input list to f. In the case of constrained optimization problems (i.e., functions with names beginning with c), i must consist entirely of non-negative numbers.
• o is a list numbers indicating the “optimal” output from f in the sense described below (kinsol output). Its length is taken to indicate the usual length of an output returned by f.

If the optimization problem is being solved by either the cj_dense or the uj_dense method, the Jacobian parameter j is expected to take a list v of real numbers the length of i as input and return a list of lists of reals as output. The numbers are represented as described in math. The outer list in the output from j is required to be the length of o, while each inner list is required to be the length of i.

The output from j is interpreted as a matrix of the form described in Two dimensional arrays. The entry in row m and column n is the partial derivative (evaluated at v) of the m-th component of the output of f with respect to the n-th item of the input list.

For optimization problems being solved by the methods of xj_gmres, xj_bicgs, or xj_tfqmr, (i.e., where x is either c or u) the Jacobian function j follows a different convention that is meant to be more memory efficient. Given an argument of the form (m,v), it returns only the m-th row of the matrix described above instead of the whole thing. The parameter m is a natural number less than the length of o, and v is a list of real numbers the length of i the same as above. The number m is encoded as described in Representation of Numeric and Textual Data.