Function Declaration in Xpress NonLinear

User functions are declared through the XSLPloaduserfuncs, XSLPadduserfuncs and XSLPchguserfunc functions, or in the SLPDATA section of the Extended MPS file format in UF type records. These declarations define which of the arguments will actually be made available to the function and (by implication) whether the function can perform automatic differentiation. Simple functions and general functions are declared in the same way. Xpress NonLinear recognizes the difference because of the way in which the functions are referenced in formulae.

Function declaration in Extended MPS format

In the SLPDATA section of Extended MPS format, the full UF record format is:

UF Function [ = Extname] ( InputValues , FunctionInfo ,
InputNames , ReturnNames , Deltas , ReturnArray )
Linkage = Param1 [ [ = Param2 ] = Param3 ]

The fields are as follows:

Function

The name of the user function. This is used in the formulae within the problem. A function which returns only one value must return it as a double-precision value. A function which returns multiple values must return a double-precision array, or return the values in the ReturnArray argument. In the latter case, the function must return a single double-precision status value.

Extname

This field is optional. If it is used, then it is the external name of the function or program when it is called. If the field is omitted, then the same name is used for the internal and external function name. If the name matches the name of a character variable, then the value of the character variable will be used instead. This allows the definition of external names which contain spaces.

InputValues

DOUBLE or VARIANT or NULL. This is the data type for the input argument list. Use NULL or omit the argument if the data is not required.

FunctionInfo

INTEGER or VARIANT or NULL. This is the data type for the array of function and argument information. Use NULL or omit the argument if the data is not required. Note that this argument is required if function objects are used by the function.

InputNames

CHAR or VARIANT or NULL. This is the data type for the names of the input arguments. Use NULL or omit the argument if the data is not required.

ReturnNames

CHAR or VARIANT or NULL. This is the data type for the names of the return arguments. Use NULL or omit the argument if the data is not required.

Deltas

DOUBLE or VARIANT or NULL. This is the data type for the perturbations (or differentiation flags). Use NULL or omit the argument if the data is not required.

ReturnArray

DOUBLE or VARIANT or NULL. This is the data type for the array of results from a multi-valued function. Use NULL or omit the argument if the results are returned directly by the function.

Linkage

This defines the linkage type and calling mechanism. The following are supported:

DLL

The function is compiled in a user library or DLL. The name of the file is in the Param1 field.

XLS

The function is in an Excel workbook and communicates through a sheet within the workbook. The name of the workbook is in the Param1 field and the name of the sheet is in the Param2 field.
If Extname is non-blank, it is the name of a macro on the workbook which is to be executed after the data is loaded.

XLF

The function is in an Excel workbook and communicates directly with Xpress NonLinear. The name of the workbook is in the Param1 field and the name of the sheet containing the function is in the Param2 field.

MOSEL

This can only be used in conjunction with Xpress-Mosel. See the Xpress Mosel User Guide (Xpress NonLinear section) for more information.

COM

This is used for a function compiled into an ActiveX DLL. The PROGID (typically of the form file.class) is in the Param1 field.

Optionally, the type can be suffixed with additional characters, indicating when the function is to be re-evaluated, what sort of numerical derivatives are to be calculated and what sort of calling mechanism is to be used. The possible types for re-evaluation are:

A

Function is re-evaluated when input variables change outside strict tolerance

R

Function is re-evaluated every time that input variables change

I

Function always generates function instances.

M

Function is multi-valued.

N

Function is non-differentiable

P

Function is multi-purpose, and can provide its dependency matrix.

V

Function can be interrogated to provide some constant derivatives

W

Function may have constant derivatives, which can be deduced by the calling program

If no re-evaluation suffix is provided, then re-evaluation will be determined from the setting of XSLP_FUNCEVAL, and function instances will be generated only if the function is "complicated". See the section on "More complicated user functions" for further details.
Normally, a user function is identified as multi-valued from the context in which it is used, and so the M suffix is not required. It must be used if the user function being defined is not used directly in any formulae.
Any formulae involving a non-differentiable function will always be evaluated using numerical derivatives.
The possible types for numerical derivatives are:

1

Forward derivatives

2

Tangential derivatives (calculated from forward and backward perturbation)

