Simple functions and general functions

A simple function is one which returns a single value calculated from its arguments, and does not provide derivatives. A general function returns more than one value, because it calculates an array of results, or because it calculates derivatives, or both.

Because of restrictions in the various types of linkage, not all types of function can be declared and used in all languages. Any limitations are described in the appropriate sections.

For simplicity, the functions will be described using only examples in C. Implementation in other languages follows the same rules.

Simple user functions

A simple user function returns only one value and does not calculate derivatives. It therefore does not use the ReturnNames, Deltas or ReturnArray arguments.

The full form of the declaration is:

double XPRS_CC MyFunc(double *InputValues, int *FunctionInfo,
                    char *InputNames);

FunctionInfo can be omitted if the number of arguments is not required, and access to problem information and function objects is not required.
InputNames can be omitted if the input values are identified by position and not by name (see "Programming Techniques for User Functions" below).

The function supplies its single result as the return value of the function.

There is no provision for indicating that an error has occurred, so the function must always be able to calculate a value.

General user functions returning an array of values through a reference

General user functions calculate more than one value, and the results are returned as an array. In the first form of a general function, the values are supplied by returning the address of an array which holds the values. See the notes below for restrictions on the use of this method.

The full form of the declaration is:

double * XPRS_CC MyFunc(double *InputValues, int *FunctionInfo,
                    char *InputNames, char *ReturnNames
                    double *Deltas);

FunctionInfo can be omitted if the number of arguments is not required, no derivatives are being calculated, the number of return values is fixed, and access to problem information and function objects is not required. However, it is recommended that FunctionInfo is always included.

InputNames can be omitted if the input values are identified by position and not by name (see "Programming Techniques for User Functions" below).

ReturnNames can be omitted if the return values are identified by position and not by name (see "Programming Techniques for User Functions" below).

Deltas must be omitted if no derivatives are calculated.

The function supplies the address of an array of results. This array must be available after the function has returned to its caller, and so is normally a static array. This may mean that the function cannot be called from a multi-threaded optimization, or where multiple instances of the function are required, because the single copy of the array may be overwritten by another call to the function. An alternative method is to use a function object which refers to an array specific to the thread or problem being optimized.

Deltas is an array with the same number of items as InputValues. It is used as an indication of which derivatives (if any) are required on a particular function call. If Deltas[i] is zero then a derivative for input variable i is not required and must not be returned. If Deltas[i] is nonzero then a derivative for input variable i is required and must be returned. The total number of nonzero entries in Deltas is given in FunctionInfo[2]. In particular, if it is zero, then no derivatives are required at all.

When no derivatives are calculated, the array of return values simply contains the results (in the order specified by ReturnNames if used).
When derivatives are calculated, the array contains the values and the derivatives as follows (DVi is the i^th variable for which derivatives are required, which may not be the same as the i^th input value):
 Result1
 Derivative of Result1 w.r.t. DV1
 Derivative of Result1 w.r.t. DV2
 ...
 Derivative of Result1 w.r.t. DVn
 Result2
 Derivative of Result2 w.r.t. DV1
 Derivative of Result2 w.r.t. DV2
 ...
 Derivative of Result2 w.r.t. DVn
 ...
 Derivative of Resultm w.r.t. DVn

It is therefore important to check whether derivatives are required and, if so, how many.

This form must be used by user functions which are called through OLE automation (VBA (Excel) and COM) because they cannot directly access the memory areas of the main program.

This form cannot be used by Fortran programs because Fortran functions can only return a single value, not an array.

This form cannot be used by Mosel programs because Mosel functions can only return a single value, not an array.

General user functions returning an array of values through an argument

General user functions calculate more than one value, and the results are returned as an array. In the second form of a general function, the values are supplied by returning the values in an array provided as an argument to the function by the calling program. See the notes below for restrictions on the use of this method.

The full form of the declaration is:

double XPRS_CC MyFunc(double *InputValues, int *FunctionInfo,
                    char *InputNames, char *ReturnNames
                    double *Deltas, double *ReturnArray);

FunctionInfo can be omitted if the number of arguments is not required, no derivatives are being calculated, the number of return values is fixed, and access to problem information and function objects is not required. However, it is recommended that FunctionInfo is always included.

InputNames can be omitted if the input values are identified by position and not by name (see "Programming Techniques for User Functions" below).

ReturnNames can be omitted if the return values are identified by position and not by name (see "Programming Techniques for User Functions" below).

Deltas must be omitted if no derivatives are calculated.

The function must supply the results in the array ReturnArray. This array is guaranteed to be large enough to hold all the values requested by the calling program. No guarantee is given that the results will be retained between function calls.

Deltas is an array with the same number of items as InputValues. It is used as an indication of which derivatives (if any) are required on a particular function call. If Deltas[i] is zero then a derivative for input variable i is not required and must not be returned. If Deltas[i] is nonzero then a derivative for input variable i is required and must be returned. The total number of nonzero entries in Deltas is given in FunctionInfo[2]. In particular, if it is zero, then no derivatives are required at all.

When no derivatives are calculated, the array of return values simply contains the results (in the order specified by ReturnNames if used).
When derivatives are calculated, the array contains the values and the derivatives as follows (DVi is the i^th variable for which derivatives are required, which may not be the same as the i^th input value):
 Result1
 Derivative of Result1 w.r.t. DV1
 Derivative of Result1 w.r.t. DV2
 ...
 Derivative of Result1 w.r.t. DVn
 Result2
 Derivative of Result2 w.r.t. DV1
 Derivative of Result2 w.r.t. DV2
 ...
 Derivative of Result2 w.r.t. DVn
 ...
 Derivative of Resultm w.r.t. DVn

It is therefore important to check whether derivatives are required and, if so, how many.

The return value of the function is a status code indicating whether the function has completed normally. Possible values are:

0

No errors: the function has completed normally.

1

The function has encountered an error. This will terminate the optimization.

-1

The calling function must estimate the function value from the last set of values calculated. This will cause an error if no values are available.

This form must be not used by user functions which are called through OLE automation (VBA (Excel) and COM) because they cannot directly access the memory areas (in particular ReturnArray) in the main program.

This form must be used by Fortran programs because Fortran functions can only return a single value, not an array. An array of values must therefore be returned through ReturnArray.

This form must be used by Mosel programs because Mosel functions can only return a single value, not an array. An array of values must therefore be returned through ReturnArray.