A CCS tree object represents a node in a tree structure. More...

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

Functions
ccs_result_t	ccs_create_tree (size_t arity, ccs_datum_t value, ccs_tree_t *tree_ret)
	Create new tree node.

ccs_result_t	ccs_tree_get_value (ccs_tree_t tree, ccs_datum_t *value_ret)
	Get the value of a tree node.

ccs_result_t	ccs_tree_get_arity (ccs_tree_t tree, size_t *arity_ret)
	Get the arity of a tree node.

ccs_result_t	ccs_tree_set_child (ccs_tree_t tree, size_t index, ccs_tree_t child)
	Set an unset child in a tree node at the given index.

ccs_result_t	ccs_tree_get_child (ccs_tree_t tree, size_t index, ccs_tree_t *child_ret)
	Query a tree node for the child at the given index.

ccs_result_t	ccs_tree_get_children (ccs_tree_t tree, size_t num_children, ccs_tree_t children, size_t num_children_ret)
	Query all the children of a tree node.

ccs_result_t	ccs_tree_get_parent (ccs_tree_t tree, ccs_tree_t parent_ret, size_t index_ret)
	Get the parent node of a tree node.

ccs_result_t	ccs_tree_get_position (ccs_tree_t tree, size_t position_size, size_t position, size_t position_size_ret)
	Get the position of a node in it's tree.

ccs_result_t	ccs_tree_get_values (ccs_tree_t tree, size_t num_values, ccs_datum_t values, size_t num_values_ret)
	Get the values along the path leading to a node in it's tree.

