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

Last change on this file since 897 was 897, checked in by mmc, 15 years ago

Improved the Rappture optimization API to include Tcl bindings.
Added standard build/test stuff for Tcl libraries. Created a
plugin hook for optimization libraries like pgapack. The plugin
support still needs some work.

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