dmlfw_ml_configurations.h File Reference

Gradient descent configuration data structures and APIs. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

typedef void(*	dmlfw_gradient_descent_lin_reg_data_provider_t) (void *x, void *y, uint64_t from_row_index, uint32_t how_many_rows)
	Data provider callback for gradient descent linear regression.
typedef int(*	dmlfw_gradient_descent_lin_reg_progress_callback_t) (uint64_t iteration_number, void *y, void *predicted_y, void *model, double regularization_parameter)
	Progress callback for gradient descent linear regression.
typedef struct _dmlfw_gradient_descent_options	dmlfw_gradient_descent_options
	Opaque structure representing gradient descent configuration options.
dmlfw_gradient_descent_options *	dmlfw_gradient_descent_options_create_new (void)
	Creates a new gradient descent options object with default values.
void	dmlfw_gradient_descent_options_destroy (dmlfw_gradient_descent_options *gd_options)
	Destroys a gradient descent options object and frees associated memory.
dmlfw_gradient_descent_lin_reg_data_provider_t	dmlfw_gradient_descent_options_get_data_provider (dmlfw_gradient_descent_options *gd_options)
	Gets the data provider callback pointer.
int	dmlfw_gradient_descent_options_get_gradient_descent_type (dmlfw_gradient_descent_options *gd_options)
	Gets the gradient descent type.
double	dmlfw_gradient_descent_options_get_learning_rate (dmlfw_gradient_descent_options *gd_options)
	Gets the learning rate.
uint32_t	dmlfw_gradient_descent_options_get_mini_batch_size (dmlfw_gradient_descent_options *gd_options)
	Gets the mini-batch size.
uint64_t	dmlfw_gradient_descent_options_get_number_of_iterations (dmlfw_gradient_descent_options *gd_options)
	Gets the number of iterations.
dmlfw_gradient_descent_lin_reg_progress_callback_t	dmlfw_gradient_descent_options_get_progress_callback (dmlfw_gradient_descent_options *gd_options)
	Gets the progress callback pointer.
void	dmlfw_gradient_descent_options_set_data_provider (dmlfw_gradient_descent_options *gd_options, dmlfw_gradient_descent_lin_reg_data_provider_t data_provider)
	Sets the data provider callback.
void	dmlfw_gradient_descent_options_set_gradient_descent_type (dmlfw_gradient_descent_options *gd_options, int gradient_descent_type)
	Sets the gradient descent type.
void	dmlfw_gradient_descent_options_set_learning_rate (dmlfw_gradient_descent_options *gd_options, double learning_rate)
	Sets the learning rate.
void	dmlfw_gradient_descent_options_set_mini_batch_size (dmlfw_gradient_descent_options *gd_options, uint32_t mini_batch_size)
	Sets the mini-batch size for mini-batch gradient descent.
void	dmlfw_gradient_descent_options_set_number_of_iterations (dmlfw_gradient_descent_options *gd_options, uint64_t number_of_iterations)
	Sets the number of iterations.
void	dmlfw_gradient_descent_options_set_progress_callback (dmlfw_gradient_descent_options *gd_options, dmlfw_gradient_descent_lin_reg_progress_callback_t progress_callback)
	Sets the progress callback.
enum	MLFW_GRADIENT_DESCENT_TYPE { MLFW_BATCH_GRADIENT_DESCENT , MLFW_STOCHASTIC_GRADIENT_DESCENT , MLFW_MINI_BATCH_GRADIENT_DESCENT }
	Gradient descent algorithm types. More...

Detailed Description

Gradient descent configuration data structures and APIs.

Version

1.0

Date

2025-09-25

This module provides definitions and management functions for gradient descent configuration objects used with ML algorithms such as linear regression. It enables detailed customization of learning rate, iterations, gradient descent type, progress callbacks, data provisioning, and mini-batch processing.

Error Handling:

All functions validate input parameters and report errors via the centralized error API. After function calls, check dmlfw_error() to detect if an error occurred. Retrieve descriptive error messages with dmlfw_get_error_string() and diagnostic info with dmlfw_get_debug_string().

Typedef Documentation

dmlfw_gradient_descent_lin_reg_data_provider_t

typedef void(* dmlfw_gradient_descent_lin_reg_data_provider_t) (void *x, void *y, uint64_t from_row_index, uint32_t how_many_rows)

Data provider callback for gradient descent linear regression.

