[Previous chapter] [Next chapter]

Functions and Callbacks


User functions and callbacks are the two mechanisms which allow the user program to control the way in which the optimization proceeds. They have different purposes and are not interchangeable.

A callback is called at a specific point in the SLP optimization process (for example, at the start of each SLP iteration). It has full access to all the problem data and can, in principle, change the values of any items — although not all such changes will necessarily be acted upon immediately or at all. Callbacks are implemented in Mosel as functions or procedures and are registered with the optimizer by using the setcallback or SLPsetcallback procedures.

A user function is essentially the same as any other mathematical function, used in a formula to calculate the current value of a coefficient. The function is called when a new value is needed; for efficiency, user functions are not usually called if the value is already known (for example, when the function arguments are the same as on the previous call). Therefore, there is no guarantee that a user function will be called at any specific point in the optimization procedure or at all. User functions are implemented in Mosel as functions with a pre-defined pattern of arguments; they are registered with the optimizer by using the SLPDATA("UF") procedure and included in constraints by using the Func function.

A user function appears in formulae with one or more arguments (and possibly with a return value reference if the function returns an array of values). These arguments can be any mixture of constants, mpvars, formulae or XVs. Regardless of how the arguments appear, they are converted into a single array of values for input to the implementation of the user function, so that the user function itself always deals with an array of values and returns a value or an array of values. The user function itself can be written in a number of different languages — for example: in Mosel as a real function; in Excel as a set of spreadsheet formulae or in a macro; in C or Fortran, compiled into a library. The SLPDATA("UF") procedure describes the linkage and location of the function so that it can be called as necessary.

In skeleton form, the components of a user function implementation are:

  1. The user function used in formulae.
    For example, if Product is a user function: 
    declarations
 X, Y: mpvar
 Z: array(1..n) of xvitem
 R: real
end-declarations
 Product(X,Y,R) >= 10
 Product(X^R,Y,X+2,X-2) <= 20
 Product(X,Z) >= 100
    The first usage shows the function called with 3 arguments: 2 mpvars and a constant;
    the second usage shows the function called with 4 arguments including linear and nonlinear formulae;
    the third usage shows the function called with an mpvar and an XV. An XV (extended variable array) is equivalent to an array of mpvars, formulae or constants.
  2. The implementation of the user function.
    In Mosel, a simple function takes an array of values and an integer (with the number of values) as its arguments and returns a single real value: 
    function Product(Values:array(vRange:range) of real, N:integer):real
 returned := 1
 forall (i in 1..N) returned := returned * Values(vRange(i))
end-function
    This function works independently of the number of arguments used in the original formula and returns the product of the first N values in the array.
  3. Declaration of the function linkage using SLPDATA.
    All the information necessary for calling the function is contained in this statement:
    the name of the function (both within the Mosel program and, if necessary, the actual name used in the implementation);
    the type of function (C, Fortran, Mosel, etc) which determines the linkage mechanism;
    where the function is (user library, Mosel program, spreadsheet, etc);
    what data the program expects (values, names) and what it returns (multiple values, derivatives). 
    SLPDATA("UF","Product", "", "DOUBLE,INTEGER",
        "Mosel", "Model", "BigArray")
    This declares the user function Product as a Mosel function in the model Model which takes input values and the number of values and returns a single result. BigArray is additional information specific to Mosel functions, and is the name of an array used to transfer data to and from the program.

[Next] [Index]
If you have any comments or suggestions about these pages, please send mail to docs@dashoptimization.com.