Coding Optimizers for use in Rave

Introduction

This page contains some guidelines for how to code optimizers for use in Rave. Like other Rave plugins, optimizers require you to follow certain code structures in a few places, but for the most part you can code the actual optimization part of it however you want.

Required Files

Just like workspace objects, each optimizer has a keyword that serves as its unique identifier in Rave. Keywords appear in the name of the folder that contains the files for your optimizer, and in the filenames themselves. There is no min/max length requirement for the keyword, and it can contain letters and numbers. Keywords are case sensitive, so if you use capitalization, be sure to use it everywhere.

In this example, the optimizer described has the keyword "KEYWORD".

All files related to this optimizer must be placed in a folder named KEYWORD, which in turn must be placed in one of the three subfolders in the rave\optimizers directory. The subfolders are rave\optimizers\single, rave\optimizers\multi, and rave\optimizers\ranking. Put single objective optimizers in the single directory, multiobjective optimizers in the multi directory, and ranking functions in the ranking directory. Ranking functions are any functions that act only on the data set already loaded in Rave without requiring new function calls to generate new data. (They might, for example, select some rows in the data set based on some definition of optimality.)

The choice of which directory you place your optimizer in determines where it appears in the Algorithm menu on the Optimize tab. Also, if you place it in the single directory, Rave will only allow one objective to be selected from the Objective list on the Optimize tab. If you place it in the multi or ranking directories, the user may be allowed to select multiple objectives from the Objective list, as defined by settings.maxobjectives (described below).

Once you've made your KEYWORD directory, you must put three required files in it, plus any other helper files that your optimizer uses. The three required files are:

• optimizerinfo.txt - A two line plain text file. (Note that the file name does not contain KEYWORD). The first line of this file is the name of your optimizer as you want it to appear in Rave. The second line is a short description of the optimizer that will appear in the infobar when this optimizer is selected from the Algorithm menu.
• optimizersettingsKEYWORD.m - This is a script that defines any user-specified parameters that your optimizer needs, and a few required parameters that Rave needs.
• raveKEYWORD.m - This is the main function that actually runs your optimizer

The required files are describe in more detail below.

optimizerinfo.txt

This is a simple two+ line plain text file. It doesnt contain any code, just plain english text. The first line contains the name of the optimizer as it will appear in the Algorithm menu on the Optimize Tab. Because the menu is only 200 pixels wide, try to keep this to around 40 characters or less. The second line of the file contains a slightly longer description. This should contain critical identifying information about the optimizer, not a description of how it works. If the optimizer requires any MATLAB toolboxes (or other files that must be downloaded etc) you should note it here. You might also want to put your name here.

In the remainder of this file (lines 3+), you can put any instructions or additional information about the optimizer. Future versions of Rave will offer a method for the user to view this information from the Optimize Tab.

Required Function Parts

At the end of the file, your function must send certain data back to Rave. At a minimum, you must include two lines:

handles.optimizerresults(end+1).settings=settings;

This line saves the settings structure from this optimizer run. You can include this line at any point in your function, just make sure you put it after any changes to the settings structure that are made while the optimizer runs

handles.optimizerresults(end+1).results=X;

Here, X is whatever data you want your optimizer to return as its "answer." X must be an array with the same number of columns as settings.x where the value in each column is the value of the corresponding independent variable as indexed by settings.x. If the optimizer only returns a single optimal designs, X will have one row. If your optimizer returns multiple designs, X will have multiple rows. You should sort the rows of X in the order that you desired them to appear in Rave (if it matters).

You don't need to save the corresponding values of the objective functions; Rave will do that automatically.

You may also include any other relevant outputs from your optimizer as additional fields below handles.optimizerresults(end+1). Rave will not use these directly, but it will save them and export them so that you can refer to them in other programs. For example, suppose your optimizer also generates a matrix called A that you want to save. You can do this by adding the line:

handles.optimizerresults(end+1).myMatrix=A;