The suffix for numerical derivatives is not used if the function is defined as calculating its own derivatives. If no suffix is provided, then the method of calculating derivatives will be determined from the setting of XSLP_FUNCEVAL.
The possible types for the calling mechanism are:

S

STDCALL (the default under Windows)

C

CDECL (the alternative mechanism under Windows)

The setting of the calling mechanism has no effect on platforms other than Windows.

Param1

See Linkage

Param2

See Linkage

Param3

Name of return array for MOSEL linkage

Notes:

1. If an argument is declared as NULL, then Xpress NonLinear will provide a dummy argument of the correct type, but it will contain no useful information.
2. Arguments can be omitted entirely. This is achieved by leaving the space for the declaration of the argument empty (for example, by having two consecutive commas). In this case, Xpress NonLinear will omit the argument altogether. Trailing empty declarations can be omitted (that is, the closing bracket can immediately follow the last required argument).
3. COM, XLS and XLF require VARIANT types for their arguments. A declaration of any other type will be treated as VARIANT for these linkage types. VARIANT cannot be used for other linkage types.
4. Functions which do not perform their own differentiation must declare Deltas as NULL or omit it altogether.
5. The Extname, Param1, Param2 and Param3 fields can contain the names of character variables (defined on CV records). This form is required if the data to go in the field contains spaces. If the data does not contain spaces, the data can be provided directly in the field.

If a function has a constant derivative with respect to any of its variables, Xpress NonLinear can save some time by not repeatedly evaluating the function to obtain the same result. Provided that there are no circumstances in which the function might return values which imply derivatives identical to within about 1.0E-08 over a range of ±0.0001 or so for a derivative which is not constant, then the suffix W can be used so that Xpress NonLinear will assume that where a derivative appears to be constant within tolerances XSLP_CDTOL_A or XSLP_CDTOL_R it is actually constant and does not need further re-evaluation. If there are some derivatives which might falsely appear to be constant, then it is better to use the suffix V and write the function so that it can be interrogated for constant derivatives.

See Constant Derivatives for a detailed explanation of constant derivatives.

Examples:

UF MyLog ( DOUBLE ) DLL = MyFuncs

This declares a simple function called MyLog which only needs the input arguments. Because FunctionInfo is omitted, the number of arguments is probably fixed, or can be determined from the input argument list itself. The function is compiled as a user function in the library file MyFuncs (depending on the platform, the file may have an extension).

UF MyCalc = Simulator ( VARIANT , VARIANT ) XLS = MyTests.xls = XSLPInOut

This declares a function called MyCalc in Xpress NonLinear formulae. It is implemented as an Excel macro called Simulator in the workbook MyTests.xls. Xpress NonLinear will place the input data in sheet XSLPInOut in columns A and B; this is because only the first two arguments are declared to be in use. Xpress NonLinear will expect the results in column I of the same sheet. Note that although the arguments are respectively of type DOUBLE and INTEGER, they are both declared as VARIANT because the linkage mechanism uses only VARIANT types.

UF MyFunc = AdvancedFunction ( VARIANT , VARIANT , VARIANT , VARIANT ) XLF = MyTests.xls = XSLPFunc

This declares a function called MyFunc in Xpress NonLinear formulae. It is implemented as an Excel function on sheet XSLPFunc in the Excel workbook MyTests.xls. It will take values from and return values directly to Xpress NonLinear without using a sheet as an intermediary.

UF MyFunc = CFunc ( DOUBLE , INTEGER , CHAR , , DOUBLE , DOUBLE ) DLL = MyLib

This declares a function called MyFunc in Xpress NonLinear formulae. It is implemented as the function CFunc compiled in the user library MyLib. It takes a list of input names as the third argument, so it can identify arguments by name instead of by position. The fourth argument in the declaration is empty, meaning that the ReturnNames argument is not used. The fourth argument to the function is therefore the Deltas array of perturbations. Because Deltas is specified, the function must produce its own array of derivatives if required. It returns the array of results into the array defined by its fifth argument. The function itself will return a single status value.

Function declaration through XSLPloaduserfuncs and XSLPadduserfuncs

The method for declaring a user function is the same for XSLPloaduserfuncs and XSLPadduserfuncs. In each case the user function declaration is made using a variant of the parsed formula structure. Given the UF record described in the previous section:

