Changes between Version 1 and Version 2 of OptimizationApi


Ignore:
Timestamp:
Feb 22, 2008, 6:26:03 PM (10 years ago)
Author:
mmc
Comment:

updated with changes as of 2/22/2008

Legend:

Unmodified
Added
Removed
Modified
  • OptimizationApi

    v1 v2  
    44
    55----
    6 !RpOptimEnv* '''!RpOptimCreate'''()
     6!RpOptimEnv* '''!RpOptimCreate'''(''pluginDefn'')
    77
    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}}}.
     12
     13Once created, an optimization context can be updated by calling
     14functions like {{{RpOptimAddParamNumber}}} to define various
    1115input parameters.
    1216
    1317----
    14 void '''!RpOptimAddParamNumber'''(''envPtr'', ''name'', ''min'', ''max'')
     18!RpOptimParam* '''!RpOptimAddParamNumber'''(''envPtr'', ''name'')
    1519
    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 ||
    2527
    2628----
    27 void '''!RpOptimAddParamString'''(''envPtr'', ''name'', ''allowedValues'')
     29!RpOptimParam* '''!RpOptimAddParamString'''(''envPtr'', ''name'')
    2830
    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.
    3335
    3436||!RpOptimEnv* || envPtr || context for this optimization ||
    3537||char* || name || name of this parameter ||
    36 ||char** || allowedValues || null-terminated list of allowed values ||
    3738
    3839----
    39 !RpOptimStatus '''!RpOptimPerform'''(''envPtr'', ''evalFuncPtr'', ''maxRuns'')
     40!RpOptimParam* '''!RpOptimFindParam'''(''envPtr'',''name'')
    4041
    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.
    4245
    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 ||
    4648
    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:
     49----
     50void '''!RpOptimDeleteParam'''(''envPtr'',''name'')
    5151
    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.
    5354
    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;
    66 
    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.
    77 
    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.
    84 
     55||!RpOptimEnv* || envPtr || context for this optimization ||
     56||char* || name || name of parameter to be deleted ||
    8557
    8658----
     
    9668----
    9769
     70== Plug-in Definitions ==
     71
     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:
     76
     77{{{
     78static RpOptimPlugin rpOptimPlugins[] = {
     79    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
     80    {NULL, NULL, NULL},
     81};
     82}}}
     83
     84The first element is the name of the optimization package.
     85
     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.
     90
     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.
     96
     97The fourth argument is a clean-up routine called whenever the optimization
     98environment is deleted to clean up memory allocated during the initialization
     99routine.
     100
     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.
     105
     106----
     107
    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.
    100115{{{
     116static RpOptimPlugin rpOptimPlugins[] = {
     117    {"pgapack", PgapackInit, PgapackRun, PgapackCleanup, &PgapackOptions},
     118    {NULL, NULL, NULL},
     119};
     120
    101121RpOptimEnv *envPtr;
    102122RpOptimStatus status;
    103 char *funcValues[] = { "f1", "f2", "another", NULL };
     123RpOptimParamNumber *numParam;
    104124
    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;
    109129
    110 status = RpOptimPerform(envPtr, GetValue, 10);
     130RpOptimAddParamNumber(envPtr, "b");
     131RpOptimAddParamString(envPtr, "func");
     132
     133status = (*envPtr->pluginDefn->runProc)(envPtr,
     134            handleOptimization, "output.number(f)");
    111135
    112136if (status == RP_OPTIM_SUCCESS) {