From 01c78a274c02ad126171503b12e5dfd7eba58e0c Mon Sep 17 00:00:00 2001 From: jkfindeisen Date: Tue, 8 Jun 2021 17:13:59 +0200 Subject: [PATCH] better documentation of the type of user information and additional Matlab example (fixes #67) --- Gpufit/matlab/examples/linear_regression.m | 38 ++++++++++++++++++++++ docs/bindings.rst | 2 +- docs/examples.rst | 8 ++--- docs/fit_model_functions.rst | 2 +- docs/gpufit_api.rst | 8 +++-- 5 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 Gpufit/matlab/examples/linear_regression.m diff --git a/Gpufit/matlab/examples/linear_regression.m b/Gpufit/matlab/examples/linear_regression.m new file mode 100644 index 00000000..bc939cbb --- /dev/null +++ b/Gpufit/matlab/examples/linear_regression.m @@ -0,0 +1,38 @@ +function linear_regression() +% Example of the Matlab binding of the Gpufit library implementing +% Levenberg Marquardt curve fitting in CUDA +% https://github.com/gpufit/Gpufit +% +% 1D linear regression with custom x values given as user information +% http://gpufit.readthedocs.io/en/latest/bindings.html#matlab + +% x values for the 1D linear regression model must be single +x = single(0:10); +parameters = single([0;1]); +y = single(parameters(1)+parameters(2)*x'); + +% fit parameter +tolerance = 1e-9; +max_n_iterations = 1000; +estimator_id = EstimatorID.LSE; +model_id = ModelID.LINEAR_1D; +initial_parameters = single([0;1]); % should result in correct parameters with only 1 iteration + +% with user info +[parameters, states, chi_squares, n_iterations, time] = gpufit(y, [], ... + model_id, initial_parameters, tolerance, max_n_iterations, [], estimator_id, x); +fprintf('first fit with user info: fitted parameters = [%.2f, %.2f]\n', parameters); + +% without user info +[parameters, states, chi_squares, n_iterations, time] = gpufit(y, [], ... + model_id, initial_parameters, tolerance, max_n_iterations, [], estimator_id); +fprintf('first fit without user info: fitted parameters = [%.2f, %.2f]\n', parameters); + +% now more meaningful +x = single([1,3,4,5,5.5]); +y = single(parameters(1)+parameters(2)*x'); +[parameters, states, chi_squares, n_iterations, time] = gpufit(y, [], ... + model_id, initial_parameters, tolerance, max_n_iterations, [], estimator_id, x); +fprintf('second fit with user info: fitted parameters = [%.2f, %.2f]\n', parameters); + +end \ No newline at end of file diff --git a/docs/bindings.rst b/docs/bindings.rst index 7dcef766..bfadd770 100644 --- a/docs/bindings.rst +++ b/docs/bindings.rst @@ -349,7 +349,7 @@ The signature of the gpufit function is :special: If empty ([]), the default value is used. :user_info: user info - vector of arbitrary type. The length in bytes is deduced automatically. + vector of suitable type (correct type is not checked and depends on the used fit model function or estimator). The length of the user_info in bytes is deduced automatically. *Output parameters* diff --git a/docs/examples.rst b/docs/examples.rst index b9a30714..22bac254 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -342,9 +342,9 @@ This example features: - Noisy data and random initial guesses for the parameters - Unequally spaced *X* position values, passed to :code:`gpufit()` using the user_info parameter. - -The following code illustrates how the *X* positions of the data points are stored in the user_info variable, for this model function. -Note, however, that the way in which user_info is used by a model function may vary from function to function. +The following code illustrates how the *X* positions of the data points are stored in the user_info variable, for this +model function. The user_info points at a vector of float values. Note, however, that the way in which user_info +is used by a model function may vary from function to function. .. code-block:: cpp @@ -358,7 +358,7 @@ Note, however, that the way in which user_info is used by a model function may v // size of user_info in bytes size_t const user_info_size = n_points_per_fit * sizeof(float); -Here, by providing the data coordinates for only one fit in user_info, the model function will use the same coordinates for +By providing the data coordinates for only one fit in user_info, the model function will use the same coordinates for all fits in the dataset, as described in :ref:`fit-model-functions`. In the next section, the initial parameters for each fit are set to random values, uniformly distributed around the true parameter value. diff --git a/docs/fit_model_functions.rst b/docs/fit_model_functions.rst index 70677f74..41d0a736 100644 --- a/docs/fit_model_functions.rst +++ b/docs/fit_model_functions.rst @@ -41,7 +41,7 @@ A 1D linear function defined by two parameters (offset and slope). The model ID it is implemented in linear_1d.cuh_. **Optional**: The *X* coordinate of each data point may be specified via the user information data parameter of the -Gpufit interface. +Gpufit interface. The user information should then contain *X* coordinate values of type float in increasing order. :`Default X coordinates`: diff --git a/docs/gpufit_api.rst b/docs/gpufit_api.rst index 0f18dae9..7f24dec5 100644 --- a/docs/gpufit_api.rst +++ b/docs/gpufit_api.rst @@ -186,13 +186,15 @@ Description of input parameters 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 :code:`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. For - a coded example which makes use of the user information data, see :ref:`linear-regression-example`. The user + for independent variables (e.g. X values) or to supply additional data to the fit model function or estimator. + The documentation of the used 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 :ref:`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. + :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. .. _api-output-parameters: