distribution.h File Reference

A Distribution is the probability distribution of a random variable. More...

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

Go to the source code of this file.

Typedefs
typedef enum ccs_distribution_type_e	ccs_distribution_type_t
	A commodity type to represent CCS distribution type.
typedef enum ccs_scale_type_e	ccs_scale_type_t
	A commodity type to represent CCS scale type.

Enumerations
enum	ccs_distribution_type_e {   CCS_DISTRIBUTION_TYPE_UNIFORM , CCS_DISTRIBUTION_TYPE_NORMAL , CCS_DISTRIBUTION_TYPE_ROULETTE , CCS_DISTRIBUTION_TYPE_MIXTURE ,   CCS_DISTRIBUTION_TYPE_MULTIVARIATE , CCS_DISTRIBUTION_TYPE_MAX , CCS_DISTRIBUTION_TYPE_FORCE_32BIT = INT32_MAX }
	CCS distribution types. More...
enum	ccs_scale_type_e { CCS_SCALE_TYPE_LINEAR , CCS_SCALE_TYPE_LOGARITHMIC , CCS_SCALE_TYPE_MAX , CCS_SCALE_TYPE_FORCE_32BIT = INT32_MAX }
	CCS scale types. More...

Functions
ccs_result_t	ccs_create_normal_distribution (ccs_numeric_type_t data_type, ccs_float_t mu, ccs_float_t sigma, ccs_scale_type_t scale, ccs_numeric_t quantization, ccs_distribution_t *distribution_ret)
	Create a new normal distribution of the specified data type.
ccs_result_t	ccs_create_normal_int_distribution (ccs_float_t mu, ccs_float_t sigma, ccs_scale_type_t scale, ccs_int_t quantization, ccs_distribution_t *distribution_ret)
	Create a new normal distribution of integer values.
ccs_result_t	ccs_create_normal_float_distribution (ccs_float_t mu, ccs_float_t sigma, ccs_scale_type_t scale, ccs_float_t quantization, ccs_distribution_t *distribution_ret)
	Create a new normal distribution of floating point values.
ccs_result_t	ccs_create_uniform_distribution (ccs_numeric_type_t data_type, ccs_numeric_t lower, ccs_numeric_t upper, ccs_scale_type_t scale, ccs_numeric_t quantization, ccs_distribution_t *distribution_ret)
	Create a new uniform distribution of the specified data type.
ccs_result_t	ccs_create_uniform_int_distribution (ccs_int_t lower, ccs_int_t upper, ccs_scale_type_t scale, ccs_int_t quantization, ccs_distribution_t *distribution_ret)
	Create a new uniform distribution of integer values.
ccs_result_t	ccs_create_uniform_float_distribution (ccs_float_t lower, ccs_float_t upper, ccs_scale_type_t scale, ccs_float_t quantization, ccs_distribution_t *distribution_ret)
	Create a new uniform distribution of floating point values.
ccs_result_t	ccs_create_roulette_distribution (size_t num_areas, ccs_float_t *areas, ccs_distribution_t *distribution_ret)
	Create a new area proportional distribution of integer values.
ccs_result_t	ccs_create_mixture_distribution (size_t num_distributions, ccs_distribution_t *distributions, ccs_float_t *weights, ccs_distribution_t *distribution_ret)
	Create a new mixture distribution.
ccs_result_t	ccs_create_multivariate_distribution (size_t num_distributions, ccs_distribution_t *distributions, ccs_distribution_t *distribution_ret)
	Create a new multivariate distribution.
ccs_result_t	ccs_distribution_get_type (ccs_distribution_t distribution, ccs_distribution_type_t *type_ret)
	Get the type of a distribution.
ccs_result_t	ccs_distribution_get_dimension (ccs_distribution_t distribution, size_t *dimension_ret)
	Get the dimensionality of a distribution.
ccs_result_t	ccs_distribution_get_data_types (ccs_distribution_t distribution, ccs_numeric_type_t *data_types_ret)
	Get the data types of a distribution.
ccs_result_t	ccs_distribution_get_bounds (ccs_distribution_t distribution, ccs_interval_t *interval_ret)
	Get the bounds of a distribution.
ccs_result_t	ccs_distribution_check_oversampling (ccs_distribution_t distribution, ccs_interval_t *intervals, ccs_bool_t *oversamplings_ret)
	Check if a distribution could return values outside of the given intervals.
