A CCS tuner defines an ask and tell interface to optimize an objective space (see objective_space.h). More...

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

Data Structures
struct	ccs_user_defined_tuner_vector_s
	A structure that define the callbacks the user must provide to create a user defined tuner. More...

Typedefs
typedef enum ccs_tuner_type_e	ccs_tuner_type_t
	A commodity type to represent CCS tuner types.

typedef struct ccs_user_defined_tuner_vector_s	ccs_user_defined_tuner_vector_t
	a commodity type to represent a user defined tuner callback vector.

Enumerations
enum	ccs_tuner_type_e { CCS_TUNER_TYPE_RANDOM , CCS_TUNER_TYPE_USER_DEFINED , CCS_TUNER_TYPE_MAX , CCS_TUNER_TYPE_32BIT = INT_MAX }
	CCS supported tuner types. More...

Functions
ccs_result_t	ccs_tuner_get_type (ccs_tuner_t tuner, ccs_tuner_type_t *type_ret)
	Get the type of a tuner.

ccs_result_t	ccs_tuner_get_name (ccs_tuner_t tuner, const char **name_ret)
	Get the name of a tuner.

ccs_result_t	ccs_tuner_get_search_space (ccs_tuner_t tuner, ccs_search_space_t *search_space_ret)
	Get the associated search space.

ccs_result_t	ccs_tuner_get_objective_space (ccs_tuner_t tuner, ccs_objective_space_t *objective_space_ret)
	Get the associated objective space.

ccs_result_t	ccs_tuner_get_feature_space (ccs_tuner_t tuner, ccs_feature_space_t *feature_space_ret)
	Get the associated feature space.

ccs_result_t	ccs_tuner_ask (ccs_tuner_t tuner, ccs_features_t features, size_t num_configurations, ccs_search_configuration_t configurations, size_t num_configurations_ret)
	Ask a tuner for a set of configurations to evaluate.

ccs_result_t	ccs_tuner_tell (ccs_tuner_t tuner, size_t num_evaluations, ccs_evaluation_t *evaluations)
	Give a list of results to a tuner through evaluations.

ccs_result_t	ccs_tuner_suggest (ccs_tuner_t tuner, ccs_features_t features, ccs_search_configuration_t *configuration)
	Ask a tuner to suggest a good configuration.

ccs_result_t	ccs_tuner_get_optima (ccs_tuner_t tuner, ccs_features_t features, size_t num_evaluations, ccs_evaluation_t evaluations, size_t num_evaluations_ret)
	Ask a tuner for the discovered Pareto front.

ccs_result_t	ccs_tuner_get_history (ccs_tuner_t tuner, ccs_features_t features, size_t num_evaluations, ccs_evaluation_t evaluations, size_t num_evaluations_ret)
	Ask a tuner for the evaluation history.

ccs_result_t	ccs_create_random_tuner (const char name, ccs_objective_space_t objective_space, ccs_tuner_t tuner_ret)
	Create a new random tuner.

ccs_result_t	ccs_create_user_defined_tuner (const char name, ccs_objective_space_t objective_space, ccs_user_defined_tuner_vector_t vector, void tuner_data, ccs_tuner_t tuner_ret)
	Create a new user defined tuner.

ccs_result_t	ccs_user_defined_tuner_get_tuner_data (ccs_tuner_t tuner, void **tuner_data_ret)
	Get the user defined tuner internal data pointer.

Detailed Description

A CCS tuner defines an ask and tell interface to optimize an objective space (see objective_space.h).

The tuner will propose search configurations (see search_configuration.h) and the user will return evaluations (see evaluation.h).

Enumeration Type Documentation

◆ ccs_tuner_type_e

enum ccs_tuner_type_e

CCS supported tuner types.

Enumerator
CCS_TUNER_TYPE_RANDOM	A random tuner.
CCS_TUNER_TYPE_USER_DEFINED	A user defined tuner.
CCS_TUNER_TYPE_MAX	Guard.
CCS_TUNER_TYPE_32BIT	Try forcing 32 bits value for bindings.

Function Documentation

◆ ccs_create_random_tuner()

ccs_result_t ccs_create_random_tuner	(	const char *	name,
		ccs_objective_space_t	objective_space,
		ccs_tuner_t *	tuner_ret
	)

extern

Create a new random tuner.

The random tuner should be viewed as a baseline for evaluating tuners, and as a tool for developing interfaces.

Parameters

