Rappture Optimization Library

Rappture comes with a built-in optimization package that knows how to drive the inputs for any Rappture-based tool toward the optimum of a certain fitness function. The library supporting optimization is still under development right now. The C language API for that library is as follows:

---

RpOptimEnv* RpOptimCreate(pluginDefn)

Used to create the context for an optimization. Creates an empty context and returns a pointer to it. The pluginDefn describes the underlying optimization method; right now, there is only one definition for pgapack, but others could be added later on at the top of rp_optimizer_tcl.c.

Once created, an optimization context can be updated by calling functions like RpOptimAddParamNumber to define various input parameters.

---

RpOptimParam* RpOptimAddParamNumber(envPtr, name)

Used to add a number parameter as an input to an optimization. Each number has a name and a double precision value that can be constrained between min/max values. Adds this number to the end of the parameter list in the given optimization context.

RpOptimEnv*	envPtr	context for this optimization
char*	name	name of this parameter

---

RpOptimParam* RpOptimAddParamString(envPtr, name)

Used to add a string parameter as an input to an optimization. Each string has a name and a list of allowed values. Adds this string parameter to the end of the parameter list in the given optimization context.

RpOptimEnv*	envPtr	context for this optimization
char*	name	name of this parameter

---

RpOptimParam* RpOptimFindParam(envPtr,name)

Used to look for an existing parameter defined with the specified name. Returns a pointer to the parameter definition, or NULL if the parameter is not defined.

RpOptimEnv*	envPtr	context for this optimization
char*	name	name of the desired parameter

---

void RpOptimDeleteParam(envPtr,name)

Deletes the parameter with the specified name. If there is no parameter with that name, this routine does nothing.

RpOptimEnv*	envPtr	context for this optimization
char*	name	name of parameter to be deleted

---

void RpOptimDelete(envPtr)

Used to delete the context for an optimization once it is finished or no longer needed. Frees up the memory needed to store the context and all input parameters. After this call, the context should not be used again.

RpOptimEnv*

envPtr

optimization context being deleted

---

Plug-in Definitions

Optimization libraries such as PGApack should be integrated into this package via the plug-in mechanism. Each plug-in is defined by a record hard-coded at the top of the trunk/optimizer/src/rp_optimizer_tcl.c file. Right now, it looks like this:

static RpOptimPlugin rpOptimPlugins[] = {
    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
    {NULL, NULL, NULL},
};

The first element is the name of the optimization package.

The second is the name of an initialization routine that is called whenever an optimizer object is created, to initialize configuration parameters associated with the package. These are things like the population size, maximum number of runs, etc., that can be configured to control the optimization.

The third argument is the routine that runs the core of the optimization. It takes as arguments the optimization environment, a function to handle evaluations (runs), and a string representing the fitness function being evaluated. It returns a status of RP_OPTIM_SUCCESS if optimization was achieved, and RP_OPTIM_FAILURE or RP_OPTIM_ABORTED if something goes wrong.

The fourth argument is a clean-up routine called whenever the optimization environment is deleted to clean up memory allocated during the initialization routine.

The fifth argument is a list of configuration options that represent the knobs on the optimization algorithm that can be tweaked. Each option in this list is associated with an element of the data structure allocated during the initialization routine.

---

Example

Here is a quick example of the optimization API in action. Note that this API has corresponding Tcl bindings, and those bindings are normally used to create an optimization program, such as the example program in trunk/optimizer/examples/simple.tcl. The following isn't really a very good or complete example, but just a quick example to show the API in action.

static RpOptimPlugin rpOptimPlugins[] = {
    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
    {NULL, NULL, NULL},
};

RpOptimEnv *envPtr;
RpOptimStatus status;
RpOptimParamNumber *numParam;

envPtr = RpOptimCreate(rpOptimPlugins[0]);
numParam = (RpOptimParamNumber*)RpOptimAddParamNumber(envPtr, "a");
numParam->min = 0.0;
numParam->max = 1.5;

RpOptimAddParamNumber(envPtr, "b");
RpOptimAddParamString(envPtr, "func");

status = (*envPtr->pluginDefn->runProc)(envPtr,
            handleOptimization, "output.number(f)");

if (status == RP_OPTIM_SUCCESS) {
    printf ("success!\n");
} else {
    printf ("failed :(\n");
}
RpOptimDelete(envPtr);