Gpufit

https://gpufit.readthedocs.io/en/latest/
Admin
Gpufit is an open-source, GPU-accelerated CUDA library for high-performance non-linear curve fitting...
Tokens:18,445
Snippets:195
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pyGpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Use pip to install the pyGpufit wheel file from a local directory.

```bash
pip install --no-index --find-links=LocalPathToWheelFile pyGpufit
```

--------------------------------

### Execute Matlab examples

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Commands to add the build directory to the Matlab path and run a sample script.

```matlab
addpath('XX/Gpufit-build/matlab');
cd('XX/Gpufit/Gpufit/matlab/examples');
gauss2d();
```

--------------------------------

### Install Python package on Linux

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Install the generated Python wheel file from the distribution directory.

```bash
cd pyGpufit/dist
pip install pyGpufit-X.Y.Z-py2.py3-none-any.whl
```

--------------------------------

### Minimal Gpufit C++ Call Setup

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Initializes the necessary parameters, memory, and configuration for a Gpufit operation.

```cpp
// number of fits, number of points per fit
size_t const n_fits = 10;
size_t const n_points_per_fit = 10;

// model ID and number of model parameters
int const model_id = GAUSS_1D;
size_t const n_model_parameters = 5;

// initial parameters
std::vector< float > initial_parameters(n_fits * n_model_parameters);

// data
std::vector< float > data(n_points_per_fit * n_fits);

// tolerance
float const tolerance = 0.001f;

// maximum number of iterations
int const max_number_iterations = 10;

// estimator ID
int const estimator_id = LSE;

// parameters to fit (all of them)
std::vector< int > parameters_to_fit(n_model_parameters, 1);
```

```cpp
// output parameters
std::vector< float > output_parameters(n_fits * n_model_parameters);
std::vector< int > output_states(n_fits);
std::vector< float > output_chi_square(n_fits);
std::vector< int > output_number_iterations(n_fits);
```

```cpp
// call to gpufit (C interface)
int const status = gpufit
    (
        n_fits,
        n_points_per_fit,
        data.data(),
        0,
        model_id,
        initial_parameters.data(),
        tolerance,
        max_number_iterations,
        parameters_to_fit.data(),
        estimator_id,
        0,
        0,
        output_parameters.data(),
        output_states.data(),
        output_chi_square.data(),
        output_number_iterations.data()
    );

// check status
if (status != STATUS_OK)
{
    throw std::runtime_error(gpufit_get_last_error());
}
```

--------------------------------

### Define True Parameters

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Example of defining the initial parameters for a 2D Gaussian peak fit.

```java
// true parameters (order: amplitude, center-x, center-y, width, offset)
float[] trueParameters = new float[]{10, 5.5f, 5.5f, 3, 10};
```

--------------------------------

### Set Model and Estimator

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Example of setting the model and estimator types for a fit.

```java
Model model = Model.GAUSS_2D;
Estimator estimator = Estimator.MLE;
```

--------------------------------

### Check CUDA Information

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Example code to verify CUDA availability and retrieve version details.

```java
// print general CUDA information
System.out.println(String.format("CUDA available: %b", Gpufit.isCudaAvailable()));
CudaVersion cudaVersion = Gpufit.getCudaVersion();
System.out.println(String.format("CUDA versions runtime: %s, driver: %s", cudaVersion.runtime, cudaVersion.driver));
```

--------------------------------

### Run Gpufit performance comparison

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Execute the performance comparison binary after a successful build.

```bash
./Gpufit_Cpufit_performance_comparison
```

--------------------------------

### Configure Gpufit with CMake via Command Line

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Commands to navigate to the build directory and generate compiler files using CMake.

```bash
cd C:\Sources\Gpufit-build-64
cmake -G "Visual Studio 12 2013 Win64" C:\Sources\Gpufit

```

--------------------------------

### Assemble FitModel

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Configures the FitModel and populates data and initial parameters into the Java buffers.

```java
// assemble FitModel
FitModel fitModel = new FitModel(numberFits, numberPoints, false, model, tolerance, maxNumberIterations, null, estimator, 0);

// fill data and initial parameters in the fit model
fitModel.data.clear();
fitModel.data.put(data);
fitModel.initialParameters.clear();
fitModel.initialParameters.put(initialParameters);
```

--------------------------------

### Compile Gpufit on Linux

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Standard sequence of commands to clone, configure, and build the Gpufit project on a Linux system.

```bash
git clone https://github.com/gpufit/Gpufit.git Gpufit
mkdir Gpufit-build
cd Gpufit-build
cmake -DCMAKE_BUILD_TYPE=RELEASE ../Gpufit
make
```

--------------------------------

### Initialize fit parameters

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Sets initial parameters to random values distributed around the true parameter values.

```cpp
// true parameters
std::vector< float > true_parameters { 5, 2 }; // offset, slope

// initial parameters (randomized)
std::vector< float > initial_parameters(n_fits * n_model_parameters);
for (size_t i = 0; i != n_fits; i++)
{
    // random offset
    initial_parameters[i * n_model_parameters + 0] = true_parameters[0] * (0.8f + 0.4f * uniform_dist(rng));
    // random slope
    initial_parameters[i * n_model_parameters + 1] = true_parameters[0] * (0.8f + 0.4f * uniform_dist(rng));
}
```