UF Function = Extname ( InputValues , FunctionInfo ,
InputNames , ReturnNames , Deltas , ReturnArray )
Linkage = Param1 = Param2 = Param3

the equivalent formula sequence is:

Notes:

1. The value of the XSLP_UFARGTYPE token holds the information for the existence and type of each of the 6 possible arguments. Bits 0-2 represent the first argument (InputValues), bits 3-5 represent the second argument (FunctionInfo) and so on. Each 3-bit field takes one of the following values, describing the existence and type of the argument:

   0

   argument is omitted

   1

   NULL (argument is present but has no information content

   2

   INTEGER

   3

   DOUBLE

   4

   VARIANT

   6

   CHAR

2. The value of the XSLP_UFEXETYPE token holds the linkage type, the calling mechanism, and the options for evaluation and for calculating derivatives:

   Bits 0-2

   type of linkage:

   1

   DLL (User library or DLL)

   2

   XLS (Excel spreadsheet)

   3

   XLF (Excel macro)

   5

   MOSEL

   7

   COM

   Bits 3-4

   evaluation flags:

   0

   default

   1 (Bit 3)

   re-evaluation at each SLP iteration

   2 (Bit 4)

   re-evaluation when independent variables have changed outside tolerance

   Bits 6-7

   derivative flags:

   0

   default

   1 (Bit 6)

   tangential derivatives

   2 (Bit 7)

   forward derivatives

   Bit 8

   calling mechanism:

   0

   standard

   1

   CDECL (Windows only)

   Bit 13

   set if the function multi-purposed and can provide its dependency matrix

   Bit 24

   set if the function is multi-valued

   Bit 28

   set if the function is not differentiable

   Bits 11-12
   constant derivative flags:

   0

   default: no known constant derivatives

   1 (Bit 11)

   assume that derivatives which do not change outside the tolerance are constant

   2 (Bit 12)

   interrogate function for constant derivatives

The following constants are provided for setting these bits:

Setting bit 11	XSLP_DEDUCECONSTDERIVS
Setting bit 12	XSLP_SOMECONSTDERIVS

See Constant Derivatives for a detailed explanation of constant derivatives.

3. The string arguments are interpreted in the order in which they appear. Therefore, if any of the function parameters Param1 to Param3 is required, there must be entries for the internal function name and any preceding function parameters. If the fields are blank, use an XSLP_STRING token with a zero value.
4. The name of the function itself (Function in this case) is provided through the function XSLPaddnames.

Function declaration through XSLPchguserfunc

Functions can be declared individually using XSLPchguserfunc. The function information is passed in separate variables, rather than in an array of tokens. Given the UF record described earlier in Extended MPS format:

UF Function = Extname ( InputValues , FunctionInfo ,
InputNames , ReturnNames , Deltas , ReturnArray )
Linkage = Param1 = Param2 = Param3

the equivalent declaration is:

XSLPchguserfunc(Prob, 0, Extname, &ArgType, &ExeType,
       Param1, Param2, Param3)

where: Extname, Param1, Param2 and Param3 are character strings; ArgType and ExeType are integers.

An unused character string can be represented by an empty string or a NULL argument.

ArgType and ExeType are bitmaps with the same meaning as in the previous section.

Using zero as the second argument to XSLPchguserfunc forces the creation of a new user function definition. A positive integer will change the definition of an existing user function. In that case, a NULL argument means "no change".

Function declaration through SLPDATA in Mosel

In Mosel, a user function is declared to Xpress NonLinear using the SLPDATA function which mirrors the Extended MPS format declaration for file-based definitions.

SLPDATA(UF:string, Function:string, Extname:string, ArgList:string,
        ArgType:string [,Param1:string [,Param2:string [,Param3:string] ] ] )

Arguments:

UF

string containing UF, indicating the SLPDATA type.

Function

name of the function (as used within a Func() expression)

Extname

name of the function to be used when it is called. This may be different from Function (for example, it may be decorated or have a special prefix).

ArgList

list of the argument types to the function, as described in Extended MPS format. Effectively, it is the same as the list of argument types within the brackets in an Extended MPS format declaration: for example "DOUBLE,INTEGER". The argument types must match exactly the declaration of the function in its native language.

ArgType

the function type as described in Extended MPS format.

Param1-3

optional strings giving additional parameter information as required by the particular function type. Details are in Extended MPS format.