src/nws_portability/Include/forecast_api.h

   1 /* $Id$ */
   2
   3 #ifndef FORECAST_API_H
   4 #define FORECAST_API_H
   5
   6
   7 #include <sys/types.h>  /* size_t */
   8
   9
  10 /*
  11  * This file defines the API for the Network Weather Service forecast-
  12  * generation library.  The functions defined here allow programs to compute
  13  * forecasts from time-stamp/value pairs. The logic of operation is:
  14  *      - create a new ForecasterState
  15  *      - Update the state with values you observe
  16  *      - get a forecast back
  17  *
  18  * NOTE: In order to avoid name collisions, all names defined here begin with
  19  * FORECASTAPI_.  To avoid having to use this prefix, #define
  20  * FORECASTAPI_SHORTNAMES before #include'ing this file.
  21  */
  22
  23
  24 /*
  25  * A description of a measurement.  The time the measurement was taken
  26  * (represented as a number of seconds since midnight, 1/1/1970 GMT) and the
  27  * observed value.
  28  */
  29 typedef struct {
  30   double timeStamp;
  31   double measurement;
  32 } FORECASTAPI_Measurement;
  33
  34
  35 /*
  36  * A description of a forecast.  The forecast value itself, an estimate of the
  37  * precision of the forecast, and an index for the method used to generate it.
  38  */
  39 typedef struct {
  40   double forecast;
  41   double error;
  42   unsigned int methodUsed;
  43 } FORECASTAPI_Forecast;
  44
  45
  46 /**
  47  * A description of a collection of forecasts, each one based on minimizing a
  48  * different measurement of the error (MAE == MEAN_ABSOLUTE_ERROR, MSE ==
  49  * MEAN_SQUARE_ERROR).  The actual measurement taken at the same time is
  50  * included for convenience when available.
  51  */
  52 #define FORECASTAPI_FORECAST_TYPE_COUNT 2
  53 #define FORECASTAPI_MAE_FORECAST 0
  54 #define FORECASTAPI_MSE_FORECAST 1
  55 typedef struct {
  56         FORECASTAPI_Measurement measurement;
  57         FORECASTAPI_Forecast forecasts[FORECASTAPI_FORECAST_TYPE_COUNT];
  58 } FORECASTAPI_ForecastCollection;
  59
  60
  61 /**
  62  * A description of a forecasting state.  Client code should obtain these
  63  * structures via NewForecastState(), update them with new values via
  64  * UpdateForecastState(), then delete them via FreeForecastState().
  65  */
  66 struct FORECASTAPI_ForecastStateStruct;
  67 typedef struct FORECASTAPI_ForecastStateStruct FORECASTAPI_ForecastState;
  68
  69
  70 /**
  71  * Frees the memory occupied by the forecasting state pointed to by #state#
  72  * and sets #state# to NULL.
  73  */
  74 void
  75 FORECASTAPI_FreeForecastState(FORECASTAPI_ForecastState **state);
  76
  77
  78 /**
  79  * Returns the name of the #methodIndex#th forecasting method used by the
  80  * forecasting library, or NULL if #methodIndex# is out of range.
  81  */
  82 const char *
  83 FORECASTAPI_MethodName(unsigned int methodIndex);
  84
  85
  86 /**
  87  * Allocates and returns a new forecasting state, or NULL if memory is
  88  * exhausted.  The caller should eventually call FreeForecastingState() to
  89  * free the memory.
  90  */
  91 FORECASTAPI_ForecastState *
  92 FORECASTAPI_NewForecastState(void);
  93
  94
  95 /**
  96  * Incorporates the #howManyMeasurements#-long series #measurements# into the
  97  * forecasting state #state#.  If #forecasts# is non-NULL, it points to a
  98  * #howManyForecasts#-long array into which the function should store
  99  * forecasts generated during the course of the update  If #howManyForecasts#
 100  * is less than #howManyMeasurements#, the forecasts derived from the later
 101  * measurements (which appear at the beginning of #measurements#) are stored.
 102  */
 103 void
 104 FORECASTAPI_UpdateForecastState(FORECASTAPI_ForecastState *state,
 105                                 const FORECASTAPI_Measurement *measurements,
 106                                 size_t howManyMeasurements,
 107                                 FORECASTAPI_ForecastCollection *forecasts,
 108                                 size_t howManyForecasts);
 109 #define FORECASTAPI_UpdateForecast(state, measurements, howMany) \
 110         FORECASTAPI_UpdateForecastState(state, measurements, howMany, NULL, 0)
 111
 112 /**
 113  * Return a set of forecast base on the current state of the forecaster.
 114  * #forecast# need to have space for at least one ForecastCollection.
 115  *
 116  * Return 1 in case of error, 0 otherwise.
 117  *
 118  * Warning: The measurement insite the Collection is not meaningful.
 119  */
 120 int
 121 FORECASTAPI_ComputeForecast(    FORECASTAPI_ForecastState *state,
 122                                 FORECASTAPI_ForecastCollection *forecast);
 123
 124 #ifdef FORECASTAPI_SHORTNAMES
 125
 126 #define Measurement FORECASTAPI_Measurement
 127 #define Forecast FORECASTAPI_Forecast
 128 #define FORECAST_TYPE_COUNT FORECASTAPI_FORECAST_TYPE_COUNT
 129 #define MAE_FORECAST FORECASTAPI_MAE_FORECAST
 130 #define MSE_FORECAST FORECASTAPI_MSE_FORECAST
 131 #define ForecastCollection FORECASTAPI_ForecastCollection
 132 #define ForecastStateStruct FORECASTAPI_ForecastStateStruct
 133 #define ForecastState FORECASTAPI_ForecastState
 134 #define FreeForecastState FORECASTAPI_FreeForecastState
 135 #define MethodName FORECASTAPI_MethodName
 136 #define NewForecastState FORECASTAPI_NewForecastState
 137 #define UpdateForecastState FORECASTAPI_UpdateForecastState
 138 #define UpdateForecast FORECASTAPI_UpdateForecast
 139 #define ComputeForecast FORECASTAPI_ComputeForecast
 140
 141 #endif
 142
 143 #endif