User function interface

In its simplest form, a user function is exactly the same as any other mathematical function: it takes a set of arguments (constants or values of variables) and returns a value as its result. In this form, which is the usual implementation, the function needs no information apart from the values of its arguments. It is possible to create more complicated functions which do use external data in some form: these are discussed at the end of this section.

Xpress NonLinear supports two basic forms of user function. The simple form of function returns a single value, and is treated in essentially the same way as a normal mathematical function. The general form of function returns an array of values and may also perform automatic differentiation.

The main difference between the simple and general form of a user function is in the way the value is returned.

• The simple function calculates and returns one value and is declared as such (for example, double in C).
• The general function calculates an array of values. It can either return the array itself (and is declared as such: for example, double * in C), or it can return the results in one of the function arguments, in which case the function itself returns a single (double precision) status value (and is declared as such: for example double in C).

Values are passed to and from the function in a format dependent on the type of the function and the type of the argument.

• NULL format provides a place-holder for the argument but it is a null or empty argument which cannot be used to access or return data. This differs from the omitted argument which does not appear at all.
• INTEGER format is used only for the Function Information array (the second argument to the function).
• DOUBLE format is used for passing and returning all other numeric values
• CHAR format is used for passing character information to the function (input and return variable names)
• VARIANT format is used for user functions written in Microsoft Excel, COM. All arguments in Xpress NonLinear are then of type VARIANT, which is the same as the Variant type in COM and Excel VBA. In the function source code, the function itself is declared with all its arguments and return value(s) as Variant. VARIANT is not available for user functions called through other linkage mechanisms.