A CCS tree space defines an search space over a tree. More...

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

Data Structures
struct	ccs_dynamic_tree_space_vector_s
	A structure that define the callbacks the user must provide to create a dynamic tree space. More...

Typedefs
typedef enum ccs_tree_space_type_e	ccs_tree_space_type_t
	A commodity type to represent CCS tree space types.

typedef struct ccs_dynamic_tree_space_vector_s	ccs_dynamic_tree_space_vector_t
	A commodity type to represent a dynamic tree space callback vector.

Enumerations
enum	ccs_tree_space_type_e { CCS_TREE_SPACE_TYPE_STATIC , CCS_TREE_SPACE_TYPE_DYNAMIC , CCS_TREE_SPACE_TYPE_MAX , CCS_TREE_SPACE_TYPE_FORCE_32BIT = INT_MAX }
	CCS supported tree space types. More...

Functions
ccs_result_t	ccs_create_static_tree_space (const char name, ccs_tree_t tree, ccs_feature_space_t feature_space, ccs_rng_t rng, ccs_tree_space_t tree_space_ret)
	Create a new static tree space.

ccs_result_t	ccs_create_dynamic_tree_space (const char name, ccs_tree_t tree, ccs_feature_space_t feature_space, ccs_rng_t rng, ccs_dynamic_tree_space_vector_t vector, void tree_space_data, ccs_tree_space_t tree_space_ret)
	Create a new static tree space.

ccs_result_t	ccs_tree_space_get_type (ccs_tree_space_t tree_space, ccs_tree_space_type_t *type_ret)
	Get the type of a tree space.

ccs_result_t	ccs_tree_space_get_name (ccs_tree_space_t tree_space, const char **name_ret)
	Get the name of a tree space.

ccs_result_t	ccs_tree_space_get_rng (ccs_tree_space_t tree_space, ccs_rng_t *rng_ret)
	Get the internal rng of the tree space.

ccs_result_t	ccs_tree_space_get_feature_space (ccs_tree_space_t tree_space, ccs_feature_space_t *feature_space_ret)
	Get the feature space of the tree space.

ccs_result_t	ccs_tree_space_get_tree (ccs_tree_space_t tree_space, ccs_tree_t *tree_ret)
	Get the tree of a tree space.

ccs_result_t	ccs_tree_space_get_node_at_position (ccs_tree_space_t tree_space, size_t position_size, const size_t position, ccs_tree_t tree_ret)
	Get the node at a given position in a tree space.

ccs_result_t	ccs_tree_space_get_values_at_position (ccs_tree_space_t tree_space, size_t position_size, const size_t position, size_t num_values, ccs_datum_t values)
	Get the values along the path to a given position in the tree space.

ccs_result_t	ccs_tree_space_sample (ccs_tree_space_t tree_space, ccs_features_t features, ccs_rng_t rng, ccs_tree_configuration_t *configuration_ret)
	Get a tree configuration sampled randomly from a tree space.

ccs_result_t	ccs_tree_space_samples (ccs_tree_space_t tree_space, ccs_features_t features, ccs_rng_t rng, size_t num_configurations, ccs_tree_configuration_t *configurations)
	Get a given number of configurations sampled randomly from a tree space.

ccs_result_t	ccs_dynamic_tree_space_get_tree_space_data (ccs_tree_space_t tree_space, void **tree_space_data_ret)
	Get the dynamic tree space internal data pointer.

Detailed Description

A CCS tree space defines an search space over a tree.

Optionally configuration space can be attached a feature space (see feature_space.h). Tree spaces can be sampled to obtain tree configurations. Configurations con point to unknown children (if they exist). This is where static tree spaces and dynamic tree spaces differ: in a static tree space, the user is responsible for modifying the tree before evaluating these configuration values or node; in a dynamic tree space, when querying a configuration validity, node or values, a callback will be invoked to define the missing children on the configuration path. Sampling a dynamic tree space, by itself, does not modify the tree.

Enumeration Type Documentation

◆ ccs_tree_space_type_e

enum ccs_tree_space_type_e

CCS supported tree space types.

Enumerator
CCS_TREE_SPACE_TYPE_STATIC	A static tree space.
CCS_TREE_SPACE_TYPE_DYNAMIC	A dynamic tree space.
CCS_TREE_SPACE_TYPE_MAX	Guard.
CCS_TREE_SPACE_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

Function Documentation

◆ ccs_create_dynamic_tree_space()

