MAD Black Box Interfaces

This page is part of the MAD Manual. See MAD Manual.

Black Box Interfaces

In some cases it is necessary or desirable for a user to provide code directly to provide the derivatives of a function that forms part of the target function that is being differentiated with Mad. Examples of this are when analytic derivatives for a function are available, or perhaps when the function is coded in another language (e.g., Fortran or C) and interfaced to Matlab via a mex file or some other interface. We refer to such a function as a black box function since, as far as Mad is concerned it is a black box that should not be differentiated directly but for which derivative information will be supplied by the user. In order for Mad to differentiate through such black box functions three steps are necessary:

1. Use the function MADBlackBoxRegister to register the black box function with Mad supplying information on the number of input and output arguments, which of these are active (i.e., have derivatives), and to register a second function which calculates the necessary derivatives of output variables with respect to inputs.
2. Provide a function to calculate the required derivatives of the black box function.
3. Change the line of code in which the black box function is called so that the function call is made via the function MADBlackBoxEval.

The example of MADEXAERBlackBox will make this clearer.

Example MADEXAERBlackBox: Black Box Interface Example for AER Problem

Demonstration of using black box interface to calculate the gradient of the AER (analysis of an enzyme reaction) problem from MINPACK-2 collection.

The AER problem is to find x to minimise the sum of squares,

$f(x)=sum(F(x).^{2})$

where the residual vector F is supplied by MinpackAER_F. Here we look at how the gradient of f(x) may be calculated by direct use of fmad or by making use of the Jacobian of F(x) via a Black Box Interface.

See also: MADBlackBoxRegister, MinpackAER_Prob, TomlabAERBlackBox, ToolboxAERBlackBox

Contents

• Function definition

• Direct use of fmad

• Setting up the black box interface

• 1) Register the black box function

• 2) Provide a function to calculate required derivatives

• 3) Prepare a modified objective function

• Calculate derivatives using black box interface

• Conclusions

Function definition

The function we wish to differentiate is AERObj f which consists of the following code:

function f=AERObj_f(x,Prob)

R=MinpackAER_F(x,Prob);

f=R'*R;

the Jacobian DR/Dx of the function MinpackAER_F is available in the function MinpackAER_J. We may differentiate AERObj_f in one of two ways:

• Using fmad throughout.

• Using the Jacobian information from MinpackAER_J within a black box interface with fmad.

Direct use of fmad

By using the fmad class in the usual way we calculate the function's gradient.

Prob=MinpackAER_Prob(zeros(4,1)); % set up structure Prob
x0=Prob.x_0;
x=fmad(x0,eye(length(x0)));
f=AERObj_f(x,Prob);
gradient=getinternalderivs(f)

gradient =
    0.1336   -0.0007   -0.0090    0.0111

Setting up the black box interface

We'll go through the 3 stages step-by-step.

1) Register the black box function

First we use MADBlackBoxRegister to specify that MinpackAER_F is to be treated as a black box so that fmad needn't differentiate it and that the Jacobian of this function will be returned by MinpackAER_J. Note that we specify that MinpackAER_F has Nin=2 input variables, NOut=1 output variable and that only the first input (ActiveIn=1) and first output (ActiveOut=1} are active. If more than one input or output is active then ActiveIn and ActiveOut are vector lists of the position of the active variables in the argument list. As a result of this MinpackAER_J should calculate the Jacobian of the first output with respect to the first input.

MADBlackBoxRegister(@MinpackAER_F,'NIn',2,'NOut',1,'ActiveIn',1,'Activeout',1,...
    'JHandle',@MinpackAER_J)

2) Provide a function to calculate required derivatives

This is the aforementioned MinpackAER_J.

3) Prepare a modified objective function

We must now modify the code of the objective function in AERObj f so that the call to MinpackAER_F is wrapped within a call to MADBlackBoxEval - we have coding such a change in AERObjBlackBox_f replacing the line,

R=MinpackAER_F(x,Prob);

of AERObj_f with

R=MADBlackBoxEval(@MinpackAER_F,x,Prob);

in AERObjBlackBox_f. MADBlackBoxEval has a similar syntax to MATLAB's feval function, i.e. its arguments are the handle to the original function followed by the arguments passed to the original function. When evaluated with non- fmad arguments MADBlackBoxEval will simply use feval(@MinpackAER_F,x,Prob) so AERObjBlackBox_f may be used with arguements of class double.

Calculate derivatives using black box interface

It is now easy to calculate the required derivatives since MADBlackBoxEval takes care of all the interfacing of fmad variables with those supplied by MinpackAER_J.

x=fmad(x0,eye(length(x0)));
f=AERObjBlackBox_f(x,Prob);
gradient=getinternalderivs(f)

gradient =
    0.1336   -0.0007   -0.0090    0.0111

Conclusions

Using MAD's black box interface facilities it is straightforward to make use of analytic expressions, hand-coding, or external Fortran or C programs for calculating derivatives of functions.

For an example using such an interface in conjunction with the TOMLAB optimisers see MADEXTomlabAERBlackBox; Matlab Optimization Toolbox users should see MADEXToolboxAERBlackBox. Mad stores all data about black box functions in the global variable MADBlackBoxData. In addition to MADBlackBoxRegister and MADBlackBoxEval further black box interface functions to manipulate the data in MADBlackBoxData are:

• MADBlackBoxDisplay: which displays a list of all registered black box functions. For example, after running Example 7.1 MADBlackBoxDisplay produces the following output.

>> MADBlackBoxDisplay
Function : MinpackAER_F
  Type      : simple
  File      : C:\ShaunsDocuments\matlab\MAD\EXAMPLES\BlackBox\MinpackAER_F.m
  NIn       : 2
  NOut      : 1
  ActiveIn  : 1
  ActiveOut : 1
  J function  : MinpackAER_J
    Type      : simple
    File      : C:\ShaunsDocuments\matlab\MAD\EXAMPLES\BlackBox\MinpackAER_J.m

This shows that MinpackAER_F has been registered as a black box interface function, gives the file that defines the function, information on the input and output variables, and information on the Jacobian function.

• MADBlackBoxIndex: Given the function handle of a registered black box function, this function returns the index of that function (and optionally the function name) in Mad's internal list of black box functions. For example,

>> i=MADBlackBoxIndex(@MinpackAER_F)
i =
     1

>> [i,name]=MADBlackBoxIndex(@MinpackAER_F)
i =
     1
name =
MinpackAER_F

It is not anticipated that users will use this function.

• MADBlackBoxDelete: Given the function handle of a registered black box function, this function will delete that function from Mad's list of black box functions. For example,

>> MADBlackBoxDelete(@MinpackAER_F)
>> MADBlackBoxDisplay
MADBlackBoxDisplay: No functions registered

Note that MADBlackBoxDelete with no function handle argument deletes details of all registered black box functions.