Changes between Version 1 and Version 2 of OptimizationApi


Ignore:
Timestamp:
02/22/08 18:26:03 (7 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) {