--------------------------------

### Initialize Randomized Fit Parameters

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Generates initial guesses for fit parameters by applying a 20% uniform deviation to the true parameters.

```cpp
// initial parameters (randomized)
std::vector< float > initial_parameters(n_fits * n_model_parameters);
for (size_t i = 0; i < n_fits; i++)
{
    for (size_t j = 0; j < n_model_parameters; j++)
    {
        if (j == 1 || j == 2)
        {
            initial_parameters[i * n_model_parameters + j] = true_parameters[j] + true_parameters[3] * (-0.2f + 0.4f * uniform_dist(rng));
        }
        else
        {
            initial_parameters[i * n_model_parameters + j] = true_parameters[j] * (0.8f + 0.4f*uniform_dist(rng));
        }
    }
}
```

--------------------------------

### Execute gpufit()

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Calls the gpufit function with unweighted parameters to perform the linear regression.

```cpp
// call to gpufit (C interface)
int const status = gpufit
    (
        n_fits,
        n_points_per_fit,
        data.data(),
        0,
        model_id,
        initial_parameters.data(),
        tolerance,
        max_number_iterations,
        parameters_to_fit.data(),
        estimator_id,
        user_info_size,
        reinterpret_cast< char * >( user_info.data() ),
        output_parameters.data(),
        output_states.data(),
        output_chi_square.data(),
        output_number_iterations.data()
    );
```

--------------------------------

### Execute Gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Invokes the C interface of Gpufit using the configured FitModel.

```java
// fun Gpufit
FitResult fitResult = Gpufit.fit(fitModel);
```

--------------------------------

### Run Matlab package with updated C++ library

Source: https://gpufit.readthedocs.io/en/latest/installation.html

Set the LD_PRELOAD environment variable to ensure Matlab uses a compatible C++ standard library before launching.

```bash
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6
matlab
```

--------------------------------

### Python Interface Method Signatures

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Signatures for the primary Gpufit Python methods.

```python
def fit(data, weights, model_id:ModelID, initial_parameters, tolerance:float=None, max_number_iterations:int=None, parameters_to_fit=None, estimator_id:EstimatorID=None, user_info=None):
```

```python
def fit_constrained(data, weights, model_id:ModelID, initial_parameters, constraints=None, constraint_types=None, tolerance:float=None, max_number_iterations:int=None, parameters_to_fit=None, estimator_id:EstimatorID=None, user_info=None):
```

```python
def get_last_error():
```

```python
def cuda_available():
```

```python
def get_cuda_version():
```

--------------------------------

### Configure and execute constrained Gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Defines parameter constraints and constraint types before executing the fit_constrained function. Ensure constraints and constraint_types arrays are correctly sized for the number of parameters.

```python
# set constraints
constraints = np.zeros((number_fits, 2*number_parameters), dtype=np.float32)
constraints[:, 6] = 2.9
constraints[:, 7] = 3.1
constraint_types = np.array([gf.ConstraintType.LOWER, gf.ConstraintType.FREE, gf.ConstraintType.FREE, gf.ConstraintType.LOWER_UPPER, gf.ConstraintType.LOWER], dtype=np.int32)

# run constrained Gpufit
parameters, states, chi_squares, number_iterations, execution_time = gf.fit_constrained(data, None, model_id,
                                                                            initial_parameters, constraints, constraint_types,
                                                                            tolerance, max_number_iterations, None,
                                                                            estimator_id, None)
```

--------------------------------

### Execute Gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Calls the Gpufit C interface to perform the fitting process.

```matlab
%% run Gpufit
[parameters, states, chi_squares, n_iterations, time] = gpufit(data, [], model_id, initial_parameters, tolerance, max_n_iterations, [], estimator_id, []);
```

--------------------------------

### fit(data, weights, model_id, initial_parameters, ...)

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Performs curve fitting on the provided data using the specified model and initial parameters.

```APIDOC
## fit(data, weights, model_id, initial_parameters, tolerance=None, max_number_iterations=None, parameters_to_fit=None, estimator_id=None, user_info=None)

### Description
Performs curve fitting on the provided data using the specified model and initial parameters. This method is equivalent to calling the C interface function gpufit().

### Parameters
- **data** (np.float32 2D array) - Required - Data of shape (number_fits, number_points).
- **weights** (np.float32 2D array) - Required - Weights of shape (number_fits, number_points).
- **model_id** (ModelID) - Required - The ID of the model to use.
- **initial_parameters** (np.float32 2D array) - Required - Initial parameters of shape (number_fits, number_parameter).
- **tolerance** (float) - Optional - Fit tolerance.
- **max_number_iterations** (int) - Optional - Maximal number of iterations.
- **parameters_to_fit** (np.int32 1D array) - Optional - Parameters to fit.
- **estimator_id** (EstimatorID) - Optional - The ID of the estimator to use.
- **user_info** (1D array) - Optional - User info array.

### Returns
- **parameters** (np.float32 2D array) - Fitted parameters.
- **states** (np.int32 1D array) - Fit result states.
- **chi_squares** (np.float32 1D array) - Chi-square values.
- **n_iterations** (np.int32 1D array) - Number of iterations.
- **time** (float) - Execution time in seconds.
```