Supplies batches of data for training.

Parameters

x	Feature matrix subset.
y	Target vector subset.
from_row_index	Index of first row in batch.
how_many_rows	Number of rows in batch.

dmlfw_gradient_descent_lin_reg_progress_callback_t

typedef int(* dmlfw_gradient_descent_lin_reg_progress_callback_t) (uint64_t iteration_number, void *y, void *predicted_y, void *model, double regularization_parameter)

Progress callback for gradient descent linear regression.

Called during each iteration to report training status.

Parameters

iteration_number	Current iteration count.
y	Actual target values.
predicted_y	Predicted target values.
model	Current model parameters.
regularization_parameter	Regularization term used.

Returns

Zero to continue training, negative to terminate early.

dmlfw_gradient_descent_options

typedef struct _dmlfw_gradient_descent_options dmlfw_gradient_descent_options

Opaque structure representing gradient descent configuration options.

The internal details are hidden. Use the provided API functions to create, manipulate, and destroy instances.

Enumeration Type Documentation

MLFW_GRADIENT_DESCENT_TYPE

enum MLFW_GRADIENT_DESCENT_TYPE

Gradient descent algorithm types.

Enumerator
MLFW_BATCH_GRADIENT_DESCENT	Full batch gradient descent.
MLFW_STOCHASTIC_GRADIENT_DESCENT	Stochastic gradient descent.
MLFW_MINI_BATCH_GRADIENT_DESCENT	Mini-batch gradient descent.

Function Documentation

dmlfw_gradient_descent_options_create_new()

dmlfw_gradient_descent_options * dmlfw_gradient_descent_options_create_new

(

void

)

Creates a new gradient descent options object with default values.

Returns

Pointer to allocated options or NULL on failure.

Note

Caller must destroy the returned object via dmlfw_gradient_descent_options_destroy().

Usage example in API context:

dmlfw_gradient_descent_options *opts = dmlfw_gradient_descent_options_create_new();
if (opts == NULL || dmlfw_error()) {
    // Handle error (e.g., return NULL up the call chain)
}
// use opts...
dmlfw_gradient_descent_options_destroy(opts);

Usage example in main():

int main() {
    char err[512], dbg[512];
    dmlfw_gradient_descent_options *opts = dmlfw_gradient_descent_options_create_new();
    if (dmlfw_error()) {
        dmlfw_get_error_string(err, sizeof(err));
        dmlfw_get_debug_string(dbg, sizeof(dbg));
        printf("Failed to create options: %s\nDebug info: %s\n", err, dbg);
        return EXIT_FAILURE;
    }
    // use opts...
    dmlfw_gradient_descent_options_destroy(opts);
    return EXIT_SUCCESS;
}

See also

dmlfw_gradient_descent_options_destroy

Examples

example_dmlfw_linear_regression.c, and example_dmlfw_ml_configurations.c.

dmlfw_gradient_descent_options_destroy()

void dmlfw_gradient_descent_options_destroy

(

dmlfw_gradient_descent_options *

gd_options

)

Destroys a gradient descent options object and frees associated memory.

Parameters

gd_options

[in] Pointer to options to destroy, or NULL (no-op).

Usage example:

dmlfw_gradient_descent_options_destroy(opts);

See also

dmlfw_gradient_descent_options_create_new

Examples

example_dmlfw_linear_regression.c, and example_dmlfw_ml_configurations.c.

dmlfw_gradient_descent_options_get_data_provider()

dmlfw_gradient_descent_lin_reg_data_provider_t dmlfw_gradient_descent_options_get_data_provider

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the data provider callback pointer.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Data provider callback function pointer or NULL on error.

Usage example:

auto dp = dmlfw_gradient_descent_options_get_data_provider(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_data_provider

dmlfw_gradient_descent_options_get_gradient_descent_type()

int dmlfw_gradient_descent_options_get_gradient_descent_type

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the gradient descent type.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Gradient descent type or -1 on error.

Usage example:

int type = dmlfw_gradient_descent_options_get_gradient_descent_type(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_gradient_descent_type

dmlfw_gradient_descent_options_get_learning_rate()

double dmlfw_gradient_descent_options_get_learning_rate

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the learning rate.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Current learning rate or NaN on error.

Usage example:

double rate = dmlfw_gradient_descent_options_get_learning_rate(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_learning_rate

dmlfw_gradient_descent_options_get_mini_batch_size()

uint32_t dmlfw_gradient_descent_options_get_mini_batch_size

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the mini-batch size.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Mini-batch size or 0 on error.

Usage example:

uint32_t size = dmlfw_gradient_descent_options_get_mini_batch_size(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_mini_batch_size

dmlfw_gradient_descent_options_get_number_of_iterations()

uint64_t dmlfw_gradient_descent_options_get_number_of_iterations

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the number of iterations.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Number of iterations or 0 on error.

Usage example:

uint64_t num = dmlfw_gradient_descent_options_get_number_of_iterations(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_number_of_iterations

dmlfw_gradient_descent_options_get_progress_callback()

dmlfw_gradient_descent_lin_reg_progress_callback_t dmlfw_gradient_descent_options_get_progress_callback

(

dmlfw_gradient_descent_options *

gd_options

)

Gets the progress callback pointer.

Parameters

gd_options

[in] Gradient descent options (must not be NULL).

Returns

Progress callback function pointer or NULL on error.

Usage example:

auto cb = dmlfw_gradient_descent_options_get_progress_callback(opts);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_set_progress_callback

dmlfw_gradient_descent_options_set_data_provider()

void dmlfw_gradient_descent_options_set_data_provider	(	dmlfw_gradient_descent_options *	gd_options,
		dmlfw_gradient_descent_lin_reg_data_provider_t	data_provider
	)

Sets the data provider callback.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
data_provider	[in] Callback function pointer or NULL.

Usage example:

dmlfw_gradient_descent_options_set_data_provider(opts, my_data_provider);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_data_provider

dmlfw_gradient_descent_options_set_gradient_descent_type()

void dmlfw_gradient_descent_options_set_gradient_descent_type	(	dmlfw_gradient_descent_options *	gd_options,
		int	gradient_descent_type
	)

Sets the gradient descent type.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
gradient_descent_type	[in] One of MLFW_BATCH_GRADIENT_DESCENT, MLFW_STOCHASTIC_GRADIENT_DESCENT, MLFW_MINI_BATCH_GRADIENT_DESCENT.

Usage example:

dmlfw_gradient_descent_options_set_gradient_descent_type(opts, MLFW_BATCH_GRADIENT_DESCENT);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_gradient_descent_type

dmlfw_gradient_descent_options_set_learning_rate()

void dmlfw_gradient_descent_options_set_learning_rate	(	dmlfw_gradient_descent_options *	gd_options,
		double	learning_rate
	)

Sets the learning rate.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
learning_rate	[in] Learning rate value.

Usage example:

dmlfw_gradient_descent_options_set_learning_rate(opts, 0.01);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_learning_rate

Examples

example_dmlfw_linear_regression.c, and example_dmlfw_ml_configurations.c.

dmlfw_gradient_descent_options_set_mini_batch_size()

void dmlfw_gradient_descent_options_set_mini_batch_size	(	dmlfw_gradient_descent_options *	gd_options,
		uint32_t	mini_batch_size
	)

Sets the mini-batch size for mini-batch gradient descent.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
mini_batch_size	[in] Number of samples in a mini-batch.

Usage example:

dmlfw_gradient_descent_options_set_mini_batch_size(opts, 32);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_mini_batch_size

dmlfw_gradient_descent_options_set_number_of_iterations()

void dmlfw_gradient_descent_options_set_number_of_iterations	(	dmlfw_gradient_descent_options *	gd_options,
		uint64_t	number_of_iterations
	)

Sets the number of iterations.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
number_of_iterations	[in] Number of iterations.

Usage example:

dmlfw_gradient_descent_options_set_number_of_iterations(opts, 1000);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_number_of_iterations

Examples

example_dmlfw_linear_regression.c.

dmlfw_gradient_descent_options_set_progress_callback()

void dmlfw_gradient_descent_options_set_progress_callback	(	dmlfw_gradient_descent_options *	gd_options,
		dmlfw_gradient_descent_lin_reg_progress_callback_t	progress_callback
	)

Sets the progress callback.

Parameters

gd_options	[in,out] Gradient descent options (must not be NULL).
progress_callback	[in] Callback function pointer or NULL.

Usage example:

dmlfw_gradient_descent_options_set_progress_callback(opts, my_callback);
if (dmlfw_error()) {
    // Handle error
}

See also

dmlfw_gradient_descent_options_get_progress_callback