ccs_result_t	ccs_normal_distribution_get_properties (ccs_distribution_t distribution, ccs_float_t *mu_ret, ccs_float_t *sigma_ret, ccs_scale_type_t *scale_ret, ccs_numeric_t *quantization_ret)
	Get the properties of a normal distribution.
ccs_result_t	ccs_uniform_distribution_get_properties (ccs_distribution_t distribution, ccs_numeric_t *lower_ret, ccs_numeric_t *upper_ret, ccs_scale_type_t *scale_ret, ccs_numeric_t *quantization_ret)
	Get the properties of a uniform distribution.
ccs_result_t	ccs_roulette_distribution_get_areas (ccs_distribution_t distribution, size_t num_areas, ccs_float_t *areas, size_t *num_areas_ret)
	Get the normalized areas of a roulette distribution.
ccs_result_t	ccs_mixture_distribution_get_distributions (ccs_distribution_t distribution, size_t num_distributions, ccs_distribution_t *distributions, size_t *num_distributions_ret)
	Get the distributions contained in a mixture distribution.
ccs_result_t	ccs_mixture_distribution_get_weights (ccs_distribution_t distribution, size_t num_weights, ccs_float_t *weights, size_t *num_weights_ret)
	Get the normalized weights of a mixture distribution.
ccs_result_t	ccs_multivariate_distribution_get_distributions (ccs_distribution_t distribution, size_t num_distributions, ccs_distribution_t *distributions, size_t *num_distributions_ret)
	Get the distributions contained in a multivariate distribution.
ccs_result_t	ccs_distribution_sample (ccs_distribution_t distribution, ccs_rng_t rng, ccs_numeric_t *values)
	Get a random sample from a distribution.
ccs_result_t	ccs_distribution_samples (ccs_distribution_t distribution, ccs_rng_t rng, size_t num_samples, ccs_numeric_t *values)
	Get a collection of random samples from a distribution.
ccs_result_t	ccs_distribution_strided_samples (ccs_distribution_t distribution, ccs_rng_t rng, size_t num_samples, size_t stride, ccs_numeric_t *values)
	Get a collection of random samples from a distribution.
ccs_result_t	ccs_distribution_soa_samples (ccs_distribution_t distribution, ccs_rng_t rng, size_t num_samples, ccs_numeric_t **values)
	Get a collection of random samples from a distribution.
ccs_result_t	ccs_distribution_parameters_samples (ccs_distribution_t distribution, ccs_rng_t rng, ccs_parameter_t *parameters, size_t num_samples, ccs_datum_t *values)
	Get a collection of random parameters' samples by sampling a distribution.
ccs_result_t	ccs_distribution_parameters_sample (ccs_distribution_t distribution, ccs_rng_t rng, ccs_parameter_t *parameters, ccs_datum_t *values)
	Get a random parameters' sample by sampling a distribution.

Detailed Description

A Distribution is the probability distribution of a random variable.

CCS supports discrete and contiguous random variables. CCS also supports composing distributions to create mixture distributions or multivariate distributions. Distributions are immutable except from a reference counting and callback management point of view.

Enumeration Type Documentation

ccs_distribution_type_e

enum ccs_distribution_type_e

CCS distribution types.

Enumerator
CCS_DISTRIBUTION_TYPE_UNIFORM	A uniform distribution over floating point or integer values.
CCS_DISTRIBUTION_TYPE_NORMAL	A normal distribution over floating point or integer values.
CCS_DISTRIBUTION_TYPE_ROULETTE	A roulette wheel selection distribution.
CCS_DISTRIBUTION_TYPE_MIXTURE	A mixture distribution.
CCS_DISTRIBUTION_TYPE_MULTIVARIATE	A multivariate distribution.
CCS_DISTRIBUTION_TYPE_MAX	Guard.
CCS_DISTRIBUTION_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

ccs_scale_type_e

enum ccs_scale_type_e

CCS scale types.

Enumerator
CCS_SCALE_TYPE_LINEAR	A linear scale.
CCS_SCALE_TYPE_LOGARITHMIC	A logarithmic scale.
CCS_SCALE_TYPE_MAX	Guard.
CCS_SCALE_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

Function Documentation

ccs_create_mixture_distribution()

ccs_result_t ccs_create_mixture_distribution ( size_t  num_distributions, ccs_distribution_t *  distributions, ccs_float_t *  weights, ccs_distribution_t *  distribution_ret  )

extern

Create a new mixture distribution.

Mixture distributions have the same dimensionality as the distributions they are mixing.

