= 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 [source: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 [wiki:OptimizationTclApi Tcl bindings],
and those bindings are normally used to create an optimization program, such
as the example program in [source: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);
}}}