ccs_result_t ccs_create_dynamic_tree_space	(	const char *	name,
		ccs_tree_t	tree,
		ccs_feature_space_t	feature_space,
		ccs_rng_t	rng,
		ccs_dynamic_tree_space_vector_t *	vector,
		void *	tree_space_data,
		ccs_tree_space_t *	tree_space_ret
	)

extern

Create a new static tree space.

Parameters

[in]	name	pointer to a string that will be copied internally
[in]	tree	the tree defining the tree space
[in]	feature_space	an optional CCS feature space object
[in]	rng	an optional CCS rng object
[in]	vector	the callback vector implementing the dynamic tree space interface
[in]	tree_space_data	a pointer to the tree space internal data structures can be NULL
[out]	tree_space_ret	a pointer to the variable that will hold the newly created tree space.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if tree_space_ret is NULL; or if any non optional interface pointer is NULL; CCS_RESULT_ERROR_INVALID_OBJECT if rng is not NULL and is not a valid CCS rng; or it feature_space is not NULL and is not a valid CCS feature space; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new tree space

Remarks: This function is thread-safe

◆ ccs_create_static_tree_space()

ccs_result_t ccs_create_static_tree_space	(	const char *	name,
		ccs_tree_t	tree,
		ccs_feature_space_t	feature_space,
		ccs_rng_t	rng,
		ccs_tree_space_t *	tree_space_ret
	)

extern

Create a new static tree space.

Parameters

[in]	name	pointer to a string that will be copied internally
[in]	tree	the tree defining the tree space
[in]	feature_space	an optional CCS feature space object
[in]	rng	an optional CCS rng object
[out]	tree_space_ret	a pointer to the variable that will hold the newly created tree space.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if tree_space_ret is NULL; CCS_RESULT_ERROR_INVALID_OBJECT if rng is not NULL and is not a valid CCS rng; or it feature_space is not NULL and is not a valid CCS feature space; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new tree space

Remarks: This function is thread-safe

◆ ccs_dynamic_tree_space_get_tree_space_data()

ccs_result_t ccs_dynamic_tree_space_get_tree_space_data	(	ccs_tree_space_t	tree_space,
		void **	tree_space_data_ret
	)

extern

Get the dynamic tree space internal data pointer.

Parameters

[in]	tree_space
[out]	tree_space_data_ret

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_INVALID_TREE_SPACE if tree_space is not a dynamic tree space; CCS_RESULT_ERROR_INVALID_VALUE if tree_space_data_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tree_space_get_feature_space()

ccs_result_t ccs_tree_space_get_feature_space	(	ccs_tree_space_t	tree_space,
		ccs_feature_space_t *	feature_space_ret
	)

extern

Get the feature space of the tree space.

Parameters