Parameters

[in]	num_distributions	the number of distribution to mix together
[in]	distributions	an array of num_distributions distributions to mix together
[in]	weights	an array of num_distributions positive floating point values representing the probability of sampling from one of the given distributions
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if num_distributions is 0; or if distributions is NULL; or if weights is NULL; or if the sum of the weight is 0; or if the weights could not be normalized

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if the distributions have different dimensions; or if distributions do not all have the same data types

CCS_RESULT_ERROR_INVALID_OBJECT if at least one of the distributions is not a valid CCS distributions

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_multivariate_distribution()

ccs_result_t ccs_create_multivariate_distribution ( size_t  num_distributions, ccs_distribution_t *  distributions, ccs_distribution_t *  distribution_ret  )

extern

Create a new multivariate distribution.

Multivariate distributions have a dimensionality equal to the sum of the dimensionality of their component distributions.

Parameters

[in]	num_distributions	the number of distributions to compose
[in]	distributions	an array of num_distributions distributions to compose
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if num_distributions is 0; or if distributions is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if at least one of the distributions is not a valid CCS distributions

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_normal_distribution()

ccs_result_t ccs_create_normal_distribution ( ccs_numeric_type_t  data_type, ccs_float_t  mu, ccs_float_t  sigma, ccs_scale_type_t  scale, ccs_numeric_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new normal distribution of the specified data type.

Normal distributions are unidimensional.

Parameters

[in]	data_type	can be either CCS_NUMERIC_TYPE_INT or CCS_NUMERIC_TYPE_FLOAT
[in]	mu	mean of the distribution
[in]	sigma	standard deviation of the distribution
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization. Must be a ccs_int_t if data_type is CCS_NUMERIC_TYPE_INT or a ccs_float_t if data_type is CCS_NUMERIC_TYPE_FLOAT
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0

CCS_RESULT_ERROR_INVALID_TYPE if data_type is neither CCS_NUMERIC_TYPE_INT nor CCS_NUMERIC_TYPE_FLOAT

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_normal_float_distribution()

ccs_result_t ccs_create_normal_float_distribution ( ccs_float_t  mu, ccs_float_t  sigma, ccs_scale_type_t  scale, ccs_float_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new normal distribution of floating point values.

Normal distributions are unidimensional.

Parameters

[in]	mu	mean of the distribution
[in]	sigma	standard deviation of the distribution
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization.
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_normal_int_distribution()

ccs_result_t ccs_create_normal_int_distribution ( ccs_float_t  mu, ccs_float_t  sigma, ccs_scale_type_t  scale, ccs_int_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new normal distribution of integer values.

Normal distributions are unidimensional.

Parameters

[in]	mu	mean of the distribution
[in]	sigma	standard deviation of the distribution
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization.
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_roulette_distribution()

ccs_result_t ccs_create_roulette_distribution ( size_t  num_areas, ccs_float_t *  areas, ccs_distribution_t *  distribution_ret  )

extern

Create a new area proportional distribution of integer values.

Roulette distributions are unidimensional.

Parameters

[in]	num_areas	the number of areas
[in]	areas	an array of num_areas positive floating point values representing the probability of a given area to be sampled.
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if areas is NULL; or if the sum of the areas is 0; or if the areas could not be normalized

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_uniform_distribution()

ccs_result_t ccs_create_uniform_distribution ( ccs_numeric_type_t  data_type, ccs_numeric_t  lower, ccs_numeric_t  upper, ccs_scale_type_t  scale, ccs_numeric_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new uniform distribution of the specified data type.

Uniform distributions are unidimensional.

Parameters

[in]	data_type	can be either CCS_NUMERIC_TYPE_INT or CCS_NUMERIC_TYPE_FLOAT
[in]	lower	the lower bound of the distribution, included. Must be a ccs_int_t if data_type is CCS_NUMERIC_TYPE_INT or a ccs_float_t if data_type is CCS_NUMERIC_TYPE_FLOAT
[in]	upper	the upper bound of the distribution, excluded. Must be a ccs_int_t if data_type is CCS_NUMERIC_TYPE_INT or a ccs_float_t if data_type is CCS_NUMERIC_TYPE_FLOAT
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization. Must be a ccs_int_t if data_type is CCS_NUMERIC_TYPE_INT or a ccs_float_t if data_type is CCS_NUMERIC_TYPE_FLOAT
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0; or if the range defined by lower and upper is empty or smaller than the quantization; or if scale is CCS_SCALE_TYPE_LOGARITHMIC lower is less or equal to 0

CCS_RESULT_ERROR_INVALID_TYPE if data_type is neither CCS_NUMERIC_TYPE_INT nor CCS_NUMERIC_TYPE_FLOAT

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_uniform_float_distribution()

ccs_result_t ccs_create_uniform_float_distribution ( ccs_float_t  lower, ccs_float_t  upper, ccs_scale_type_t  scale, ccs_float_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new uniform distribution of floating point values.

Uniform distributions are unidimensional.

Parameters

[in]	lower	the lower bound of the distribution, included.
[in]	upper	the upper bound of the distribution, excluded.
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization.
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0; or if the range defined by lower and upper is empty or smaller than the quantization; or if scale is CCS_SCALE_TYPE_LOGARITHMIC lower is less or equal to 0

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_create_uniform_int_distribution()

ccs_result_t ccs_create_uniform_int_distribution ( ccs_int_t  lower, ccs_int_t  upper, ccs_scale_type_t  scale, ccs_int_t  quantization, ccs_distribution_t *  distribution_ret  )

extern

Create a new uniform distribution of integer values.

Uniform distributions are unidimensional.

Parameters

[in]	lower	the lower bound of the distribution, included.
[in]	upper	the upper bound of the distribution, excluded.
[in]	scale	can be either CCS_SCALE_TYPE_LINEAR or CCS_SCALE_TYPE_LOGARITHMIC
[in]	quantization	quantization of the results, 0 means no quantization.
[out]	distribution_ret	a pointer to the variable that will contain the newly created distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL; or if quantization is less than 0; or if the range defined by lower and upper is empty or smaller than the quantization; or if scale is CCS_SCALE_TYPE_LOGARITHMIC lower is less or equal to 0

CCS_RESULT_ERROR_INVALID_SCALE if scale is neither CCS_SCALE_TYPE_LINEAR nor CCS_SCALE_TYPE_LOGARITHMIC

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new distribution

Remarks

This function is thread-safe

ccs_distribution_check_oversampling()

ccs_result_t ccs_distribution_check_oversampling ( ccs_distribution_t  distribution, ccs_interval_t *  intervals, ccs_bool_t *  oversamplings_ret  )

extern

Check if a distribution could return values outside of the given intervals.

Parameters

[in]	distribution
[in]	intervals	an array of intervals of the same dimension as the distribution
[out]	oversamplings_ret	an array of boolean values of the same dimension as the distribution, that contain the result of the oversampling test for each dimension

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if intervals is NULL; or if oversamplings_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

Remarks

This function is thread-safe

ccs_distribution_get_bounds()

ccs_result_t ccs_distribution_get_bounds ( ccs_distribution_t  distribution, ccs_interval_t *  interval_ret  )

extern

Get the bounds of a distribution.

Bounds are intervals that should contain all possible values returned by a distribution's dimension.

Parameters

[in]	distribution
[out]	interval_ret	an array of intervals of the same dimension as the distribution, that will contain the possible intervals of each dimension of the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if interval_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

Remarks

This function is thread-safe

ccs_distribution_get_data_types()

ccs_result_t ccs_distribution_get_data_types ( ccs_distribution_t  distribution, ccs_numeric_type_t *  data_types_ret  )

extern

Get the data types of a distribution.

Parameters

[in]	distribution
[out]	data_types_ret	an array of numeric types of the same dimension as the distribution, that will contain the data types of each dimension of the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if data_types_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

Remarks

This function is thread-safe

ccs_distribution_get_dimension()

ccs_result_t ccs_distribution_get_dimension ( ccs_distribution_t  distribution, size_t *  dimension_ret  )

extern

Get the dimensionality of a distribution.

Parameters

[in]	distribution
[out]	dimension_ret	a pointer to the variable that will contain the dimension of the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if dimension_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

Remarks

This function is thread-safe

ccs_distribution_get_type()

ccs_result_t ccs_distribution_get_type ( ccs_distribution_t  distribution, ccs_distribution_type_t *  type_ret  )

extern

Get the type of a distribution.

Parameters

[in]	distribution
[out]	type_ret	a pointer to the variable that will contain the type of the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if type_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

Remarks

This function is thread-safe

ccs_distribution_parameters_sample()

ccs_result_t ccs_distribution_parameters_sample ( ccs_distribution_t  distribution, ccs_rng_t  rng, ccs_parameter_t *  parameters, ccs_datum_t *  values  )

extern

Get a random parameters' sample by sampling a distribution.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[in]	parameters	an array of parameters. The dimension of the array must be equal to the dimension of the distribution
[out]	values	an array of datum of the same dimension as the distribution. Will contain the sampled values.

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL; or if parameters is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng; or if at least one of the parameters provided is NULL

Remarks

This function is thread-safe

ccs_distribution_parameters_samples()

ccs_result_t ccs_distribution_parameters_samples ( ccs_distribution_t  distribution, ccs_rng_t  rng, ccs_parameter_t *  parameters, size_t  num_samples, ccs_datum_t *  values  )

extern

Get a collection of random parameters' samples by sampling a distribution.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[in]	parameters	an array of parameters. The dimension of the array must be equal to the dimension of the distribution
[in]	num_samples	the number of samples to get
[out]	values	an array of datum values. The dimension of the array should be the dimension of the distribution times num_samples. Values will be in an array of structures ordering, so values from a single sample will be contiguous in memory

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL and num_samples is greater than 0; or if parameters is NULL and num_samples is greater than 0

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng; or if at least one of the parameters provided is NULL

Remarks

This function is thread-safe

ccs_distribution_sample()

ccs_result_t ccs_distribution_sample ( ccs_distribution_t  distribution, ccs_rng_t  rng, ccs_numeric_t *  values  )

extern

Get a random sample from a distribution.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[out]	values	an array of numeric values the same dimension as the distribution. Will contain the sampled values. The type of the numeric returned depends on the data type of each dimension (see ccs_distribution_get_data_types)

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng

Remarks

This function is thread-safe

ccs_distribution_samples()

ccs_result_t ccs_distribution_samples ( ccs_distribution_t  distribution, ccs_rng_t  rng, size_t  num_samples, ccs_numeric_t *  values  )

extern

Get a collection of random samples from a distribution.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[in]	num_samples	the number of samples to get
[out]	values	an array of numeric values. The dimension of the array should be the dimension of the distribution times num_samples. Values will be in an array of structures ordering, so values from a single sample will be contiguous in memory

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL and num_samples is greater than 0

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng

Remarks

This function is thread-safe

ccs_distribution_soa_samples()

ccs_result_t ccs_distribution_soa_samples ( ccs_distribution_t  distribution, ccs_rng_t  rng, size_t  num_samples, ccs_numeric_t **  values  )

extern

Get a collection of random samples from a distribution.

Each sample components will be stored contiguously in it's own array.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[in]	num_samples	the number of samples to get
[out]	values	an array of arrays of numeric values. The array dimension is the dimension of the distribution, while the contained arrays have a dimension of num_samples. If a value inside the array is NULL this dimension is ignored.

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng

Remarks

This function is thread-safe

ccs_distribution_strided_samples()

ccs_result_t ccs_distribution_strided_samples ( ccs_distribution_t  distribution, ccs_rng_t  rng, size_t  num_samples, size_t  stride, ccs_numeric_t *  values  )

extern

Get a collection of random samples from a distribution.

Each sample is stride ccs_numeric_t element apart in memory. A stride equal to the the distribution dimension is equivalent to calling ccs_distribution_samples.

Parameters

[in]	distribution
[in,out]	rng	the random number generator to use
[in]	num_samples	the number of samples to get
[in]	stride	the distance in memory that will separate two samples successive samples. The value is given in number of ccs_numeric_t
[out]	values	an array of numeric values. The dimension of the array should be the stride times num_samples minus stride plus the dimension of the distribution. Values will be in an array of structures ordering, so values from a single sample will be contiguous in memory

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL and num_samples is greater than 0; or if stride is less than the distribution dimension

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution; or if rng is not a valid CCS rng

Remarks

This function is thread-safe

ccs_mixture_distribution_get_distributions()

ccs_result_t ccs_mixture_distribution_get_distributions ( ccs_distribution_t  distribution, size_t  num_distributions, ccs_distribution_t *  distributions, size_t *  num_distributions_ret  )

extern

Get the distributions contained in a mixture distribution.

Parameters

[in]	distribution
[in]	num_distributions	the number of distributions that can be contained in distributions. If distributions is not NULL, num_distributions must be greater than 0
[out]	distributions	an array of distributions that will contain the returned distributions, or NULL. If the array is too big, extra values are set to NULL
[out]	num_distributions_ret	a pointer to a variable that will contain the number of distributions that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distributions is NULL and num_distributions is greater than 0; or if distributions is NULL and num_distributions_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a mixture distribution

Remarks

This function is thread-safe

ccs_mixture_distribution_get_weights()

ccs_result_t ccs_mixture_distribution_get_weights ( ccs_distribution_t  distribution, size_t  num_weights, ccs_float_t *  weights, size_t *  num_weights_ret  )

extern

Get the normalized weights of a mixture distribution.

Parameters

[in]	distribution
[in]	num_weights	the number of weight that can be contained in weights. If weights is not NULL, num_weights must be greater than 0
[out]	weights	an array of num_weights floating point values that will contain the weights of the distributions, or NULL. If the array is too big, extra values are set to 0
[out]	num_weights_ret	a pointer to a variable that will contain the number of weights that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if weights is NULL and num_weights is greater than 0; or if weights is NULL and num_weights_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a mixture distribution

Remarks

This function is thread-safe

ccs_multivariate_distribution_get_distributions()

ccs_result_t ccs_multivariate_distribution_get_distributions ( ccs_distribution_t  distribution, size_t  num_distributions, ccs_distribution_t *  distributions, size_t *  num_distributions_ret  )

extern

Get the distributions contained in a multivariate distribution.

Parameters

[in]	distribution
[in]	num_distributions	the number of distributions that can be contained in distributions. If distributions is not NULL, num_distributions must be greater than 0
[out]	distributions	an array of distributions that will contain the returned distributions, or NULL. If the array is too big, extra values are set to NULL
[out]	num_distributions_ret	a pointer to a variable that will contain the number of distributions that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if distributions is NULL and num_distributions is greater than 0; or if distributions is NULL and num_distributions_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a multivariate distribution

Remarks

This function is thread-safe

ccs_normal_distribution_get_properties()

ccs_result_t ccs_normal_distribution_get_properties ( ccs_distribution_t  distribution, ccs_float_t *  mu_ret, ccs_float_t *  sigma_ret, ccs_scale_type_t *  scale_ret, ccs_numeric_t *  quantization_ret  )

extern

Get the properties of a normal distribution.

Parameters

[in]	distribution
[out]	mu_ret	an optional pointer to the variable that will contain the mean of the distribution
[out]	sigma_ret	an optional pointer to the variable that will contain the standard deviation of the distribution
[out]	scale_ret	an optional pointer to the variable that will contain the scale used by the distribution
[out]	quantization_ret	an optional pointer to the variable that will contain the quantization used by the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if mu_ret is NULL and sigma_ret is NULL and scale_ret is NULL and quantization_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a normal distribution

Remarks

This function is thread-safe

ccs_roulette_distribution_get_areas()

ccs_result_t ccs_roulette_distribution_get_areas ( ccs_distribution_t  distribution, size_t  num_areas, ccs_float_t *  areas, size_t *  num_areas_ret  )

extern

Get the normalized areas of a roulette distribution.

Parameters

[in]	distribution
[in]	num_areas	the number of area that can be contained in areas. If areas is not NULL, num_areas must be greater than 0
[out]	areas	an array of num_areas floating point values that will contain the areas of the distributions, or NULL. If the array is too big, extra values are set to 0
[out]	num_areas_ret	a pointer to a variable that will contain the number of areas that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if areas is NULL and num_areas is greater than 0; or if areas is NULL and num_areas_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a roulette distribution

Remarks

This function is thread-safe

ccs_uniform_distribution_get_properties()

ccs_result_t ccs_uniform_distribution_get_properties ( ccs_distribution_t  distribution, ccs_numeric_t *  lower_ret, ccs_numeric_t *  upper_ret, ccs_scale_type_t *  scale_ret, ccs_numeric_t *  quantization_ret  )

extern

Get the properties of a uniform distribution.

Parameters

[in]	distribution
[out]	lower_ret	an optional pointer to the variable that will contain the lower bound of the distribution
[out]	upper_ret	an optional pointer to the variable that will contain the upper bound of the distribution
[out]	scale_ret	an optional pointer to the variable that will contain the scale used by the distribution
[out]	quantization_ret	an optional pointer to the variable that will contain the quantization used by the distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if lower_ret is NULL and upper_ret is NULL and scale_ret is NULL and quantization_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS distribution

CCS_RESULT_ERROR_INVALID_DISTRIBUTION if distribution is not a uniform distribution

Remarks

This function is thread-safe