--------------------------------

### Define True Parameters for 2D Gaussian

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Sets the ground truth values for amplitude, center coordinates, width, and background offset.

```cpp
// true parameters
std::vector< float > true_parameters{ 10.f, 14.5f, 14.5f, 3.f, 10.f}; // amplitude, center x/y positions, width, offset
```

--------------------------------

### FitModel Constructor

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Constructor for initializing the model parameters for a batch of fits.

```java
public FitModel(int numberFits, int numberPoints, boolean withWeights, Model model, Float tolerance, Integer maxNumberIterations, Boolean[] parametersToFit, Estimator estimator, int userInfoSize)
```

--------------------------------

### Initialize model and estimator IDs

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Defines the estimator and model identifiers for the fitting process.

```cpp
// estimator ID
int const estimator_id = LSE;

// model ID
int const model_id = LINEAR_1D;
```

--------------------------------

### Import Gpufit and NumPy

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Essential imports for utilizing Gpufit functionality within a Python environment.

```python
import numpy as np
import pygpufit.gpufit as gf
```

--------------------------------

### Execute Gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Calls the C interface of Gpufit to perform the fitting process.

```python
# run Gpufit
parameters, states, chi_squares, number_iterations, execution_time = gf.fit(data, None, model_id, initial_parameters, tolerance, max_number_iterations, None, estimator_id, None)
```

--------------------------------

### Gpufit.fit Method Signature

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

The primary method for executing fits, mapping to the C gpufit() function.

```java
public static FitResult fit(FitModel fitModel, FitResult fitResult)
```

--------------------------------

### Clone Gpufit Repository

Source: https://gpufit.readthedocs.io/en/latest/installation.html

The URL for the Gpufit source code repository.

```text
https://github.com/gpufit/Gpufit.git

```

--------------------------------

### Configure user_info for X positions

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Stores custom X positions for data points in the user_info vector for use by the model function.

```cpp
// custom x positions for the data points of every fit, stored in user_info
std::vector< float > user_info(n_points_per_fit);
for (size_t i = 0; i < n_points_per_fit; i++)
{
    user_info[i] = static_cast<float>(pow(2, i));
}

// size of user_info in bytes
size_t const user_info_size = n_points_per_fit * sizeof(float);
```

--------------------------------

### Gpufit.fit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Executes the fitting process using the provided model and result container.

```APIDOC
## public static FitResult fit(FitModel fitModel, FitResult fitResult)

### Description
Performs the fitting operation based on the configuration in `fitModel`. Results are stored in `fitResult`.

### Parameters
- **fitModel** (FitModel) - Required - The model configuration containing parameters, data, and estimator settings.
- **fitResult** (FitResult) - Required - A container to store the output of the fit. Can be reused from previous calls.
```

--------------------------------

### Model Configuration Switch Case

Source: https://gpufit.readthedocs.io/en/latest/customization.html

Switch statement pattern for defining model parameters and dimensions within configure_model().

```cpp
switch (model_id)
{
case GAUSS_1D:              n_parameters = 4; n_dimensions = 1; break;
.
.
.
case ...:                   // model ID
    n_parameters = ...;     // number of model parameters
    n_dimensions = ...;     // number of model dimensions
    break;

default:                                                        break;
}
```

--------------------------------

### Portable Interface Wrapper

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Wrapper functions for passing parameters via an array of pointers, simplifying the interface for gpufit and gpufit_constrained.

```c
int gpufit_portable_interface(int argc, void *argv[]);
```

```c
int gpufit_constrained_portable_interface(int argc, void *argv[]);
```

--------------------------------

### Display Fit Statistics

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Analyzes and prints the results of the fitting process, including convergence rates and parameter statistics.

```python
# print fit results

# get fit states
converged = states == 0
number_converged = np.sum(converged)
print('ratio converged         {:6.2f} %'.format(number_converged / number_fits * 100))
print('ratio max it. exceeded  {:6.2f} %'.format(np.sum(states == 1) / number_fits * 100))
print('ratio singular hessian  {:6.2f} %'.format(np.sum(states == 2) / number_fits * 100))
print('ratio neg curvature MLE {:6.2f} %'.format(np.sum(states == 3) / number_fits * 100))
print('ratio gpu not read      {:6.2f} %'.format(np.sum(states == 4) / number_fits * 100))

# mean, std of fitted parameters
converged_parameters = parameters[converged, :]
converged_parameters_mean = np.mean(converged_parameters, axis=0)
converged_parameters_std = np.std(converged_parameters, axis=0)

for i in range(number_parameters):
    print('p{} true {:6.2f} mean {:6.2f} std {:6.2f}'.format(i, true_parameters[i], converged_parameters_mean[i], converged_parameters_std[i]))

# print summary
print('model ID: {}'.format(model_id))
print('number of fits: {}'.format(number_fits))
print('fit size: {} x {}'.format(size_x, size_x))
print('mean chi_square: {:.2f}'.format(np.mean(chi_squares[converged])))
print('iterations: {:.2f}'.format(np.mean(number_iterations[converged])))
print('time: {:.2f} s'.format(execution_time))
```

