Gpufit API description¶
The Gpufit source code compiles to a dynamic-link library (DLL), providing a C interface. In the sections below, the C interface and its arguments are described in detail.
C Interface¶
The C interface is defined in the Gpufit header file: gpufit.h.
gpufit()¶
This is the main fit function. A single call to the gpufit()
function executes a block of N fits.
The inputs to gpufit()
are scalars and pointers to arrays, and the outputs are also array pointers.
The inputs to the gpufit()
function are:
the number of fits (N),
the number of data points per fit (each fit has equal size),
the fit data,
an array of weight values that are used to weight the individual data points in the fit (optional),
an ID number which specifies the fit model function,
an array of initial parameters for the model functions,
a tolerance value which determines when the fit has converged,
the maximum number of iterations per fit,
an array of flags which allow one or more fit parameters to be held constant,
an ID number which specifies the fit estimator (e.g. least squares, etc.),
the size of the user info data,
the user info data, which may have multiple uses, for example to pass additional parameters to the fit functions, or to include independent variables (e.g. X values) with the fit data.
The outputs of gpufit()
are:
the best fit model parameters for each fit,
an array of flags indicating, for example, whether each fit converged,
the final value of \(\chi^2\) for each fit,
the number of iterations needed for each fit to converge.
The gpufit()
function call is defined below.
int gpufit
(
size_t n_fits,
size_t n_points,
float * data,
float * weights,
int model_id,
float * initial_parameters,
float tolerance,
int max_n_iterations,
int * parameters_to_fit,
int estimator_id,
size_t user_info_size,
char * user_info,
float * output_parameters,
int * output_states,
float * output_chi_squares,
int * output_n_iterations
) ;
Description of input parameters¶
- n_fits
Number of fits to be performed
- type
size_t
- n_points
Number of data points per fit
Gpufit is designed such that each fit must have the same number of data points per fit.
- type
size_t
- data
Pointer to data values
A pointer to the data values. The data must be passed in as a 1D array of floating point values, with the data for each fit concatenated one after another. In the case of multi-dimensional data, the data must be flattened to a 1D array. The number of elements in the array is equal to the product n_fits * n_points.
- type
float *
- length
n_points * n_fits
- weights
Pointer to weights
The weights array includes unique weighting values for each fit. It is used only by the least squares estimator (LSE). The size of the weights array and its organization is identical to that for the data array. For statistical weighting, this parameter should be set equal to the inverse of the variance of the data (i.e. weights = 1.0 / variance ). The weights array is an optional input.
- type
float *
- length
n_points * n_fits
- special
Use a NULL pointer to indicate that no weights are provided. In this case all data values will be weighted equally.
- model_id
Model ID
Determines the model which is used for all fits in this call. See Fit Model functions for more details.
As defined in constants.h:
- 0
GAUSS_1D
- 1
GAUSS_2D
- 2
GAUSS_2D_ELLIPTIC
- 3
GAUSS_2D_ROTATED
- 4
CAUCHY_2D_ELLIPTIC
- 5
LINEAR_1D
- type
int
- initial_parameters
Pointer to initial parameter values
A 1D array containing the initial model parameter values for each fit. If the number of parameters of the fit model is defined by n_parameters, then the size of this array is n_fits * n_parameters.
The parameter values for each fit are concatenated one after another. If there are M parameters per fit, the parameters array is organized as follows: [(parameter 1), (parameter 2), …, (parameter M), (parameter 1), (parameter 2), …, (parameter M), …].
- type
float *
- length
n_fits * n_parameters
- tolerance
Fit tolerance threshold
The fit tolerance determines when the fit has converged. After each fit iteration, the change in the absolute value of \(\chi^2\) is calculated. The fit has converged when one of two conditions are met. First, if the change in the absolute value of \(\chi^2\) is less than the tolerance value, the fit has converged. Alternatively, if the change in \(\chi^2\) is less than the product of tolerance and the absolute value of \(\chi^2\) [tolerance * abs(\(\chi^2\))], then the fit has converged.
Setting a lower value for the tolerance results in more precise values for the fit parameters, but requires more fit iterations to reach convergence.
A typical value for the tolerance settings is between 1.0E-3 and 1.0E-6.
- type
float
- max_n_iterations
Maximum number of iterations
The maximum number of fit iterations permitted. If the fit has not converged after this number of iterations, the fit returns with a status value indicating that the maximum number of iterations was reached.
- type
int
- parameters_to_fit
Pointer to array indicating which model parameters should be held constant during the fit
This is an array of ones or zeros, with a length equal to the number of parameters of the fit model function. Each entry in the array is a flag which determines whether or not the corresponding model parameter will be held constant during the fit. To allow a parameter to vary during the fit, set the entry in parameters_to_fit equal to one. To hold the value constant, set the entry to zero.
An array of ones, e.g. [1,1,1,1,1,…] will allow all parameters to vary during the fit.
- type
int *
- length
n_parameters
- estimator_id
Estimator ID
Determines the fit estimator which is used. See Estimator functions for more details.
As defined in constants.h:
- 0
LSE
- 1
MLE
- type
int
- user_info_size
Size of user information data
Size of the user information data array, in bytes.
- type
size_t
- user_info
Pointer to user information data
This parameter is intended to provide flexibility to the Gpufit interface. The user information data is a generic block of memory which is passed in to the
gpufit()
function, and which is accessible in shared GPU memory by the fit model functions and the estimator functions. Possible uses for the user information data are to pass in values for independent variables (e.g. X values) or to supply additional data to the fit model function or estimator. The documentation of the fit model function or estimator must specify the composition of the user info data. For a coded example which makes use of the user information data, see Linear Regression Example. The user information data is an optional parameter - if no user information is required this parameter may be set to NULL.- type
char *
- length
user_info_size
- special
Use a NULL pointer to indicate that no user information is available. The interpretation of the user info depends completely on the used fit model function or estimator.
Description of output parameters¶
- output_parameters
Pointer to array of best-fit model parameters
For each fit, this array contains the best-fit model parameters. The array is organized identically to the input parameters array.
- type
float *
- length
n_fits * n_parameters
- output_states
Pointer to array of fit result state IDs
For each fit the result of the fit is indicated by a state ID. The state ID codes are defined below. A state ID of 0 indicates that the fit converged successfully.
As defined in constants.h:
- 0
The fit converged, tolerance is satisfied, the maximum number of iterations is not exceeded
- 1
Maximum number of iterations exceeded
- 2
During the Gauss-Jordan elimination the Hessian matrix is indicated as singular
- 3
Non-positive curve values have been detected while using MLE (MLE requires only positive curve values)
- 4
State not read from GPU Memory
- type
int *
- length
n_fits
- output_chi_squares
Pointer to array of \(\chi^2\) values
For each fit, this array contains the final \(\chi^2\) value, as returned by the estimator function (see Estimator functions).
- type
float *
- length
n_fits
- output_n_iterations
Pointer to array of iteration counts
For each fit, this array contains the number of fit iterations which were performed.
- type
int *
- length
n_fits
- return value
Status code
The return value of the function call indicates whether an error occurred. As defined in constants.h.
- 0
No error
- -1
Error
gpufit_constrained()¶
This is very similar to the gpufit()
function but with the additional possibility to add box constraints on the
allowed parameter ranges.
The gpufit_constrained()
function call is defined below.
int gpufit_constrained
(
size_t n_fits,
size_t n_points,
float * data,
float * weights,
int model_id,
float * initial_parameters,
float * constraints,
int * constraint_types,
float tolerance,
int max_n_iterations,
int * parameters_to_fit,
int estimator_id,
size_t user_info_size,
char * user_info,
float * output_parameters,
int * output_states,
float * output_chi_squares,
int * output_n_iterations
) ;
In order to not repeat the same information all input and output parameters in gpufit_constrained()
that also
exist in gpufit()
have exactly the same definition and interpretation. Below only the additional input parameter
regarding the constraints are explained.
Description of constraints input parameters¶
- constraints
Pointer to model parameter constraint intervals
A 1D array containing the model parameter constraint lower and upper bounds for all parameters (including fixed parameters) and for all fits. Order is lower, upper bound first, then parameters, then number of fits.
- type
float *
- length
n_fits * n_parameters * 2
- constraint_types
Pointer to constraint types for each parameter
A 1D array containing the constraint types for each parameter (including fixed parameters). The constraint type is defined by an int with 0 - no constraint, 1 - only constrain lower bound, 2 - only constrain upper bound, 3 - constrain both lower and upper bounds.
- type
int *
- length
n_parameters
gpufit_cuda_interface()¶
This function performs the fitting without transferring the input and output data between CPU and GPU memory. The
allocation of GPU memory for input and output data is skipped, as well. The structures of input and output arrays are
equal to the main interface function gpufit()
. There are no separate arrays for initial and best-fit parameter
values. The argument gpu_fit_parameters
points to initial parameter values at start of the routine and to
best-fit parameter values at the end.
int gpufit_cuda_interface
(
size_t n_fits,
size_t n_points,
float * gpu_data,
float * gpu_weights,
int model_id,
float tolerance,
int max_n_iterations,
int * parameters_to_fit,
int estimator_id,
size_t user_info_size,
char * gpu_user_info,
float * gpu_fit_parameters,
int * gpu_output_states,
float * gpu_output_chi_squares,
int * gpu_output_n_iterations
) ;
Description of input parameters¶
- n_fits
Number of fits to be performed
- type
size_t
- n_points
Number of data points per fit
- type
size_t
- gpu_data
Pointer to data values stored on GPU
- type
float *
- length
n_points * n_fits
- gpu_weights
Pointer to weights stored on GPU
- type
float *
- length
n_points * n_fits
- special
Use a NULL pointer to indicate that no weights are provided. In this case all data values will be weighted equally.
- model_id
Model ID
- type
int
- tolerance
Fit tolerance threshold
- type
float
- max_n_iterations
Maximum number of iterations
- type
int
- parameters_to_fit
Pointer to array indicating which model parameters should be held constant during the fit
- type
int *
- length
n_parameters
- estimator_id
Estimator ID
- type
int
- user_info_size
Size of user information data
- type
size_t
- gpu_user_info
Pointer to user information data stored on GPU
- type
char *
- length
user_info_size
- special
Use a NULL pointer to indicate that no user information is available.
Description of input/output parameters¶
- gpu_fit_parameters
Pointer to array of model parameters stored on GPU
input: initial parameter values
output: best-fit parameter values
- type
float *
- length
n_fits * n_parameters
Description of output parameters¶
- gpu_output_states
Pointer to array of fit result state IDs stored on GPU
- type
int *
- length
n_fits
- gpu_output_chi_squares
Pointer to array of \(\chi^2\) values stored on GPU
- type
float *
- length
n_fits
- gpu_output_n_iterations
Pointer to array of iteration counts stored on GPU
- type
int *
- length
n_fits
- return value
Status code
- 0
No error
- -1
Error
gpufit_constrained_cuda_interface()¶
This function is very similar to the gpufit_cuda_interface()
function but with the additional possibility to add box constraints on the
allowed parameter ranges.
int gpufit_constrained_cuda_interface
(
size_t n_fits,
size_t n_points,
float * gpu_data,
float * gpu_weights,
int model_id,
float tolerance,
int max_n_iterations,
int * parameters_to_fit,
float * gpu_constraints,
int * constraint_types,
int estimator_id,
size_t user_info_size,
char * gpu_user_info,
float * gpu_fit_parameters,
int * gpu_output_states,
float * gpu_output_chi_squares,
int * gpu_output_n_iterations
) ;
In order to not repeat the same information all input and output parameters in gpufit_constrained_cuda_interface()
that also
exist in gpufit_cuda_interface()
have exactly the same definition and interpretation. Below only the additional input parameter
regarding the constraints are explained.
Description of constraint input parameters¶
- gpu_constraints
Pointer to model parameter constraint intervals stored on the GPU
A 1D array containing the model parameter constraint lower and upper bounds for all parameters (including fixed parameters) and for all fits. Order is lower, upper bound first, then parameters, then number of fits.
- type
float *
- length
n_fits * n_parameters * 2
- constraint_types
Pointer to constraint types for each parameter
A 1D array containing the constraint types for each parameter (including fixed parameters). The constraint type is defined by an int with 0 - no constraint, 1 - only constrain lower bound, 2 - only constrain upper bound, 3 - constrain both lower and upper bounds.
- type
int *
- length
n_parameters
gpufit_portable_interface()¶
This function is a simple wrapper around the gpufit()
function, providing an alternative means of passing the function parameters.
int gpufit_portable_interface(int argc, void *argv[]);
Description of parameters¶
- argc
The length of the argv pointer array
- argv
Array of pointers to gpufit parameters, as defined above. For reference, the type of each element of the argv array is listed below.
- argv[0]
Number of fits
- type
size_t *
- argv[1]
Number of points per fit
- type
size_t *
- argv[2]
Fit data
- type
float *
- argv[3]
Fit weights
- type
float *
- argv[4]
Fit model ID
- type
int *
- argv[5]
Initial parameters
- type
float *
- argv[6]
Fit tolerance
- type
float *
- argv[7]
Maximum number of iterations
- type
int *
- argv[8]
Parameters to fit
- type
int *
- argv[9]
Fit estimator ID
- type
int *
- argv[10]
User info size
- type
size_t *
- argv[11]
User info data
- type
char *
- argv[12]
Output parameters
- type
float *
- argv[13]
Output states
- type
int *
- argv[14]
Output \(\chi^2\) values
- type
float *
- argv[15]
Output number of iterations
- type
int *
- return value
This function simply returns the
gpufit()
return status code.
gpufit_constrained_portable_interface()¶
This function is a simple wrapper around the gpufit_constrained()
function, providing an alternative means of passing the function parameters.
int gpufit_constrained_portable_interface(int argc, void *argv[]);
Description of parameters¶
- argc
The length of the argv pointer array
- argv
Array of pointers to gpufit_constrained parameters, as defined above.
- return value
This function simply returns the
gpufit()
return status code.
gpufit_get_last_error()¶
A function that returns a string representation of the last error.
char const * gpufit_get_last_error();
- return value
Error message corresponding to the most recent error, or an empty string if no error occurred.
- ‘CUDA driver version is insufficient for CUDA runtime version’
The graphics driver version installed on the computer is not supported by the CUDA Toolkit version which was used to build Gpufit.dll. Update the graphics driver or re-build Gpufit using a compatible CUDA Toolkit version.
- ‘too many resources requested for launch’
Exceeded number of available registers per thread block. Adding model functions to models.cuh can increase the number of registers per thread used by the kernel cuda_calc_curve_values(). If this error occurs, comment out unused models in function calculate_model() in file models.cuh.
gpufit_cuda_available()¶
A function that calls a simple CUDA function to check if CUDA is available.
int gpufit_cuda_available();
- return value
Returns 0 if CUDA is not available (no suitable device found, or driver version insufficient). Use the function gpufit_get_last_error() to check the error message. Returns 1 if CUDA is available.
gpufit_get_cuda_version()¶
A function that returns the CUDA runtime version in runtime_version and the installed CUDA driver version in driver_version.
int gpufit_get_cuda_version(int * runtime_version, int * driver_version);
- runtime_version
Pointer to the CUDA runtime version number. Format is Minor version times 10 plus Major version times 1000. (is 0 if the CUDA runtime version is incompatible with the installed CUDA driver version)
- driver_version
Pointer to the CUDA driver version number. Format is Minor version times 10 plus Major version times 1000. (is 0 if no CUDA enabled graphics card was detected)
- return value
Status code
The return value of the function call indicates whether an error occurred.
- 0
No error
- -1
Error. Use the function gpufit_get_last_error() to check the error message.