Implementation:Rapidsai Cuml HoltWinters C API

Knowledge Sources	Rapidsai_Cuml
Domains	Machine_Learning, Time_Series
Last Updated	2026-02-08 12:00 GMT

Overview

Provides a C-compatible API for GPU-accelerated Holt-Winters exponential smoothing, supporting batched fitting and forecasting of seasonal time series with both additive and multiplicative seasonal components.

Description

The holtwinters_api.h header declares C-linkage functions for the Holt-Winters triple exponential smoothing algorithm. The API supports batch processing of multiple time series simultaneously on the GPU.

Type Definitions:

• cumlHoltWintersSeasonal_t: Enum defining seasonal types: ADDITIVE or MULTIPLICATIVE.

Buffer Size Calculation:

• cumlHoltWinters_buffer_size: Computes the required buffer sizes for level/trend arrays, seasonal arrays, full component arrays, error arrays, and offsets. This must be called before fitting to determine allocation sizes.

Fit Functions:

• cumlHoltWintersSp_fit / cumlHoltWintersDp_fit: Fit a Holt-Winters model to one or more time series, decomposing each into level, trend, and seasonal components. Outputs the sum of squared errors (SSE) for each time series.

Forecast Functions:

• cumlHoltWintersSp_forecast / cumlHoltWintersDp_forecast: Generate future point forecasts from a fitted Holt-Winters model using the stored level, trend, and seasonal components.

All functions return cumlError_t for error handling and support both single (Sp) and double (Dp) precision.

Usage

Use the Holt-Winters API for forecasting seasonal time series data on the GPU. The batched design is efficient when forecasting many independent time series simultaneously (e.g., demand forecasting across product lines). Call buffer_size first to determine memory requirements, then fit to decompose the series, and finally forecast to generate future predictions.

Code Reference

Source Location

• Repository: Rapidsai_Cuml
• File: cpp/include/cuml/tsa/holtwinters_api.h

Signature

typedef enum cumlHoltWintersSeasonal_t { ADDITIVE, MULTIPLICATIVE } cumlHoltWintersSeasonal_t;

cumlError_t cumlHoltWinters_buffer_size(int n, int batch_size, int frequency,
                                        int* start_leveltrend_len,
                                        int* start_season_len,
                                        int* components_len,
                                        int* error_len,
                                        int* leveltrend_coef_shift,
                                        int* season_coef_shift);

cumlError_t cumlHoltWintersSp_fit(cumlHandle_t handle,
                                  int n, int batch_size, int frequency,
                                  int start_periods,
                                  cumlHoltWintersSeasonal_t seasonal,
                                  float epsilon, float* data,
                                  float* level_ptr, float* trend_ptr,
                                  float* season_ptr, float* SSE_error_ptr);

cumlError_t cumlHoltWintersDp_fit(cumlHandle_t handle,
                                  int n, int batch_size, int frequency,
                                  int start_periods,
                                  cumlHoltWintersSeasonal_t seasonal,
                                  double epsilon, double* data,
                                  double* level_ptr, double* trend_ptr,
                                  double* season_ptr, double* SSE_error_ptr);

cumlError_t cumlHoltWintersSp_forecast(cumlHandle_t handle,
                                       int n, int batch_size, int frequency,
                                       int h, cumlHoltWintersSeasonal_t seasonal,
                                       float* level_ptr, float* trend_ptr,
                                       float* season_ptr, float* forecast_ptr);

cumlError_t cumlHoltWintersDp_forecast(cumlHandle_t handle,
                                       int n, int batch_size, int frequency,
                                       int h, cumlHoltWintersSeasonal_t seasonal,
                                       double* level_ptr, double* trend_ptr,
                                       double* season_ptr, double* forecast_ptr);

Import

#include <cuml/tsa/holtwinters_api.h>

I/O Contract

Inputs

cumlHoltWinters_buffer_size

Name	Type	Required	Description
n	int	Yes	Number of samples in each time series
batch_size	int	Yes	Number of time series in the batch
frequency	int	Yes	Number of periods in a season

cumlHoltWintersSp_fit / cumlHoltWintersDp_fit

Name	Type	Required	Description
handle	cumlHandle_t	Yes	cuML handle
n	int	Yes	Number of samples per time series
batch_size	int	Yes	Number of time series
frequency	int	Yes	Number of periods in a season
start_periods	int	Yes	Number of seasons used for seasonal seed values
seasonal	cumlHoltWintersSeasonal_t	Yes	ADDITIVE or MULTIPLICATIVE seasonal component
epsilon	T	Yes	Error tolerance for optimization
data	T*	Yes	Device pointer to time series data

cumlHoltWintersSp_forecast / cumlHoltWintersDp_forecast

Name	Type	Required	Description
handle	cumlHandle_t	Yes	cuML handle
n	int	Yes	Number of samples per time series
batch_size	int	Yes	Number of time series
frequency	int	Yes	Number of periods in a season
h	int	Yes	Number of future points to forecast
seasonal	cumlHoltWintersSeasonal_t	Yes	Seasonal component type
level_ptr	T*	Yes	Device pointer to level components from fit
trend_ptr	T*	Yes	Device pointer to trend components from fit
season_ptr	T*	Yes	Device pointer to seasonal components from fit

Outputs

Name	Type	Description
start_leveltrend_len	int*	Length of level/trend array buffers
start_season_len	int*	Length of seasonal array buffer
components_len	int*	Length of all three components combined
error_len	int*	Length of SSE error array
leveltrend_coef_shift	int*	Offset to level/trend arrays
season_coef_shift	int*	Offset to season array
level_ptr (fit)	T*	Fitted level components
trend_ptr (fit)	T*	Fitted trend components
season_ptr (fit)	T*	Fitted seasonal components
SSE_error_ptr (fit)	T*	Sum of squared errors per time series
forecast_ptr (forecast)	T*	Forecasted future points
return value	cumlError_t	CUML_SUCCESS or error flag

Usage Examples

#include <cuml/tsa/holtwinters_api.h>

cumlHandle_t handle;  // assume initialized

int n = 365;          // daily data for one year
int batch_size = 100; // 100 time series
int frequency = 7;    // weekly seasonality

// Step 1: Get buffer sizes
int leveltrend_len, season_len, comp_len, err_len;
int lt_shift, season_shift;
cumlHoltWinters_buffer_size(n, batch_size, frequency,
                            &leveltrend_len, &season_len, &comp_len,
                            &err_len, &lt_shift, &season_shift);

// Step 2: Allocate and fit
float* d_data;       // device pointer to time series data
float* d_level;      // allocate [comp_len]
float* d_trend;      // allocate [comp_len]
float* d_season;     // allocate [comp_len]
float* d_sse;        // allocate [err_len]

cumlHoltWintersSp_fit(handle, n, batch_size, frequency,
                      2,             // start_periods
                      ADDITIVE,      // seasonal type
                      1e-6f,         // epsilon
                      d_data, d_level, d_trend, d_season, d_sse);

// Step 3: Forecast 30 days ahead
int h = 30;
float* d_forecast;   // allocate [h * batch_size]
cumlHoltWintersSp_forecast(handle, n, batch_size, frequency,
                           h, ADDITIVE,
                           d_level, d_trend, d_season, d_forecast);

Related Pages

• Environment:Rapidsai_Cuml_CUDA_GPU