--------------------------------

### Check CUDA Availability

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Verifies the presence of CUDA and retrieves the driver and runtime versions.

```python
# cuda available checks
print('CUDA available: {}'.format(gf.cuda_available()))
print('CUDA versions runtime: {}, driver: {}'.format(*gf.get_cuda_version()))
```

--------------------------------

### Execute Gpufit and Handle Errors

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Calls the gpufit function via the C interface and checks the return status for errors.

```cpp
// call to gpufit (C interface)
int const status = gpufit
    (
        n_fits,
        n_points_per_fit,
        data.data(),
        0,
        model_id,
        initial_parameters.data(),
        tolerance,
        max_number_iterations,
        parameters_to_fit.data(),
        estimator_id,
        0,
        0,
        output_parameters.data(),
        output_states.data(),
        output_chi_square.data(),
        output_number_iterations.data()
    );

// check status
if (status != STATUS_OK)
{
    throw std::runtime_error(gpufit_get_last_error());
}
```

--------------------------------

### Include New Estimator Header

Source: https://gpufit.readthedocs.io/en/latest/customization.html

Include the newly created .cuh file within estimators.cuh.

```cpp
#include "....cuh"              // filename
```

--------------------------------

### Configure Gpufit Model and Estimator IDs

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Sets the estimator and model identifiers for a 2D Gaussian fit.

```cpp
// estimator ID
int const estimator_id = MLE;

// model ID
int const model_id = GAUSS_2D;
```

--------------------------------

### int gpufit(...)

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

The main fit function that executes a block of N fits in parallel on the GPU.

```APIDOC
## 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
Executes a batch of N fits using the specified model and estimator. The function processes data in parallel on the GPU and returns the optimized parameters and convergence statistics.

### Parameters
- **n_fits** (size_t) - Number of fits to be performed.
- **n_points** (size_t) - Number of data points per fit.
- **data** (float *) - Pointer to a 1D array of floating point values containing the data for all fits.
- **weights** (float *) - Optional pointer to weights for the least squares estimator. Use NULL for equal weighting.
- **model_id** (int) - Identifier for the fit model function (e.g., 0: GAUSS_1D, 1: GAUSS_2D).
- **initial_parameters** (float *) - 1D array containing initial model parameter values for each fit.
- **tolerance** (float) - Convergence tolerance value.
- **max_n_iterations** (int) - Maximum number of iterations allowed per fit.
- **parameters_to_fit** (int *) - Array of flags to hold specific parameters constant.
- **estimator_id** (int) - Identifier for the fit estimator.
- **user_info_size** (size_t) - Size of the user info data.
- **user_info** (char *) - Pointer to user info data for additional parameters or independent variables.

### Returns
- **output_parameters** (float *) - Best fit model parameters for each fit.
- **output_states** (int *) - Array indicating convergence status for each fit.
- **output_chi_squares** (float *) - Final chi-square value for each fit.
- **output_n_iterations** (int *) - Number of iterations required for convergence per fit.
```

--------------------------------

### cuda_available()

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Checks if CUDA is available.

```APIDOC
## cuda_available()

### Description
Returns True if CUDA is available and False otherwise.
```

--------------------------------

### Display Fit Statistics

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Analyzes and prints the results of the fitting process, including convergence rates and parameter statistics.

```matlab
%% displaying results

% get fit states
converged = states == 0;
number_converged = sum(converged);
fprintf(' ratio converged         %6.2f %%\n', number_converged / number_fits * 100);
fprintf(' ratio max it. exceeded  %6.2f %%\n', sum(states == 1) / number_fits * 100);
fprintf(' ratio singular hessian  %6.2f %%\n', sum(states == 2) / number_fits * 100);
fprintf(' ratio neg curvature MLE %6.2f %%\n', sum(states == 3) / number_fits * 100);
fprintf(' ratio gpu not read      %6.2f %%\n', sum(states == 4) / number_fits * 100);

% mean and std of fitted parameters
converged_parameters = parameters(:, converged);
converged_parameters_mean = mean(converged_parameters, 2);
converged_parameters_std  = std(converged_parameters, [], 2);
for i = 1 : number_parameters
    fprintf(' p%d true %6.2f mean %6.2f std %6.2f\n', i, true_parameters(i), converged_parameters_mean(i), converged_parameters_std(i));
end

% print summary
fprintf('model ID: %d\n', model_id);
fprintf('number of fits: %d\n', number_fits);
fprintf('fit size: %d x %d\n', size_x, size_x);
fprintf('mean chi-square: %6.2f\n', mean(chi_squares(converged)));
fprintf('iterations: %6.2f\n', mean(n_iterations(converged)));
fprintf('time: %6.2f s\n', time);
```

--------------------------------

### Calculate and Display 2D Gaussian Peak Fit Statistics

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Iterates through fit states to identify converged results and computes the mean and standard deviation for parameters. Requires access to fitResult and model objects.

