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).