Changes between Version 1 and Version 2 of OptimizationApi

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