```java
// count FitState outcomes and get a list of those who converged
boolean[] converged = new boolean[numberFits];
int numberConverged = 0, numberMaxIterationExceeded = 0, numberSingularHessian = 0, numberNegativeCurvatureMLE = 0;
for (int i = 0; i < numberFits; i++) {
    FitState fitState = FitState.fromID(fitResult.states.get(i));
    converged[i] = fitState.equals(FitState.CONVERGED);
    switch (fitState) {
        case CONVERGED:
            numberConverged++;
            break;
        case MAX_ITERATIONS:
            numberMaxIterationExceeded++;
            break;
        case SINGULAR_HESSIAN:
            numberSingularHessian++;
            break;
        case NEG_CURVATURE_MLE:
            numberNegativeCurvatureMLE++;
    }
}

// get mean and std of converged parameters
float [] convergedParameterMean = new float[]{0, 0, 0, 0, 0};
float [] convergedParameterStd = new float[]{0, 0, 0, 0, 0};
for (int i = 0; i < numberFits; i++) {
    for (int j = 0; j < model.numberParameters; j++) {
        if (converged[i]) {
            convergedParameterMean[j] += fitResult.parameters.get(i * model.numberParameters + j);
        }
    }
}
for (int i = 0; i < model.numberParameters; i++) {
    convergedParameterMean[i] /= numberConverged;
}
for (int i = 0; i < numberFits; i++) {
    for (int j = 0; j < model.numberParameters; j++) {
        if (converged[i]) {
            float dev = fitResult.parameters.get(i * model.numberParameters + j) - convergedParameterMean[j];
            convergedParameterStd[j] += dev * dev;
        }
    }
}
for (int i = 0; i < model.numberParameters; i++) {
    convergedParameterStd[i] = (float)Math.sqrt(convergedParameterStd[i] / numberConverged);
}

// print fit results
System.out.println("*Gpufit*");
System.out.println(String.format("Model: %s", model.name()));
System.out.println(String.format("Number of fits: %d", numberFits));
System.out.println(String.format("Fit size: %d x %d", sizeX, sizeX));
System.out.println(String.format("Mean Chi²: %.2f", meanFloatBuffer(fitResult.chiSquares, converged)));
System.out.println(String.format("Mean  number iterations: %.2f", meanIntBuffer(fitResult.numberIterations, converged)));
System.out.println(String.format("Time: %.2fs", fitResult.fitDuration));
System.out.println(String.format("Ratio converged: %.2f %%", (float) numberConverged / numberFits * 100));
System.out.println(String.format("Ratio max it. exceeded: %.2f %%", (float) numberMaxIterationExceeded / numberFits * 100));
System.out.println(String.format("Ratio singular Hessian: %.2f %%", (float) numberSingularHessian / numberFits * 100));
System.out.println(String.format("Ratio neg. curvature MLE: %.2f %%", (float) numberNegativeCurvatureMLE / numberFits * 100));

System.out.println("\nParameters of 2D Gaussian peak");
for (int i = 0; i < model.numberParameters; i++) {
    System.out.println(String.format("parameter %d, true: %.2f, mean %.2f, std: %.2f", i, trueParameters[i], convergedParameterMean[i], convergedParameterStd[i]));
}
```

--------------------------------

### CUDA Device Function Template for Fit Models

Source: https://gpufit.readthedocs.io/en/latest/customization.html

Template for implementing custom model functions and their partial derivatives in a .cuh file.

```cuda
__device__ void ... (               // ... = function name
    float const * parameters,
    int const n_fits,
    int const n_points,
    float * value,
    float * derivative,
    int const point_index,
    int const fit_index,
    int const chunk_index,
    char * user_info,
    std::size_t const user_info_size)
{
    ///////////////////////////// value //////////////////////////////

    value[point_index] = ... ;                      // formula calculating fit model values

    /////////////////////////// derivative ///////////////////////////
    float * current_derivative = derivative + point_index;

    current_derivative[0 * n_points] = ... ;  // formula calculating derivative values with respect to parameters[0]
    current_derivative[1 * n_points] = ... ;  // formula calculating derivative values with respect to parameters[1]
    .
    .
    .
}
```

--------------------------------

### Retrieve CUDA version information

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Call this function to obtain the CUDA runtime and driver versions. The return value indicates success (0) or failure (-1).

```c
int gpufit_get_cuda_version(int * runtime_version, int * driver_version);
```

--------------------------------

### Perform Constrained Gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Configures and executes a constrained fit by defining parameter bounds and constraint types.

```matlab
%% set constraints
constraints = zeros([2*number_parameters, number_fits], 'single');
constraints(7, :) = 2.9;
constraints(8, :) = 3.1;
constraint_types = int32([ConstraintType.LOWER, ConstraintType.FREE, ConstraintType.FREE, ConstraintType.LOWER_UPPER, ConstraintType.LOWER]);

%% run constrained Gpufit
[parameters, states, chi_squares, n_iterations, time] = gpufit_constrained(data, [], ...
    model_id, initial_parameters, constraints, constraint_types, tolerance, max_n_iterations, [], estimator_id, []);
```

--------------------------------

### Gpufit C Interface Definition

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