[in]	name	the name of the tuner
[in]	objective_space	the objective space to optimize
[out]	tuner_ret	a pointer to the variable that will contain the newly created tuner

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if objective_space is not a valid CCS objective space; CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if tuner_ret is NULL; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new tuner instance

Remarks: This function is thread-safe

◆ ccs_create_user_defined_tuner()

ccs_result_t ccs_create_user_defined_tuner	(	const char *	name,
		ccs_objective_space_t	objective_space,
		ccs_user_defined_tuner_vector_t *	vector,
		void *	tuner_data,
		ccs_tuner_t *	tuner_ret
	)

extern

Create a new user defined tuner.

Parameters

[in]	name	the name of the tuner
[in]	objective_space	the objective space to optimize
[in]	vector	the vector of callbacks implementing the tuner interface
[in]	tuner_data	a pointer to the tuner internal data structures. Can be NULL
[out]	tuner_ret	a pointer to the variable that will contain the newly created tuner

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if objective_space is not a valid CCS objective space; CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if tuner_ret is NULL; or if vector is NULL; or if any non optional interface pointer is NULL; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new tuner instance

Remarks: This function is thread-safe

◆ ccs_tuner_ask()

ccs_result_t ccs_tuner_ask	(	ccs_tuner_t	tuner,
		ccs_features_t	features,
		size_t	num_configurations,
		ccs_search_configuration_t *	configurations,
		size_t *	num_configurations_ret
	)

extern

Ask a tuner for a set of configurations to evaluate.

Configuration's ownership is transferred to the user who doesn't need to retain them, but will need to release them once the user is done using them.

Parameters

[in,out]	tuner
[in]	features	the specific features to ask the configurations for
[in]	num_configurations	the number of configurations requested by the user
[out]	configurations	an array of `num_configurations` configurations that will contain the returned configurations. Can be NULL
[out]	num_configurations_ret	a pointer to the variable that will contain the number of configuration that are returned, or, if `configurations` is NULL, a suggestion for the number of configuration to ask for

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; or if features is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features is not a valid CCS features for the tuner feature space; CCS_RESULT_ERROR_INVALID_VALUE if configurations is NULL and num_configurations is greater than 0; or if configurations and num_configurations_ret are both NULL; CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL if no or not enough valid configurations could be sampled. Configurations that could be sampled will be returned contiguously, and the rest will be NULL; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate new configurations. Configurations that could be allocated will be returned, and the rest will be NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_feature_space()

ccs_result_t ccs_tuner_get_feature_space	(	ccs_tuner_t	tuner,
		ccs_feature_space_t *	feature_space_ret
	)

extern

Get the associated feature space.

Parameters

[in]	tuner
[out]	feature_space_ret	a pointer to the variable that will contain the feature space

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; CCS_RESULT_ERROR_INVALID_VALUE if feature_space_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_history()

ccs_result_t ccs_tuner_get_history	(	ccs_tuner_t	tuner,
		ccs_features_t	features,
		size_t	num_evaluations,
		ccs_evaluation_t *	evaluations,
		size_t *	num_evaluations_ret
	)

extern

Ask a tuner for the evaluation history.

Parameters

[in]	tuner
[in]	features	the specific features to get the history for. Optional, can be NULL
[in]	num_evaluations	the size of the `evaluations` array
[out]	evaluations	an array of `num_evaluations` that will contain the the history. If `features` is given, only return history of evaluations for the given features
[out]	num_evaluations_ret	a pointer to the variable that will contain the number of evaluations that are or would be returned

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; or if features is not NULL and features is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features is not a valid CCS features for the tuner feature space; CCS_RESULT_ERROR_INVALID_VALUE if evaluations is NULL and num_evaluations is greater than 0; or if evaluations is NULL and num_evaluations_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_name()

ccs_result_t ccs_tuner_get_name	(	ccs_tuner_t	tuner,
		const char **	name_ret
	)

extern

Get the name of a tuner.

Parameters

[in]	tuner
[out]	name_ret	a pointer to the variable that will contain a pointer to the name of the tuner

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if name_ret is NULL; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner

Remarks: This function is thread-safe

◆ ccs_tuner_get_objective_space()

ccs_result_t ccs_tuner_get_objective_space	(	ccs_tuner_t	tuner,
		ccs_objective_space_t *	objective_space_ret
	)

extern

Get the associated objective space.

Parameters

[in]	tuner
[out]	objective_space_ret	a pointer to the variable that will contain the objective space

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; CCS_RESULT_ERROR_INVALID_VALUE if objective_space_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_optima()

