source: trunk/packages/optimizer/src/rp_optimizer.h @ 1154

Last change on this file since 1154 was 1154, checked in by liveletlive, 16 years ago

tweaked the configuration code for number parameters.
added code required to include units of a number parameter.
File size: 5.9 KB
Line 
1/*
2 * ----------------------------------------------------------------------
3 *  rp_optimizer
4 *
5 *  This is the C language API for the optimization package in
6 *  Rappture.  It lets you set up an optimization of some fitness
7 *  function with respect to a set of inputs.
8 *
9 * ======================================================================
10 *  AUTHOR:  Michael McLennan, Purdue University
11 *  Copyright (c) 2008  Purdue Research Foundation
12 *
13 *  See the file "license.terms" for information on usage and
14 *  redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
15 * ======================================================================
16 */
17#ifndef RP_OPTIMIZER
18#define RP_OPTIMIZER
19
20#include <tcl.h>
21#include <math.h>
22#include <float.h>
23#include <string.h>
24#include <malloc.h>
25#include "rp_tcloptions.h"
26
27#define PGAPACK_RUNTIME_TABLE_DEFAULT_SIZE 5000 /*Approx Number of Samples in a run*/
28#define SINGLE_SAMPLE_DATA_BUFFER_DEFAULT_SIZE 5000
29
30/*User defined Random Number Distributions*/
31#define RAND_NUMBER_DIST_GAUSSIAN 1
32#define RAND_NUMBER_DIST_UNIFORM 2
33
34/* Used to indicate unspecified mutation rate for a param, will result in global mutn rate being applied*/
35#define PARAM_NUM_UNSPEC_MUTN_RATE -1.0
36
37/*
38 * General-purpose allocation/cleanup routines:
39 * These are used, for example, for the plug-in architecture.
40 */
41typedef ClientData (RpOptimInit)_ANSI_ARGS_(());
42typedef void (RpOptimCleanup)_ANSI_ARGS_((ClientData cdata));
43
44/*
45 * During each optimization, a function of the following type is
46 * called again and again to evaluate input parameters and compute
47 * the fitness function.
48 */
49typedef enum {
50    RP_OPTIM_SUCCESS=0, RP_OPTIM_UNKNOWN, RP_OPTIM_FAILURE, RP_OPTIM_ABORTED
51} RpOptimStatus;
52
53struct RpOptimEnv;   /* defined below */
54struct RpOptimParam;
55
56typedef RpOptimStatus (RpOptimEvaluator) _ANSI_ARGS_((
57    struct RpOptimEnv *envPtr, struct RpOptimParam *values, int numValues,
58    double *fitnessPtr));
59
60typedef RpOptimStatus (RpOptimHandler) _ANSI_ARGS_((
61    struct RpOptimEnv *envPtr, RpOptimEvaluator *evalProc,
62    char *fitnessExpr));
63
64/*
65 * Each optimization package is plugged in to this infrastructure
66 * by defining the following data at the top of rp_optimizer_tcl.c
67 */
68typedef struct RpOptimPlugin {
69    char *name;                   /* name of this package for -using */
70    RpOptimInit *initProc;        /* initialization routine */
71    RpOptimHandler *runProc;      /* handles the core optimization */
72    RpOptimCleanup *cleanupProc;  /* cleanup routine */
73    RpTclOption *optionSpec;      /* specs for config options */
74} RpOptimPlugin;
75
76/*
77 * This is the basic definition for each parameter within an optimization.
78 * Each parameter has a name, type, and value.  The value is important
79 * at the end of an optimization.  It is either the final value, or the
80 * value where we left off when the optimization was terminated.
81 */
82typedef enum {
83    RP_OPTIMPARAM_NUMBER, RP_OPTIMPARAM_STRING
84} RpOptimParamType;
85
86typedef struct RpDiscreteString {
87    int num;                        /* integer representing this string */
88    char *str;                      /* actual string selected */
89} RpDiscreteString;
90
91typedef struct RpOptimParam {
92    char *name;                     /* name of this parameter */
93    RpOptimParamType type;          /* paramter type -- number, string, etc */
94    union {
95        double dval;                /* slot for number value */
96        int ival;                   /* slot for integer value */
97        RpDiscreteString sval;      /* slot for string value */
98    } value;
99} RpOptimParam;
100
101/*
102 * NUMBER PARAMETERS have additional constraints.
103 */
104typedef struct RpOptimParamNumber {
105    RpOptimParam base;              /* basic parameter info */
106    double min;                     /* optimization constraint: min value */
107    double max;                     /* optimization constraint: max value */
108    double mutnrate;                    /* independently sets mutation rate for each parameter*/
109    int randdist;                       /* gaussian or uniform distribution*/
110    int strictmin;                                      /* whether a strict min is to be applied for gauss. rand. numbers*/
111    int strictmax;                                      /* whether a strict max is to be applied for gauss. rand. numbers*/
112    double stddev;                                      /* std deviaton for gaussian profile*/
113    double mean;                                        /* mean for gaussian profile*/
114    char *units;
115} RpOptimParamNumber;
116
117/*
118 * STRING PARAMETERS have a set of allowed values.
119 */
120typedef struct RpOptimParamString {
121    RpOptimParam base;              /* basic parameter info */
122    char **values;                  /* array of allowed values */
123    int numValues;                  /* number of allowed values */
124} RpOptimParamString;
125
126/*
127 * Each optimization problem is represented by a context that includes
128 * the parameters that will be varied.
129 */
130typedef struct RpOptimEnv {
131    RpOptimPlugin *pluginDefn;      /* plug-in handling this optimization */
132    ClientData pluginData;          /* data created by plugin init routine */
133    RpOptimEvaluator *evalProc;     /* called during optimization to do run */
134    char *fitnessExpr;              /* fitness function in string form */
135    ClientData toolData;            /* data used during tool execution */
136    RpOptimParam **paramList;       /* list of input parameters to vary */
137    int numParams;                  /* current number of parameters */
138    int maxParams;                  /* storage for this many paramters */
139} RpOptimEnv;
140
141/*
142 *  Here are the functions in the API:
143 */
144EXTERN RpOptimEnv* RpOptimCreate _ANSI_ARGS_((RpOptimPlugin *pluginDefn));
145
146EXTERN RpOptimParam* RpOptimAddParamNumber _ANSI_ARGS_((RpOptimEnv *envPtr,
147    char *name));
148
149EXTERN RpOptimParam* RpOptimAddParamString _ANSI_ARGS_((RpOptimEnv *envPtr,
150    char *name));
151
152EXTERN RpOptimParam* RpOptimFindParam _ANSI_ARGS_((RpOptimEnv *envPtr,
153    char *name));
154
155EXTERN void RpOptimDeleteParam _ANSI_ARGS_((RpOptimEnv *envPtr, char *name));
156
157EXTERN void RpOptimDelete _ANSI_ARGS_((RpOptimEnv *envPtr));
158
159
160#endif
Note: See TracBrowser for help on using the repository browser.