Changes between Version 1 and Version 2 of OptimizationApi

Feb 22, 2008, 6:26:03 PM (9 years ago)

updated with changes as of 2/22/2008


  • OptimizationApi

    v1 v2  
    6 !RpOptimEnv* '''!RpOptimCreate'''()
     6!RpOptimEnv* '''!RpOptimCreate'''(''pluginDefn'')
    88Used to create the context for an optimization.  Creates an empty
    9 context and returns a pointer to it.  The context can be updated
    10 by calling functions like {{{RpOptimAddParamNumber}}} to define various
     9context and returns a pointer to it.  The ''pluginDefn'' describes the
     10underlying optimization method; right now, there is only one definition
     11for pgapack, but others could be added later on at the top of {{{rp_optimizer_tcl.c}}}.
     13Once created, an optimization context can be updated by calling
     14functions like {{{RpOptimAddParamNumber}}} to define various
    1115input parameters.
    14 void '''!RpOptimAddParamNumber'''(''envPtr'', ''name'', ''min'', ''max'')
     18!RpOptimParam* '''!RpOptimAddParamNumber'''(''envPtr'', ''name'')
    1620Used to add a number parameter as an input to an optimization.
    2125||!RpOptimEnv* || envPtr || context for this optimization ||
    2226||char* || name || name of this parameter ||
    23 ||double || min || minimum value for this parameter ||
    24 ||double || max || maximum value for this parameter ||
    27 void '''!RpOptimAddParamString'''(''envPtr'', ''name'', ''allowedValues'')
     29!RpOptimParam* '''!RpOptimAddParamString'''(''envPtr'', ''name'')
    2931Used to add a string parameter as an input to an optimization.
    30 Each string has a name and a list of allowed values terminated
    31 by a NULL.  Adds this string to the end of the parameter list
     32Each string has a name and a list of allowed values.  Adds
     33this string parameter to the end of the parameter list
    3234in the given optimization context.
    3436||!RpOptimEnv* || envPtr || context for this optimization ||
    3537||char* || name || name of this parameter ||
    36 ||char** || allowedValues || null-terminated list of allowed values ||
    39 !RpOptimStatus '''!RpOptimPerform'''(''envPtr'', ''evalFuncPtr'', ''maxRuns'')
     40!RpOptimParam* '''!RpOptimFindParam'''(''envPtr'',''name'')
    41 Used to perform an optimization in the given context.
     42Used to look for an existing parameter defined with the specified
     43name.  Returns a pointer to the parameter definition, or NULL if
     44the parameter is not defined.
    4346||!RpOptimEnv* || envPtr || context for this optimization ||
    44 ||!RpOptimEvaluator* || evalFuncPtr || function called to handle run ||
    45 ||int || maxRuns || limit on number of runs, or 0 for no limit ||
     47||char* || name || name of the desired parameter ||
    47 Each run is performed by calling an evaluation function represented by a
    48 function pointer.  This function takes an array of parameter
    49 pointers and a number of parameters, and returns a success/failure
    50 indication and a value for a fitness function:
     50void '''!RpOptimDeleteParam'''(''envPtr'',''name'')
    52   !RpOptimStatus ('''!RpOptimEvaluator''')(!RpOptimParam **''values'', int ''numValues'', double *''fitnessPtr'');
     52Deletes the parameter with the specified name.  If there is no
     53parameter with that name, this routine does nothing.
    54 The input values for the evaluation are contained within the ''values''
    55 array.  Each value has a name, a type, and a value contained within a union.
    56 Here is an example of an {{{RpOptimEvaluator}}} function that starts off by extracting
    57 a number called "a" from the list of input values:
    58 {{{
    59 RpOptimStatus
    60 GetValue(values, numValues, fitnessPtr)
    61     RpOptimParam **values;         /* array of input values */
    62     int numValues;                 /* number of values on the list */
    63     double *fitnessPtr;            /* returns: value of fitness */
    64 {
    65     double a = 0.0;
    67     for (n=0; n < numValues; n++) {
    68         if (strcmp(values[n]->name,"a") == 0 && values[n]->type == RP_OPTIMPARAM_NUMBER) {
    69             a = values[n]->value.num;
    70         }
    71         ...
    72 }}}
    73 Each call to the evaluator function should return RP_OPTIM_SUCCESS
    74 if it was able to compute a fitness function value based on the
    75 inputs, or RP_OPTIM_FAILURE if something went wrong for that set
    76 of inputs values.
    78 The call to {{{RpOptimPerform}}} also returns a success/failure
    79 status.  If an optimum value is found within the limit
    80 on the number of runs, then {{{RpOptimPerform}}} returns RP_OPTIM_SUCCESS.
    81 Values for the optimum input parameters are returned through the
    82 ''paramList'' within the context.  If the optimization fails, this
    83 function returns RP_OPTIM_FAILURE.
     55||!RpOptimEnv* || envPtr || context for this optimization ||
     56||char* || name || name of parameter to be deleted ||
     70== Plug-in Definitions ==
     72Optimization libraries such as PGApack should be integrated into this package
     73via the plug-in mechanism.  Each plug-in is defined by a record hard-coded
     74at the top of the [source:trunk/optimizer/src/rp_optimizer_tcl.c] file.
     75Right now, it looks like this:
     78static RpOptimPlugin rpOptimPlugins[] = {
     79    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
     80    {NULL, NULL, NULL},
     84The first element is the name of the optimization package.
     86The second is the name of an initialization routine that is called whenever
     87an optimizer object is created, to initialize configuration parameters
     88associated with the package.  These are things like the population size,
     89maximum number of runs, etc., that can be configured to control the optimization.
     91The third argument is the routine that runs the core of the optimization.  It
     92takes as arguments the optimization environment, a function to handle evaluations
     93(runs), and a string representing the fitness function being evaluated.  It
     94returns a status of RP_OPTIM_SUCCESS if optimization was achieved, and RP_OPTIM_FAILURE
     95or RP_OPTIM_ABORTED if something goes wrong.
     97The fourth argument is a clean-up routine called whenever the optimization
     98environment is deleted to clean up memory allocated during the initialization
     101The fifth argument is a list of configuration options that represent the knobs
     102on the optimization algorithm that can be tweaked.  Each option in this list
     103is associated with an element of the data structure allocated during the
     104initialization routine.
    98108== Example ==
    99 Here is a quick example of the optimization API in action.  (For complete details, see the test example [source:trunk/optimizer/src/test.c])
     109Here is a quick example of the optimization API in action.
     110Note that this API has corresponding [wiki:OptimizationTclApi Tcl bindings],
     111and those bindings are normally used to create an optimization program, such
     112as the example program in [source:trunk/optimizer/examples/simple.tcl].
     113The following isn't really a very good or complete example, but just
     114a quick example to show the API in action.
     116static RpOptimPlugin rpOptimPlugins[] = {
     117    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
     118    {NULL, NULL, NULL},
    101121RpOptimEnv *envPtr;
    102122RpOptimStatus status;
    103 char *funcValues[] = { "f1", "f2", "another", NULL };
     123RpOptimParamNumber *numParam;
    105 envPtr = RpOptimCreate();
    106 RpOptimAddParamNumber(envPtr, "a", 0.0, 1.0);
    107 RpOptimAddParamNumber(envPtr, "b", 1.0, 10.0);
    108 RpOptimAddParamString(envPtr, "func", funcValues);
     125envPtr = RpOptimCreate(rpOptimPlugins[0]);
     126numParam = (RpOptimParamNumber*)RpOptimAddParamNumber(envPtr, "a");
     127numParam->min = 0.0;
     128numParam->max = 1.5;
    110 status = RpOptimPerform(envPtr, GetValue, 10);
     130RpOptimAddParamNumber(envPtr, "b");
     131RpOptimAddParamString(envPtr, "func");
     133status = (*envPtr->pluginDefn->runProc)(envPtr,
     134            handleOptimization, "output.number(f)");
    112136if (status == RP_OPTIM_SUCCESS) {