ccs_result_t ccs_tuner_get_optima	(	ccs_tuner_t	tuner,
		ccs_features_t	features,
		size_t	num_evaluations,
		ccs_evaluation_t *	evaluations,
		size_t *	num_evaluations_ret
	)

extern

Ask a tuner for the discovered Pareto front.

For single objective spaces this would be the best point found.

Parameters

[in]	tuner
[in]	features	the specific features to get the optimal values for. Optional, can be NULL
[in]	num_evaluations	the size of the `evaluations` array
[out]	evaluations	an array of `num_evaluations` that will contain the optimal evaluations. If `features` is given, only return optimal evaluations for the given features
[out]	num_evaluations_ret	a pointer to the variable that will contain the number of evaluations that are or would be returned

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; or if features is not NULL and features is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features is not a valid CCS features for the tuner feature space; CCS_RESULT_ERROR_INVALID_VALUE if evaluations is NULL and num_evaluations is greater than 0; or if evaluations is NULL and num_evaluations_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_search_space()

ccs_result_t ccs_tuner_get_search_space	(	ccs_tuner_t	tuner,
		ccs_search_space_t *	search_space_ret
	)

extern

Get the associated search space.

Parameters

[in]	tuner
[out]	search_space_ret	a pointer to the variable that will contain the search space

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; CCS_RESULT_ERROR_INVALID_VALUE if search_space_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_get_type()

ccs_result_t ccs_tuner_get_type	(	ccs_tuner_t	tuner,
		ccs_tuner_type_t *	type_ret
	)

extern

Get the type of a tuner.

Parameters

[in]	tuner
[out]	type_ret	a pointer to the variable that will contain the returned tuner type

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; CCS_RESULT_ERROR_INVALID_VALUE if type_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tuner_suggest()

ccs_result_t ccs_tuner_suggest	(	ccs_tuner_t	tuner,
		ccs_features_t	features,
		ccs_search_configuration_t *	configuration
	)

extern

Ask a tuner to suggest a good configuration.

Parameters

[in,out]	tuner
[in]	features	the specific features to suggest a configuration for
[out]	configuration	a pointer to the variable that will contain the suggested configuration

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; or if features is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features is not a valid CCS features for the tuner feature space; CCS_RESULT_ERROR_INVALID_VALUE if configuration is NULL; CCS_RESULT_ERROR_UNSUPPORTED_OPERATION if the tuner does not support the suggest interface; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate new configurations

Remarks: This function is thread-safe

◆ ccs_tuner_tell()

ccs_result_t ccs_tuner_tell	(	ccs_tuner_t	tuner,
		size_t	num_evaluations,
		ccs_evaluation_t *	evaluations
	)

extern

Give a list of results to a tuner through evaluations.

Parameters

[in,out]	tuner
[in]	num_evaluations	the size of the `evaluations` array
[in]	evaluations	an array of `num_evaluations` to provide to the tuner

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; or if one of the evaluations is not a valid CCS features evaluation; CCS_RESULT_ERROR_INVALID_VALUE if evaluations is NULL and num_evaluations is greater than 0; CCS_RESULT_ERROR_INVALID_EVALUATION if an evaluation is not a valid evaluation for the problem the tuner is optimizing; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate internal data structures.

Remarks: This function is thread-safe

◆ ccs_user_defined_tuner_get_tuner_data()

ccs_result_t ccs_user_defined_tuner_get_tuner_data	(	ccs_tuner_t	tuner,
		void **	tuner_data_ret
	)

extern

Get the user defined tuner internal data pointer.

Parameters

[in]	tuner
[out]	tuner_data_ret

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tuner is not a valid CCS tuner; CCS_RESULT_ERROR_INVALID_TUNER if tuner is not a user defined tuner; CCS_RESULT_ERROR_INVALID_VALUE if tuner_data_ret is NULL

Remarks: This function is thread-safe

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ccs_tuner_type_e

Function Documentation

◆ ccs_create_random_tuner()

◆ ccs_create_user_defined_tuner()

◆ ccs_tuner_ask()

◆ ccs_tuner_get_feature_space()

◆ ccs_tuner_get_history()

◆ ccs_tuner_get_name()

◆ ccs_tuner_get_objective_space()

◆ ccs_tuner_get_optima()

◆ ccs_tuner_get_search_space()

◆ ccs_tuner_get_type()

◆ ccs_tuner_suggest()

◆ ccs_tuner_tell()

◆ ccs_user_defined_tuner_get_tuner_data()