source: trunk/optimizer/src/rp_optimizer.h @ 816

Last change on this file since 816 was 809, checked in by mmc, 17 years ago

Created the initial API for the optimizer. Type "make" in this directory
and then run the "rptest" program to see how it works. The guts of
rp_optimizer.c are missing, but the rest of it works.

File size: 3.5 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) 2004-2007  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#undef _ANSI_ARGS_
18#undef CONST
19
20#ifndef NO_CONST
21#  define CONST const
22#else
23#  define CONST
24#endif
25
26#ifndef NO_PROTOTYPES
27#  define _ANSI_ARGS_(x)  x
28#else
29#  define _ANSI_ARGS_(x)  ()
30#endif
31
32#ifdef EXTERN
33#  undef EXTERN
34#endif
35#ifdef __cplusplus
36#  define EXTERN extern "C"
37#else
38#  define EXTERN extern
39#endif
40
41/*
42 * This is the basic definition for each parameter within an optimization.
43 * Each parameter has a name, type, and value.  The value is important
44 * at the end of an optimization.  It is either the final value, or the
45 * value where we left off when the optimization was terminated.
46 */
47typedef enum {
48    RP_OPTIMPARAM_NUMBER, RP_OPTIMPARAM_STRING
49} RpOptimParamType;
50
51typedef struct RpOptimParam {
52    char *name;                     /* name of this parameter */
53    RpOptimParamType type;          /* paramter type -- number, string, etc */
54    union {
55        double num;                 /* slot for number value */
56        char *str;                  /* slot for string value */
57    } value;
58} RpOptimParam;
59
60/*
61 * NUMBER PARAMETERS have additional min/max values as constraints.
62 */
63typedef struct RpOptimParamNumber {
64    RpOptimParam base;              /* basic parameter info */
65    double min;                     /* optimization constraint: min value */
66    double max;                     /* optimization constraint: max value */
67} RpOptimParamNumber;
68
69/*
70 * STRING PARAMETERS have a set of allowed values.
71 */
72typedef struct RpOptimParamString {
73    RpOptimParam base;              /* basic parameter info */
74    char **values;                  /* array of allowed values */
75    int numValues;                  /* number of allowed values */
76} RpOptimParamString;
77
78/*
79 * Each optimization problem is represented by a context that includes
80 * the parameters that will be varied.
81 */
82typedef struct RpOptimEnv {
83    RpOptimParam **paramList;       /* list of input parameters to vary */
84    int numParams;                  /* current number of parameters */
85    int maxParams;                  /* storage for this many paramters */
86} RpOptimEnv;
87
88/*
89 * During each optimization, a function of the following type is
90 * called againa and again to evaluate input parameters and compute
91 * the fitness function.
92 */
93typedef enum {
94    RP_OPTIM_SUCCESS=0, RP_OPTIM_UNKNOWN, RP_OPTIM_FAILURE
95} RpOptimStatus;
96
97typedef RpOptimStatus (RpOptimEvaluator)_ANSI_ARGS_((RpOptimParam **values,
98    int numValues, double *fitnessPtr));
99
100
101/*
102 *  Here are the functions in the API:
103 */
104EXTERN RpOptimEnv* RpOptimCreate _ANSI_ARGS_(());
105
106EXTERN void RpOptimAddParamNumber _ANSI_ARGS_((RpOptimEnv *envPtr,
107    char *name, double min, double max));
108
109EXTERN void RpOptimAddParamString _ANSI_ARGS_((RpOptimEnv *envPtr,
110    char *name, char **allowedValues));
111
112EXTERN RpOptimStatus RpOptimPerform _ANSI_ARGS_((RpOptimEnv *envPtr,
113    RpOptimEvaluator *evalFuncPtr, int maxRuns));
114
115EXTERN void RpOptimDelete _ANSI_ARGS_((RpOptimEnv *envPtr));
Note: See TracBrowser for help on using the repository browser.