[in]	tree_space
[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 tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_INVALID_VALUE if feature_space_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tree_space_get_name()

ccs_result_t ccs_tree_space_get_name	(	ccs_tree_space_t	tree_space,
		const char **	name_ret
	)

extern

Get the name of a tree space.

Parameters

[in]	tree_space
[out]	name_ret	a pointer to the variable that will contain a pointer to the name of the tree space

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 tree space

Remarks: This function is thread-safe

◆ ccs_tree_space_get_node_at_position()

ccs_result_t ccs_tree_space_get_node_at_position	(	ccs_tree_space_t	tree_space,
		size_t	position_size,
		const size_t *	position,
		ccs_tree_t *	tree_ret
	)

extern

Get the node at a given position in a tree space.

Parameters

[in]	tree_space
[in]	position_size	the number of entries in the `position` array
[in]	position	an array of indexes defining a location in the tree space. can be NULL if `position_size` is 0
[out]	tree_ret	a pointer to the variable that will contain the node

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_INVALID_VALUE if tree_ret is NULL; or if position is NULL and position_size is greater than 0; CCS_RESULT_ERROR_OUT_OF_BOUNDS if position does not define a valid position in tree_space; CCS_RESULT_ERROR_INVALID_TREE if one child node described by position is undefined and tree_space is a static tree space

Remarks: This function is NOT thread-safe for dynamic tree spaces as it can instantiate new children

◆ ccs_tree_space_get_rng()

ccs_result_t ccs_tree_space_get_rng	(	ccs_tree_space_t	tree_space,
		ccs_rng_t *	rng_ret
	)

extern

Get the internal rng of the tree space.

Parameters

[in]	tree_space
[out]	rng_ret	a pointer to the variable that will contain the rng

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_INVALID_VALUE if rng_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tree_space_get_tree()

ccs_result_t ccs_tree_space_get_tree	(	ccs_tree_space_t	tree_space,
		ccs_tree_t *	tree_ret
	)

extern

Get the tree of a tree space.

Parameters

[in]	tree_space
[out]	tree_ret	a pointer to the variable that will contain the tree

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_INVALID_VALUE if rng_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tree_space_get_type()

ccs_result_t ccs_tree_space_get_type	(	ccs_tree_space_t	tree_space,
		ccs_tree_space_type_t *	type_ret
	)

extern

Get the type of a tree space.

Parameters

[in]	tree_space
[out]	type_ret	a pointer to the variable that will contain the returned tree space type

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

Remarks: This function is thread-safe

◆ ccs_tree_space_get_values_at_position()

ccs_result_t ccs_tree_space_get_values_at_position	(	ccs_tree_space_t	tree_space,
		size_t	position_size,
		const size_t *	position,
		size_t	num_values,
		ccs_datum_t *	values
	)

extern

Get the values along the path to a given position in the tree space.

Parameters

[in]	tree_space
[in]	position_size	the number of entries in the `position` array
[in]	position	an array of indexes defining a location in the tree space. can be NULL if `position_size` is 0
[in]	num_values	the size of the `values` array
[out]	values	an array of size `num_values` to hold the returned values, or NULL. If the array is too big, extra values are set to CCS_DATA_TYPE_NONE

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; CCS_RESULT_ERROR_OUT_OF_BOUNDS if position does not define a valid position in tree_space; CCS_RESULT_ERROR_INVALID_TREE if one child node described by position is undefined and tree_space is a static tree space; CCS_RESULT_ERROR_INVALID_VALUE if values is NULL; if num_values is less than position_size + 1; or if position is NULL and position_size is greater than 0

Remarks: This function is NOT thread-safe for dynamic tree spaces as it can instantiate new children

◆ ccs_tree_space_sample()

ccs_result_t ccs_tree_space_sample	(	ccs_tree_space_t	tree_space,
		ccs_features_t	features,
		ccs_rng_t	rng,
		ccs_tree_configuration_t *	configuration_ret
	)

extern

Get a tree configuration sampled randomly from a tree space.

The space is sampled according to the weight and bias of the individual tree nodes. If those are at their default values, the tree nodes are sampled uniformly.

Parameters

[in]	tree_space
[in]	features	an optional features to use. Required if a feature space was provided at `tree_space` creation.
[in]	rng	an optional rng to use
[out]	configuration_ret	a pointer to the variable that will contain the returned tree configuration

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; or if rng is not a valid CCS rng; or if features is not NULL and is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features feature space is not the same as the feature space provided at tree_space creation.; CCS_RESULT_ERROR_INVALID_VALUE if configuration_ret is NULL; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new configuration

Remarks: This function is NOT thread-safe

◆ ccs_tree_space_samples()

ccs_result_t ccs_tree_space_samples	(	ccs_tree_space_t	tree_space,
		ccs_features_t	features,
		ccs_rng_t	rng,
		size_t	num_configurations,
		ccs_tree_configuration_t *	configurations
	)

extern

Get a given number of configurations sampled randomly from a tree space.

The space is sampled according to the weight and bias of the individual tree nodes. If those are at their default values, the tree nodes are sampled uniformely.

Parameters

[in]	tree_space
[in]	features	an optional features to use. Required if a feature space was provided at `tree_space` creation.
[in]	rng	an optional rng to use
[in]	num_configurations	the number of requested configurations
[out]	configurations	an array of `num_configurations` that will contain the requested configurations

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree_space is not a valid CCS tree space; or if rng is not NULL and is not a valid CCS rng; or if features is not NULL and is not a valid CCS features; CCS_RESULT_ERROR_INVALID_FEATURES if features feature space is not the same as the feature space provided at tree_space creation.; CCS_RESULT_ERROR_INVALID_VALUE if configurations is NULL and num_configurations is greater than 0; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new configurations

Remarks: This function is NOT thread-safe

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ccs_tree_space_type_e

Function Documentation

◆ ccs_create_dynamic_tree_space()

◆ ccs_create_static_tree_space()

◆ ccs_dynamic_tree_space_get_tree_space_data()

◆ ccs_tree_space_get_feature_space()

◆ ccs_tree_space_get_name()

◆ ccs_tree_space_get_node_at_position()

◆ ccs_tree_space_get_rng()

◆ ccs_tree_space_get_tree()

◆ ccs_tree_space_get_type()

◆ ccs_tree_space_get_values_at_position()

◆ ccs_tree_space_sample()

◆ ccs_tree_space_samples()