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::shared_ptr<boost::mt19937> rng;
} PyBoostMt19937Object;
boost::shared_ptr<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 *PyBoostBinomial_SimpleNew(int type_num, PyObject *t, PyObject *p)
PyObject *PyBoostDiscrete_SimpleNew(int type_num, PyObject *probs)

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

Distribution

Parameter 1

Parameter 2

Normal

mean

sigma

LogNormal

mean

sigma

Gamma

alpha

Binomial

t

p

Discrete

probs

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