The main function signature for executing a batch of fits in Gpufit.

```c
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
) ;
```

--------------------------------

### Generate Noisy Dataset

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Creates a dataset of Gaussian peaks with added Poisson-distributed noise.

```cpp
// generate data with noise
std::vector< float > temp_gauss(n_points_per_fit);
// compute the model function
generate_gauss_2d(x, y, true_parameters.begin(), temp_gauss);

std::vector< float > data(n_fits * n_points_per_fit);
for (size_t i = 0; i < n_fits; i++)
{
    // generate Poisson random numbers
    for (size_t j = 0; j < n_points_per_fit; j++)
    {
        std::poisson_distribution< int > poisson_dist(temp_gauss[j]);
        data[i * n_points_per_fit + j] = static_cast<float>(poisson_dist(rng));
    }
}
```

--------------------------------

### Error Handling and Device Check

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Utility functions for retrieving the last error message and verifying CUDA availability.

```c
char const * gpufit_get_last_error();
```

```c
int gpufit_cuda_available();
```

--------------------------------

### Define True Parameters for 2D Gaussian

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Sets the ground truth parameters for the 2D Gaussian model.

```matlab
% true parameters
true_parameters = single([10, 5.5, 5.5, 3, 10]);
```

--------------------------------

### gpufit

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Performs a fit operation using the Gpufit library. This function takes input data, model identifiers, and initial parameters to compute fitted parameters, states, chi-squares, iteration counts, and execution time.

```APIDOC
## function [parameters, states, chi_squares, n_iterations, time] = gpufit(data, weights, model_id, initial_parameters, tolerance, max_n_iterations, parameters_to_fit, estimator_id, user_info)

### Description
Performs a fit operation on the provided data using the specified model and parameters.

### Parameters
- **data** (single) - 2D matrix of size [number_points, number_fits]
- **weights** (single) - 2D matrix of size [number_points, number_fits]
- **model_id** (ModelID) - ID of the model to use
- **initial_parameters** (single) - 2D matrix of size [number_parameter, number_fits]
- **tolerance** (single) - Fit tolerance
- **max_n_iterations** (int32) - Maximum number of iterations
- **parameters_to_fit** (int32) - Vector of length number_parameter
- **estimator_id** (EstimatorID) - ID of the estimator to use
- **user_info** (vector) - User info vector

### Returns
- **parameters** (single) - Fitted parameters [number_parameter, number_fits]
- **states** (int32) - Fit result states
- **chi_squares** (single) - Chi-square values
- **n_iterations** (int32) - Number of iterations
- **time** (double) - Execution time in seconds
```

--------------------------------

### getCudaVersion

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Retrieves the current CUDA runtime and driver versions.

```APIDOC
## public static CudaVersion getCudaVersion()

### Description
Returns a CudaVersion instance containing the runtime and driver version strings.
```

--------------------------------

### Define True Parameters

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Sets the ground truth parameters for the 2D Gaussian model as a float32 NumPy array.

```python
# true parameters
true_parameters = np.array((10, 5.5, 5.5, 3, 10), dtype=np.float32)
```

--------------------------------

### Generate data and add Poisson noise

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Repeats the model function and applies Poisson noise to the generated dataset.

```java
// generate data
float[] gauss2D = generateGauss2D(trueParameters, xi, yi);
float[] data = new float[numberFits * numberPoints];
for (int i = 0; i < numberFits; i++) {
    System.arraycopy(gauss2D, 0, data, i * numberPoints, numberPoints);
}

// add Poisson noise
for (int i = 0; i < numberFits * numberPoints; i++) {
    data[i] = nextPoisson(data[i], rand);
}
```

--------------------------------

### Gpufit Constrained Matlab Function Signature

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Interface for performing fits with parameter constraints in Matlab.

```matlab
function [parameters, states, chi_squares, n_iterations, time] = gpufit_constrained(data, weights, model_id, initial_parameters, constraints, constraint_types, tolerance, max_n_iterations, parameters_to_fit, estimator_id, user_info)
```

--------------------------------

### gpufit_portable_interface

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

A wrapper function for gpufit() that accepts parameters via an array of pointers.

```APIDOC
## gpufit_portable_interface

### Description
Provides an alternative interface to the standard gpufit() function by passing parameters through an array of pointers.

### Signature
int gpufit_portable_interface(int argc, void *argv[]);

### Parameters
- **argc** (int) - The length of the argv pointer array.
- **argv** (void *[]) - Array of pointers to gpufit parameters (Number of fits, points, data, weights, model ID, initial parameters, tolerance, iterations, parameters to fit, estimator ID, user info, output parameters, states, chi-squares, and iteration counts).
```

--------------------------------

### Configure Estimator and Model IDs

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Sets the estimator and model identifiers for the Gpufit execution.

```matlab
% estimator id
estimator_id = EstimatorID.MLE;

% model ID
model_id = ModelID.GAUSS_2D;
```

--------------------------------

### Generate 2D Grid Positions

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Creates coordinate grids for x and y positions using meshgrid.

```python
# generate x and y values
g = np.arange(size_x)
yi, xi = np.meshgrid(g, g, indexing='ij')
xi = xi.astype(np.float32)
yi = yi.astype(np.float32)
```

