Template of the API for specific probability distributions (not to be included as is!) More...

#include <clProbDist.h>

Data Structures
struct	clprobdistObject
	Distribution object [device]. More...

Typedefs
typedef cl_double	vartype
	Random variable data type. More...

Functions
Functions to create and destroy distribution objects
clprobdistObject *	clprobdistCreate (DIST_PARAMS, size_t bufSize, clprobdistStatus err)
	Create a distribution object. More...

clprobdistStatus	clprobdistDestroy (clprobdistObject *dist)
	Destroy a distribution object. More...

Functions for use with a distribution object
These functions take a distribution object as their first argument. Some distribution objects contain precomputed values that can accelerate multiple evaluations of certain functions. When this is not needed, one can use the API below of functions with explicit distribution parameters, that do not require the prior creation of a distribution object.
cl_double	clprobdistDensityWithObject (const clprobdistObject dist, cl_double x, clprobdistStatus err)
	Probability density function [device]. More...

cl_double	clprobdistProbWithObject (const clprobdistObject dist, cl_int x, clprobdistStatus err)
	Probability mass function [device]. More...

cl_double	clprobdistCDFWithObject (const clprobdistObject dist, vartype x, clprobdistStatus err)
	Cumulative density function [device]. More...

cl_double	clprobdistComplCDFWithObject (const clprobdistObject dist, vartype x, clprobdistStatus err)
	Complementary CDF or reliability function [device]. More...

vartype	clprobdistInverseCDFWithObject (const clprobdistObject dist, cl_double u, clprobdistStatus err)
	Inverse cumulative density function [device]. More...

cl_double	clprobdistMeanWithObject (const clprobdistObject dist, clprobdistStatus err)
	Mean of the distribution [device]. More...

cl_double	clprobdistVarianceWithObject (const clprobdistObject dist, clprobdistStatus err)
	Variance of the distribution [device]. More...

cl_double	clprobdistStdDeviationWithObject (const clprobdistObject dist, clprobdistStatus err)
	Standard deviation of the distribution [device]. More...

clprobdistStatus	clprobdistCopyOverFromGlobal (_CLPROBDIST_< DIST >_OBJ_MEM clprobdistObject destDist, __global const clprobdistObject srcDist)
	Copy a distribution object into already allocated memory [device-only]. More...

Functions for use with explicit distribution parameters
These functions do not require a previously created distribution objects. They take the distribution parameters as their first arguments (see the description of DIST_PARAMS in Implemented distributions). They cannot take advantage of precomputed values for the distributions.
cl_double	clprobdistDensity (DIST_PARAMS, cl_double x, clprobdistStatus *err)
	Probability density function [device]. More...

cl_double	clprobdistProb (DIST_PARAMS, cl_int x, clprobdistStatus *err)
	Probability mass function [device]. More...

cl_double	clprobdistCDF (DIST_PARAMS, vartype x, clprobdistStatus *err)
	Cumulative density function [device]. More...

cl_double	clprobdistComplCDF (DIST_PARAMS, vartype x, clprobdistStatus *err)
	Complementary CDF or reliability function [device]. More...

vartype	clprobdistInverseCDF (DIST_PARAMS, cl_double u, clprobdistStatus *err)
	Inverse cumulative density function [device]. More...

cl_double	clprobdistMean (DIST_PARAMS, clprobdistStatus *err)
	Mean of the distribution [device]. More...

cl_double	clprobdistVariance (DIST_PARAMS, clprobdistStatus *err)
	Variance of the distribution [device]. More...

cl_double	clprobdistStdDeviation (DIST_PARAMS, clprobdistStatus *err)
	Standard deviation of the distribution [device]. More...

Detailed Description

Template of the API for specific probability distributions (not to be included as is!)

The function and type names in this API all start with clprobdist. In each specific implementation, prefixes to function names are expanded to a specific prefix and the generic distribution object type clprobdistObject is replaced with a specific distribution object type. Also, vartype is replaced with cl_double for continuous distributions or with cl_int for discrete distributions. For example, the generic declaration

vartype clprobdistInverseCDFWithObject(const clprobdistObject* dist, cl_double u, clprobdistStatus* err);

expands to

cl_int clprobdistPoissonInverseCDFWithObject(const clprobdistPoisson* dist, cl_double u, clprobdistStatus* err);

