C++ API

The C++ API of bob.core allows users to leverage from automatic converters for classes in bob.core.random. To use the C API, clients should first, include the header file <bob.core/random_api.h> on their compilation units and then, make sure to call once import_bob_core_random() at their module instantiation, as explained at the Python manual.

Here is a dummy C example showing how to include the header and where to call the import function:

#include <bob.blitz/capi.h>
#include <bob.core/random_api.h>

PyMODINIT_FUNC initclient(void) {

  PyObject* m Py_InitModule("client", ClientMethods);

  if (!m) return;

  // imports dependencies
  if (import_bob_blitz() < 0) {
    PyErr_Print();
    PyErr_SetString(PyExc_ImportError, "cannot import module");
    return 0;
  }

  // imports dependencies
  if (import_bob_core_random() < 0) {
    PyErr_Print();
    PyErr_SetString(PyExc_ImportError, "cannot import module");
    return 0;
  }

  return m;

}

Mersenne Twister Random Number Generator (mt19937)

This package contains bindings to boost::mt19937, which is a powerful random number generator available within the Boost C++ library.

type PyBoostMt19937Object

The pythonic object representation for a boost::mt19937 object.

typedef struct {
  PyObject_HEAD
  boost::mt19937* rng;
} PyBoostMt19937Object;

boost::mt19937* rng

A direct pointer to the boost random number generator. You can use this pointer in your C/C++ code if required.

int PyBoostMt19937_Check(PyObject* o)

Checks if the input object o is a PyBoostMt19937Object. Returns 1 if it is, and 0 otherwise.

int PyBoostMt19937_Converter(PyObject* o, PyBoostMt19937Object** a)

This function is meant to be used with PyArg_ParseTupleAndKeywords() family of functions in the Python C-API. It checks the input object to be of type PyBoostMt19937Object and sets a new reference to it (in *a) if it is the case. Returns 0 in case of failure, 1 in case of success.

PyObject* PyBoostMt19937_SimpleNew()

Creates a new instance of PyBoostMt19937Object, with the default seed. Returns a new reference.

PyObject* PyBoostMt19937_NewWithSeed(Py_ssize_t seed)

Creates a new instance of PyBoostMt19937Object, with a user given seed. Returns a new reference.

Distribution API

Together with the boost random number generator mt19937, this package provides bindings to these boost::random distributions:

• Uniform
• Normal (or Gaussian)
• Log-normal
• Gamma
• Binomial

Distributions wrap the random number generator, skewing the distribution of numbers according to their parametrization. Distributions are templated according to the scalar data types they produce. Different distributions support a different set of scalar types:

Distribution	Scalars supported
Uniform	bool, int8/16/32/64, uint8/16/32/64, float32/64
Normal	float32/64
Log-normal	float32/64
Gamma	float32/64
Binomial	float32/64 (internally using int64)

type PyBoostUniformObject

The pythonic object representation for a boost::random::uniform_* object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyUniformObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
bool	NPY_BOOL
int8	NPY_INT8
int16	NPY_INT16
int32	NPY_INT32
int64	NPY_INT64
int8	NPY_INT8
int16	NPY_INT16
int32	NPY_INT32
int64	NPY_INT64
float32	NPY_FLOAT32
float64	NPY_FLOAT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
bool	boost::random::uniform_smallint<uint8_t>
int8	boost::random::uniform_int<int8_t>
int16	boost::random::uniform_int<int16_t>
int32	boost::random::uniform_int<int32_t>
int64	boost::random::uniform_int<int64_t>
uint8	boost::random::uniform_int<uint8_t>
uint16	boost::random::uniform_int<uint16_t>
uint32	boost::random::uniform_int<uint32_t>
uint64	boost::random::uniform_int<uint64_t>
float32	boost::random::uniform_real<float>
float64	boost::random::uniform_real<double>

In order to use the distribution in your C/C++ code, you must first cast the shared pointer using boost::static_pointer_cast<D>, with D matching one of the distributions listed above, depending on the value of

type PyBoostNormalObject

The pythonic object representation for a boost::random::normal_distribution object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyUniformObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
float32	NPY_FLOAT32
float64	NPY_FLOAT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
float32	boost::random::normal_distribution<float>
float64	boost::random::normal_distribution<double>

type PyBoostLogNormalObject

The pythonic object representation for a boost::random::lognormal_distribution object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyUniformObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
float32	NPY_FLOAT32
float64	NPY_FLOAT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
float32	boost::random::lognormal_distribution<float>
float64	boost::random::lognormal_distribution<double>

type PyBoostGammaObject