--------------------------------

### Constrained CUDA Interface

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Interface for performing fits with box constraints on parameter ranges using GPU-resident data.

```c
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
) ;
```

--------------------------------

### getCudaVersion Method Signature

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Retrieves the current CUDA runtime and driver versions.

```java
public static CudaVersion getCudaVersion()
```

--------------------------------

### Generate and Noise Data

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Creates synthetic data by repeating the model function and applying Poisson noise.

```python
# generate data
data = generate_gauss_2d(true_parameters, xi, yi)
data = np.reshape(data, (1, number_points))
data = np.tile(data, (number_fits, 1))

# add Poisson noise
data = np.random.poisson(data)
data = data.astype(np.float32)
```

--------------------------------

### Define Estimator CUDA Device Functions

Source: https://gpufit.readthedocs.io/en/latest/customization.html

Template for implementing the Chi-square, gradient, and Hessian calculation functions in a new .cuh file.

```cpp
///////////////////////////// Chi-square /////////////////////////////
__device__ void ... (           // ... = function name Chi-square
    volatile float * chi_square,
    int const point_index,
    float const * data,
    float const * value,
    float const * weight,
    int * state,
    char * user_info,
    std::size_t const user_info_size)
{
    chi_square[point_index] = ... ;            // formula calculating Chi-square summands
}

////////////////////////////// gradient //////////////////////////////
__device__ void ... (           // ... = function name gradient of Chi-square
    volatile float * gradient,
    int const point_index,
    int const parameter_index,
    float const * data,
    float const * value,
    float const * derivative,
    float const * weight,
    char * user_info,
    std::size_t const user_info_size)
{
    gradient[point_index] = ... ;           // formula calculating summands of the gradient of Chi-square
                                            // model derivates are stored in derivative[parameter_index]
}

////////////////////////////// hessian //////////////////////////////
__device__ void ... (           // function name hessian
    double * hessian,
    int const point_index,
    int const parameter_index_i,
    int const parameter_index_j,
    float const * data,
    float const * value,
    float const * derivative,
    float const * weight,
    char * user_info,
    std::size_t const user_info_size)
{
    *hessian += ... ;            // formula calculating summands of the hessian of Chi-square
}
```

--------------------------------

### Calculate Fit State Histogram

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Iterates over output states to generate a histogram of fit convergence results.

```cpp
// get fit states
std::vector< int > output_states_histogram(5, 0);
for (std::vector< int >::iterator it = output_states.begin(); it != output_states.end(); ++it)
{
    output_states_histogram[*it]++;
}
```

--------------------------------

### gpufit_cuda_available

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Checks if the CUDA environment is available.

```APIDOC
## gpufit_cuda_available

### Description
Verifies if a suitable CUDA device and driver are available.

### Signature
int gpufit_cuda_available();

### Returns
- **int** - 1 if CUDA is available, 0 otherwise.
```

--------------------------------

### gpufit_cuda_interface()

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Performs fitting directly on data already resident in GPU memory, skipping CPU-GPU data transfer.

```APIDOC
## int gpufit_cuda_interface(...)

### Description
Performs fitting without transferring input/output data between CPU and GPU memory. The function uses pointers to GPU-resident memory for all data, weights, and parameters.

### Parameters
- **gpu_data** (float *) - Pointer to data values on GPU.
- **gpu_weights** (float *) - Pointer to weights on GPU (NULL for equal weighting).
- **gpu_user_info** (char *) - Pointer to user info on GPU.
- **gpu_fit_parameters** (float *) - Pointer to initial parameters (input) and best-fit parameters (output) on GPU.
- **gpu_output_states** (int *) - Pointer to fit result state IDs on GPU.
- **gpu_output_chi_squares** (float *) - Pointer to chi-square values on GPU.
- **gpu_output_n_iterations** (int *) - Pointer to iteration counts on GPU.

### Return Value
- **0** - No error
- **-1** - Error
```

--------------------------------

### Generate 2D grid positions

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Creates x and y coordinate arrays for a 2D grid.

```java
// generate x and y values
float[] xi = new float[numberPoints];
float[] yi = new float[numberPoints];
for (int i = 0; i < sizeX; i++) {
    for (int j = 0; j < sizeX; j++) {
        xi[i * sizeX + j] = i;
        yi[i * sizeX + j] = j;
    }
}
```

--------------------------------

### Gpufit Matlab Function Signature

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Standard interface for performing fits in Matlab. Optional parameters can be passed as empty matrices.

```matlab
function [parameters, states, chi_squares, n_iterations, time] = gpufit(data, weights, model_id, initial_parameters, tolerance, max_n_iterations, parameters_to_fit, estimator_id, user_info)
```

--------------------------------

### Set Estimator and Model IDs

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Configures the estimator and model identifiers required for the Gpufit interface.

```python
# estimator ID
estimator_id = gf.EstimatorID.MLE

# model ID
model_id = gf.ModelID.GAUSS_2D
```

--------------------------------

### fit_constrained(data, weights, model_id, initial_parameters, ...)

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Performs constrained curve fitting on the provided data.