for the Poisson distribution, and to

cl_double clprobdistExponentialInverseCDFWithObject(const clprobdistExponential* dist, cl_double u, clprobdistStatus* err);

for the normal distribution.

The API of each distribution, except for the standard normal that has no parameter, comes in two flavors: using a distribution object or using explicit distribution parameters. Since the number of parameters and their names vary across distributions, in the generic description of the API below, the list of distribution parameters is abbreviated by DIST_PARAMS in the function signatures, and should be replaced by the appropriate list of parameters, given in Implemented distributions for each distribution.

Host and Device APIs

The functions described here are all available on the host, in all implementations, unless specified otherwise. Only some of the functions and types are also available on the device in addition to the host; they are tagged with [device]. Other functions are only available on the device; they are tagged with [device-only]. Some functions return an error code in err.

Todo:: Explain that on the device, the distribution object needs to be copied to local memory. (Is this actually faster than the cache for global read-only memory?)

Typedef Documentation

typedef cl_double vartype

Random variable data type.

Either cl_doubld or cl_int, depending on the distribution. See Implemented distributions.

Todo:: Maybe remove this. This is here to allow to document both continuous and discrete distributions together.

Function Documentation

clprobdistObject* clprobdistCreate	(	DIST_PARAMS	,
		size_t *	bufSize,
		clprobdistStatus *	err
	)

Create a distribution object.

Create a new distribution object. Since this function allocates memory for the new distribution object; clprobdistDestroy() must be called to release the allocated memory.

For each distribution type, the token DIST_PARAMS expands to a list of the probability distribution parameters specific to the type of distribution. See Implemented distributions for more details.

Parameters

[out]	bufSize	Size in bytes of the created distribution object, or `NULL`.
[out]	err	Error status variable, or `NULL`.

Returns: New distribution object.

clprobdistStatus clprobdistDestroy ( clprobdistObject * dist )

Destroy a distribution object.

Release the resources associated to a distribution object.

Parameters

[in,out] dist Distribution object.

Returns: Error status.

cl_double clprobdistDensityWithObject	(	const clprobdistObject *	dist,
		cl_double	x,
		clprobdistStatus *	err
	)

Probability density function [device].

Return \(f(x)\), the value at \(x=\)x of the probability density function associated with the distribution object dist.

This function is defined only for continuous distributions (see Implemented distributions).

Parameters