The pythonic object representation for a boost::random::gamma_distribution object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyUniformObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
float32	NPY_FLOAT32
float64	NPY_FLOAT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
float32	boost::random::gamma_distribution<float>
float64	boost::random::gamma_distribution<double>

type PyBoostBinomialObject

The pythonic object representation for a boost::random::binomial_distribution object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyBinomialObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
float32	NPY_FLOAT32
float64	NPY_FLOAT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
float32	boost::random::binomial_distribution<int64_t,float>
float64	boost::random::binomial_distribution<int64_t,double>

type PyBoostDiscreteObject

The pythonic object representation for a boost::random::discrete_distribution object.

typedef struct {
  PyObject_HEAD
  int type_num;
  boost::shared_ptr<void> distro;
} PyDiscreteObject;

int type_num;

The NumPy type number of scalars produced by this distribution. Accepted values match the scalar type produced:

Scalar type	NumPy scalar type number (enumeration)
int8	NPY_INT8
int16	NPY_INT16
int32	NPY_INT32
int64	NPY_INT64
int8	NPY_INT8
int16	NPY_INT16
int32	NPY_INT32
int64	NPY_INT64

boost::shared_ptr<void> distro

A direct pointer to the boost distribution. The underlying allocated type changes with the scalar that is produced by the distribution:

Scalar type	C++ data type
int8	boost::random::uniform_int<int8_t>
int16	boost::random::uniform_int<int16_t>
int32	boost::random::uniform_int<int32_t>
int64	boost::random::uniform_int<int64_t>
uint8	boost::random::uniform_int<uint8_t>
uint16	boost::random::uniform_int<uint16_t>
uint32	boost::random::uniform_int<uint32_t>
uint64	boost::random::uniform_int<uint64_t>

int PyBoostUniform_Check(PyObject* o)

int PyBoostNormal_Check(PyObject* o)

int PyBoostLogNormal_Check(PyObject* o)

int PyBoostGamma_Check(PyObject* o)

int PyBoostBinomial_Check(PyObject* o)

int PyBoostDiscrete_Check(PyObject* o)

Checks if the input object o is a PyBoost<Distribution>Object. Returns 1 if it is, and 0 otherwise.

int PyBoostUniform_Converter(PyObject* o, PyBoostUniformObject** a)

int PyBoostNormal_Converter(PyObject* o, PyBoostNormalObject** a)

int PyBoostLogNormal_Converter(PyObject* o, PyBoostLogNormalObject** a)

int PyBoostGamma_Converter(PyObject* o, PyBoostGammaObject** a)

int PyBoostBinomial_Converter(PyObject* o, PyBoostBinomialObject** a)

int PyBoostDiscrete_Converter(PyObject* o, PyBoostDiscreteObject** a)

This function is meant to be used with PyArg_ParseTupleAndKeywords() family of functions in the Python C-API. It checks the input object to be of type PyBoost<Distribution>Object and returns a new reference to it (in *a) if it is the case. Returns 0 in case of failure, 1 in case of success.

PyObject* PyBoostUniform_SimpleNew(int type_num, PyObject* min, PyObject* max)

Creates a new instance of PyBoostUniformObject, with the input scalar establishing the minimum and the maximum of the distribution. Note that bool distributions will raise an exception if one tries to set the minimum and the maximum, since that is non-sensical.

The parameter type_num may be set to one of the supported NPY_ enumeration values (e.g. NPY_UINT16).

Warning

For integral uniform distributions the range of numbers produced is defined as [min, max]. For real-valued distributions, the range of numbers produced lies on the interval [min, max[.

PyObject* PyBoostNormal_SimpleNew(int type_num, PyObject* mean, PyObject* sigma)

PyObject* PyBoostLogNormal_SimpleNew(int type_num, PyObject* mean, PyObject* sigma)

PyObject* PyBoostGamma_SimpleNew(int type_num, PyObject* alpha, PyObject* beta)

PyObject* PyBoostBinomial_SimpleNew(int type_num, PyObject* t, PyObject* p)

PyObject* PyBoostDiscrete_SimpleNew(int type_num, PyObject* t, PyObject* p)

Depending on the distribution, which may be one of Normal, LogNormal, Gamma or Binomial, each of the parameters assume a different function:

Distribution	Parameter 1	Parameter 2
Normal	mean	sigma (standard deviation)
LogNormal	mean	sigma (standard deviation)
Gamma	alpha	beta
Binomial	t	p
Discrete	probs	None

The parameter type_num may be set to one of the supported NPY_ enumeration values (e.g. NPY_FLOAT64).