```APIDOC
## fit_constrained(data, weights, model_id, initial_parameters, constraints=None, constraint_types=None, ...)

### Description
Performs constrained curve fitting on the provided data, similar to the fit method but with additional parameter constraints.

### Parameters
- **constraints** (np.float32 2D array) - Optional - Constraint bound intervals of shape (number_fits, 2*number_parameter).
- **constraint_types** (np.int32 1D array) - Optional - Constraint types for every parameter.
```

--------------------------------

### Gpufit.isCudaAvailable Method Signature

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Checks if the CUDA environment is available for use.

```java
public static native boolean isCudaAvailable()
```

--------------------------------

### get_cuda_version()

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Retrieves the CUDA runtime and driver versions.

```APIDOC
## get_cuda_version()

### Description
Returns the CUDA runtime and driver versions.

### Returns
- **runtime version** (Tuple) - (Major version, Minor version).
- **driver version** (Tuple) - (Major version, Minor version).
```

--------------------------------

### gpufit_get_cuda_version()

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

Retrieves the current CUDA runtime and driver versions.

```APIDOC
## int gpufit_get_cuda_version(int * runtime_version, int * driver_version)

### Description
Returns the CUDA runtime version and the installed CUDA driver version. The versions are returned via pointers provided as arguments.

### Parameters
- **runtime_version** (int*) - Required - Pointer to the CUDA runtime version number. Format is (Minor version * 10) + (Major version * 1000). Returns 0 if incompatible.
- **driver_version** (int*) - Required - Pointer to the CUDA driver version number. Format is (Minor version * 10) + (Major version * 1000). Returns 0 if no CUDA enabled card is detected.

### Return Value
- **int** - Status code: 0 for success, -1 for error. Use gpufit_get_last_error() to retrieve error details.
```

--------------------------------

### Gpufit.isCudaAvailable

Source: https://gpufit.readthedocs.io/en/latest/bindings.html

Checks if the CUDA environment is available.

```APIDOC
## public static native boolean isCudaAvailable()

### Description
Returns true if CUDA is available and false otherwise.
```

--------------------------------

### Generate 2D Coordinate Grid

Source: https://gpufit.readthedocs.io/en/latest/examples.html

Computes X and Y coordinate vectors for a 2D grid ranging from 0 to 29.

```cpp
// generate x and y values
std::vector< float > x(n_points_per_fit);
std::vector< float > y(n_points_per_fit);
for (size_t i = 0; i < size_x; i++)
{
    for (size_t j = 0; j < size_x; j++) {
        x[i * size_x + j] = static_cast<float>(j);
        y[i * size_x + j] = static_cast<float>(i);
    }
}
```

--------------------------------

### Cite Gpufit publication

Source: https://gpufit.readthedocs.io/en/latest/introduction.html

Use this citation format when referencing Gpufit in research publications.

```text
Gpufit: An open-source toolkit for GPU-accelerated curve fitting
Adrian Przybylski, Björn Thiel, Jan Keller-Findeisen, Bernd Stock, and Mark Bates
Scientific Reports, vol. 7, 15722 (2017); doi: https://doi.org/10.1038/s41598-017-15313-9
```

--------------------------------

### gpufit_constrained_portable_interface

Source: https://gpufit.readthedocs.io/en/latest/gpufit_api.html

A wrapper function for gpufit_constrained() that accepts parameters via an array of pointers.

```APIDOC
## gpufit_constrained_portable_interface

### Description
Provides an alternative interface to the gpufit_constrained() function by passing parameters through an array of pointers.

### Signature
int gpufit_constrained_portable_interface(int argc, void *argv[]);
```

--------------------------------

### Register Estimator in Switch Cases

Source: https://gpufit.readthedocs.io/en/latest/customization.html

Add the new estimator to the switch statements in estimators.cuh for Chi-square, gradient, and Hessian calculations.

```cpp
switch (estimator_id)
{
case LSE:
    calculate_chi_square_lse(chi_square, point_index, data, value, weight, state, user_info, user_info_size);
    break;
    .
    .
    .
case ...:           // estimator ID
    ...             // function name Chi-square
        (chi_square, point_index, data, value, weight, state, user_info, user_info_size);
    break;

default:
    break;
}
```

```cpp
switch (estimator_id)
{
case LSE:
    calculate_gradient_lse(gradient, point_index, parameter_index, data, value, derivative, weight, user_info, user_info_size);
    break;
    .
    .
    .
case ...:           // estimator ID
    ...             // function name gradient
        (gradient, point_index, parameter_index, data, value, derivative, weight, user_info, user_info_size);
    break;

default:
    break;
}
```

```cpp
switch (estimator_id)
{
case LSE:
    calculate_hessian_lse
        (hessian, point_index, parameter_index_i, parameter_index_j, data, value, derivative, weight, user_info,user_info_size);
    break;
    .
    .
    .
case ...:           // estimator ID
    ...             // function name hessian
        (hessian, point_index, parameter_index_i, parameter_index_j, data, value, derivative, weight, user_info, user_info_size);
    break;

default:
    break;
}
```
Tokens:
Raw