[in]	dist	Distribution object.
[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(f(x)\).

cl_double clprobdistProbWithObject	(	const clprobdistObject *	dist,
		cl_int	x,
		clprobdistStatus *	err
	)

Probability mass function [device].

Return \(p(x)\), the probability of \(x\) associated with the distribution object dist.

This function is defined only for discrete distributions (see Implemented distributions).

Parameters

[in]	dist	Distribution object.
[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(p(x)\).

cl_double clprobdistCDFWithObject	(	const clprobdistObject *	dist,
		vartype	x,
		clprobdistStatus *	err
	)

Cumulative density function [device].

Return \(F(x)\), the value at \(x=\)x of the distribution function associated with the distribution object dist.

Parameters

[in]	dist	Distribution object.
[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(F(x)\).

cl_double clprobdistComplCDFWithObject	(	const clprobdistObject *	dist,
		vartype	x,
		clprobdistStatus *	err
	)

Complementary CDF or reliability function [device].

Return \(\bar F(x)\), the value of the complementary distribution function associated with the distribution object dist.

Parameters

[in]	dist	Distribution object.
[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(\bar F(x)\).

vartype clprobdistInverseCDFWithObject	(	const clprobdistObject *	dist,
		cl_double	u,
		clprobdistStatus *	err
	)

Inverse cumulative density function [device].

Return \(F^{-1}(u)\), the value at \(u=\)u of the inverse distribution function associated with the distribution object dist. The type of the return value is cl_int for a discrete distribution of cl_double for a continuous distribution.

Parameters

[in]	dist	Distribution object.
[in]	u	Value of \(u \in [0,1]\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(F^{-1}(u)\).

cl_double clprobdistMeanWithObject	(	const clprobdistObject *	dist,
		clprobdistStatus *	err
	)

Mean of the distribution [device].

Return the mean of the distribution associated with the distribution object dist.

Parameters

[in]	dist	Distribution object.
[out]	err	Error status variable, or `NULL`.

Returns: Mean of the distribution.

cl_double clprobdistVarianceWithObject	(	const clprobdistObject *	dist,
		clprobdistStatus *	err
	)

Variance of the distribution [device].

Return the variance of the distribution associated with the distribution object dist.

Parameters

[in]	dist	Distribution object.
[out]	err	Error status variable, or `NULL`.

Returns: Variance of the distribution.

cl_double clprobdistStdDeviationWithObject	(	const clprobdistObject *	dist,
		clprobdistStatus *	err
	)

Standard deviation of the distribution [device].

Return the standard deviation of the distribution associated with the distribution object dist.

Parameters

[in]	dist	Distribution object.
[out]	err	Error status variable, or `NULL`.

Returns: Standard deviation of the distribution.

clprobdistStatus clprobdistCopyOverFromGlobal	(	_CLPROBDIST_< DIST >_OBJ_MEM clprobdistObject *	destDist,
		__global const clprobdistObject *	srcDist
	)

Copy a distribution object into already allocated memory [device-only].

Copy the distribution object srcDist located in global memory into the buffer destDist located in local or private memory. This function does not allocate memory for the distribution object, it assumes that this has already been done.

When the distribution API is configured to use distribution objects stored in global memory (the default), there is no need to copy distribution objects across memory types, since the kernel already receives them in global memory (see Device memory types). The same applies to constant memory. In such cases, this function is not defined.

Parameters

[out]	destDist	Destination buffer into which to copy (its content will be overwritten). The qualifier `_CLPROBDIST_<DIST>_OBJ_MEM`, where `<DIST>` is the uppercase distribution name, is replaced with the OpenCL keywords `__private` or `__local`, respectively.
[in]	srcDist	Distribution object to be copied.

Returns: Error status

Warning: This function is available only on the device.

cl_double clprobdistDensity	(	DIST_PARAMS	,
		cl_double	x,
		clprobdistStatus *	err
	)

Probability density function [device].

Same as clprobdistDensityWithObject(), but with explicit distribution parameters instead of distribution object.

This function is defined only for continuous distributions (see Implemented distributions).

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(f(x)\).

cl_double clprobdistProb	(	DIST_PARAMS	,
		cl_int	x,
		clprobdistStatus *	err
	)

Probability mass function [device].

Same as clprobdistProbWithObject(), but with explicit distribution parameters instead of distribution object.

This function is defined only for discrete distributions (see Implemented distributions).

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(f(x)\).

cl_double clprobdistCDF	(	DIST_PARAMS	,
		vartype	x,
		clprobdistStatus *	err
	)

Cumulative density function [device].

Same as clprobdistCDFWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(F(x)\).

cl_double clprobdistComplCDF	(	DIST_PARAMS	,
		vartype	x,
		clprobdistStatus *	err
	)

Complementary CDF or reliability function [device].

Same as clprobdistComplCDFWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[in]	x	Value of \(x\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(\bar F(x)\).

vartype clprobdistInverseCDF	(	DIST_PARAMS	,
		cl_double	u,
		clprobdistStatus *	err
	)

Inverse cumulative density function [device].

Same as clprobdistInverseCDFWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[in]	u	Value of \(u \in [0,1]\).
[out]	err	Error status variable, or `NULL`.

Returns: Value of \(F^{-1}(u)\).

cl_double clprobdistMean	(	DIST_PARAMS	,
		clprobdistStatus *	err
	)

Mean of the distribution [device].

Same as clprobdistMeanWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[out] err Error status variable, or NULL.

Returns: Mean of the distribution.

cl_double clprobdistVariance	(	DIST_PARAMS	,
		clprobdistStatus *	err
	)

Variance of the distribution [device].

Same as clprobdistVarianceWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[out] err Error status variable, or NULL.

Returns: Variance of the distribution.

cl_double clprobdistStdDeviation	(	DIST_PARAMS	,
		clprobdistStatus *	err
	)

Standard deviation of the distribution [device].

Same as clprobdistStdDeviationWithObject(), but with explicit distribution parameters instead of distribution object.

See Implemented distributions for the expansion of DIST_PARAMS.

Parameters

[out] err Error status variable, or NULL.

Returns: Standard deviation of the distribution.

Data Structures

Typedefs

Functions

Detailed Description

Host and Device APIs

Typedef Documentation

Function Documentation