ccs_result_t	ccs_tree_get_values_at_position (ccs_tree_t tree, 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 from a tree node.

ccs_result_t	ccs_tree_get_node_at_position (ccs_tree_t tree, size_t position_size, const size_t position, ccs_tree_t tree_ret)
	Get the node at a given position from a tree node.

ccs_result_t	ccs_tree_get_weight (ccs_tree_t tree, ccs_float_t *weight_ret)
	Get the weight of a tree node.

ccs_result_t	ccs_tree_set_weight (ccs_tree_t tree, ccs_float_t weight)
	Set the weight of a tree node.

ccs_result_t	ccs_tree_get_bias (ccs_tree_t tree, ccs_float_t *bias_ret)
	Get the bias of a subtree.

ccs_result_t	ccs_tree_set_bias (ccs_tree_t tree, ccs_float_t bias)
	Set the bias of a tree node.

ccs_result_t	ccs_tree_sample (ccs_tree_t tree, ccs_rng_t rng, size_t *index_ret)
	Sample the child index space of a a tree node.

ccs_result_t	ccs_tree_samples (ccs_tree_t tree, ccs_rng_t rng, size_t num_indices, size_t *indices)
	Sample the child index space of a tree node.

Detailed Description

A CCS tree object represents a node in a tree structure.

Nodes have a given arity and are associated a give datum. Nodes can be sampled for the index of one of their children, but can also return themselves. By default children are sampled according to their subtree weight. This allows uniform sampling of the whole tree by recursively sampling selected children, and stopping when a node returns itself. This behavior can be changed by modifying individual nodes weights, as well as biasing subtrees.

Function Documentation

◆ ccs_create_tree()

ccs_result_t ccs_create_tree	(	size_t	arity,
		ccs_datum_t	value,
		ccs_tree_t *	tree_ret
	)

extern

Create new tree node.

Parameters

[in]	arity	the arity of the node
[in]	value	the value associated with the node
[out]	tree_ret	a pointer to the variable that will hold the newly created tree node.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new tree node.

Remarks: This function is thread-safe

◆ ccs_tree_get_arity()

ccs_result_t ccs_tree_get_arity	(	ccs_tree_t	tree,
		size_t *	arity_ret
	)

extern

Get the arity of a tree node.

Parameters

[in]	tree
[out]	arity_ret	a pointer to the variable that will contain the arity of the node.

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

Remarks: This function is thread-safe

◆ ccs_tree_get_bias()

ccs_result_t ccs_tree_get_bias	(	ccs_tree_t	tree,
		ccs_float_t *	bias_ret
	)

extern

Get the bias of a subtree.

Parameters

[in]	tree
[out]	bias_ret	a pointer to the variable that will contain the returned bias

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

Remarks: This function is thread-safe

◆ ccs_tree_get_child()

ccs_result_t ccs_tree_get_child	(	ccs_tree_t	tree,
		size_t	index,
		ccs_tree_t *	child_ret
	)

extern

Query a tree node for the child at the given index.

Parameters

[in]	tree
[in]	index
[in]	child_ret	a pointer to the variable that will hold the returned child or NULL if the child was undefined

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_OUT_OF_BOUNDS if index is greater than tree arity; CCS_RESULT_ERROR_INVALID_VALUE if child_ret is NULL

Remarks: This function is thread-safe

◆ ccs_tree_get_children()

ccs_result_t ccs_tree_get_children	(	ccs_tree_t	tree,
		size_t	num_children,
		ccs_tree_t *	children,
		size_t *	num_children_ret
	)

extern

Query all the children of a tree node.

Parameters

[in]	tree
[in]	num_children	the size of the `children` array
[out]	children	an array of size `num_children` to hold the returned values, or NULL. If the array is too big, extra values are set to NULL. If children are undefined, NULL is returned as well
[out]	num_children_ret	a pointer to a variable that will contain the number of children that are or would be returned. Can be NULL

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_INVALID_VALUE if children is NULL and num_children is greater than 0; or if children is NULL and num_children_ret is NULL; or if children is not NULL and num_children is less than the arity of tree

Remarks: This function is thread-safe

◆ ccs_tree_get_node_at_position()

ccs_result_t ccs_tree_get_node_at_position	(	ccs_tree_t	tree,
		size_t	position_size,
		const size_t *	position,
		ccs_tree_t *	tree_ret
	)

extern

Get the node at a given position from a tree node.

Parameters

[in]	tree
[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 is not a valid CCS tree; 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; CCS_RESULT_ERROR_INVALID_TREE if one child node described by position is undefined in tree

Remarks: This function is thread-safe

◆ ccs_tree_get_parent()

ccs_result_t ccs_tree_get_parent	(	ccs_tree_t	tree,
		ccs_tree_t *	parent_ret,
		size_t *	index_ret
	)

extern

Get the parent node of a tree node.

Parameters

[in]	tree
[out]	parent_ret	a pointer to a variable that will contain the returned parent node or NULL if the node has no parent.
[out]	index_ret	a pointer to a variable that will contain the index of the node in the parent if it has a parent. Can be NULL

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

Remarks: This function is thread-safe

◆ ccs_tree_get_position()

ccs_result_t ccs_tree_get_position	(	ccs_tree_t	tree,
		size_t	position_size,
		size_t *	position,
		size_t *	position_size_ret
	)

extern

Get the position of a node in it's tree.

Parameters

[in]	tree
[in]	position_size	the size of the `position` array
[out]	position	an array of size `position_size` to hold the returned values, or NULL. If the array is too big, extra values are set to 0
[out]	position_size_ret	a pointer to a variable that will contain the number of values that are or would be returned. Can be NULL

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_INVALID_VALUE if position is NULL and position_size is greater than 0; or if position is NULL and position_size_ret is NULL; or if position_size is less than the number of values that would be returned

Remarks: This function is thread-safe

◆ ccs_tree_get_value()

ccs_result_t ccs_tree_get_value	(	ccs_tree_t	tree,
		ccs_datum_t *	value_ret
	)

extern

Get the value of a tree node.

Parameters

[in]	tree
[out]	value_ret	a pointer to the variable that will contain the value associated with the node.

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

Remarks: This function is thread-safe

◆ ccs_tree_get_values()

ccs_result_t ccs_tree_get_values	(	ccs_tree_t	tree,
		size_t	num_values,
		ccs_datum_t *	values,
		size_t *	num_values_ret
	)

extern

Get the values along the path leading to a node in it's tree.

Parameters

[in]	tree
[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
[out]	num_values_ret	a pointer to a variable that will contain the number of values that are or would be returned. Can be NULL

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_INVALID_VALUE if values is NULL and num_values is greater than 0; or if values is NULL and num_values_ret is NULL; or if num_values is less than the number of values that would be returned

Remarks: This function is thread-safe

◆ ccs_tree_get_values_at_position()

ccs_result_t ccs_tree_get_values_at_position	(	ccs_tree_t	tree,
		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 from a tree node.

Parameters

[in]	tree
[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 is not a valid CCS tree; CCS_RESULT_ERROR_OUT_OF_BOUNDS if position does not define a valid position in tree; CCS_RESULT_ERROR_INVALID_TREE if one child node described by position is undefined in tree; 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 thread-safe

◆ ccs_tree_get_weight()

ccs_result_t ccs_tree_get_weight	(	ccs_tree_t	tree,
		ccs_float_t *	weight_ret
	)

extern

Get the weight of a tree node.

Parameters

[in]	tree
[out]	weight_ret	a pointer to the variable that will contain the returned weight

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

Remarks: This function is thread-safe

◆ ccs_tree_sample()

ccs_result_t ccs_tree_sample	(	ccs_tree_t	tree,
		ccs_rng_t	rng,
		size_t *	index_ret
	)

extern

Sample the child index space of a a tree node.

If the returned index is equal to the arity, the node sampled itself. Sampling is proportional to each subtree weight and to the tree node own weight. A subtree weight is computed as the sum of each of it's subtree weights plus it's root node weight, multiplied by it's bias.

Parameters

[in]	tree
[in]	rng	the rng to use while sampling
[out]	index_ret	a pointer to the variable that will contain the returned index

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_INVALID_VALUE if index_ret is NULL; CCS_RESULT_ERROR_INVALID_DISTRIBUTION if all the weights of tree and all it's subtrees are 0

Remarks: This function is thread-safe

◆ ccs_tree_samples()

ccs_result_t ccs_tree_samples	(	ccs_tree_t	tree,
		ccs_rng_t	rng,
		size_t	num_indices,
		size_t *	indices
	)

extern

Sample the child index space of a tree node.

If the returned index is equal to the arity, the node sampled itself. Sampling is proportional to each subtree weight and to the tree node own weight. A subtree weight is computed as the sum of each of it's subtree weights plus it's root node weight, multiplied by it's bias.

Parameters

[in]	tree
[in]	rng	the rng to use while sampling
[in]	num_indices
[out]	indices	an array of `num_indices` which will hold the returned values

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; CCS_RESULT_ERROR_INVALID_VALUE if indices is NULL and num_indices is greater than 0; CCS_RESULT_ERROR_INVALID_DISTRIBUTION if all the weights of tree and all it's subtrees are 0

Remarks: This function is thread-safe if rng is only used by one thread at a time

◆ ccs_tree_set_bias()

ccs_result_t ccs_tree_set_bias	(	ccs_tree_t	tree,
		ccs_float_t	bias
	)

extern

Set the bias of a tree node.

Parameters

[in,out]	tree
[in]	bias

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree

Remarks: This function is NOT thread-safe

◆ ccs_tree_set_child()

ccs_result_t ccs_tree_set_child	(	ccs_tree_t	tree,
		size_t	index,
		ccs_tree_t	child
	)

extern

Set an unset child in a tree node at the given index.

Parameters

[in]	tree
[in]	index
[in]	child

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree; or if child is not a valid CCS tree; CCS_RESULT_ERROR_OUT_OF_BOUNDS if index is greater than tree arity; CCS_RESULT_ERROR_INVALID_VALUE if tree already has a child at index; CCS_RESULT_ERROR_INVALID_TREE if child is already a child of another node; or if child is the root of a tree space

Remarks: This function is NOT thread-safe

◆ ccs_tree_set_weight()

ccs_result_t ccs_tree_set_weight	(	ccs_tree_t	tree,
		ccs_float_t	weight
	)

extern

Set the weight of a tree node.

Parameters

[in,out]	tree
[in]	weight

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if tree is not a valid CCS tree

Remarks: This function is NOT thread-safe

Functions

Detailed Description

Function Documentation

◆ ccs_create_tree()

◆ ccs_tree_get_arity()

◆ ccs_tree_get_bias()

◆ ccs_tree_get_child()

◆ ccs_tree_get_children()

◆ ccs_tree_get_node_at_position()

◆ ccs_tree_get_parent()

◆ ccs_tree_get_position()

◆ ccs_tree_get_value()

◆ ccs_tree_get_values()

◆ ccs_tree_get_values_at_position()

◆ ccs_tree_get_weight()

◆ ccs_tree_sample()

◆ ccs_tree_samples()

◆ ccs_tree_set_bias()

◆ ccs_tree_set_child()

◆ ccs_tree_set_weight()