better documentation of the type of user information and additional M…

…atlab example (fixes #67)

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

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*
 

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.

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`:
 

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: