Расширение#
The BitGeneratorбыли разработаны для расширения с использованием стандартных инструментов для высокопроизводительного Python — numba и Cython. Generator объект также может использоваться с предоставленными пользователем BitGenerators, пока они экспортируют небольшой набор требуемых функций.
Numba#
Numba можно использовать с
CTypes
или CFFI. Текущая итерация
BitGeneratorвсе экспортируют небольшой набор функций через оба интерфейса.
Этот пример показывает, как Numba может использоваться для генерации гауссовских выборок с использованием чистой реализации на Python, которая затем компилируется. Случайные числа предоставляются ctypes.next_double.
from timeit import timeit
import numba as nb
import numpy as np
from numpy.random import PCG64
bit_gen = PCG64()
next_d = bit_gen.cffi.next_double
state_addr = bit_gen.cffi.state_address
def normals(n, state):
out = np.empty(n)
for i in range((n + 1) // 2):
x1 = 2.0 * next_d(state) - 1.0
x2 = 2.0 * next_d(state) - 1.0
r2 = x1 * x1 + x2 * x2
while r2 >= 1.0 or r2 == 0.0:
x1 = 2.0 * next_d(state) - 1.0
x2 = 2.0 * next_d(state) - 1.0
r2 = x1 * x1 + x2 * x2
f = np.sqrt(-2.0 * np.log(r2) / r2)
out[2 * i] = f * x1
if 2 * i + 1 < n:
out[2 * i + 1] = f * x2
return out
# Compile using Numba
normalsj = nb.jit(normals, nopython=True)
# Must use state address not state with numba
n = 10000
def numbacall():
return normalsj(n, state_addr)
rg = np.random.Generator(PCG64())
def numpycall():
return rg.normal(size=n)
# Check that the functions work
r1 = numbacall()
r2 = numpycall()
assert r1.shape == (n,)
assert r1.shape == r2.shape
t1 = timeit(numbacall, number=1000)
print(f'{t1:.2f} secs for {n} PCG64 (Numba/PCG64) gaussian randoms')
t2 = timeit(numpycall, number=1000)
print(f'{t2:.2f} secs for {n} PCG64 (NumPy/PCG64) gaussian randoms')
И CTypes, и CFFI позволяют использовать более сложные распределения
непосредственно в Numba после компиляции файла distributions.c в DLL или
soПример, показывающий использование более сложного распределения, находится в Примеры раздел ниже.
Cython#
Cython можно использовать для распаковки PyCapsule предоставленный BitGenerator.
Этот пример использует PCG64 и пример выше. Обычные предостережения для написания высокопроизводительного кода с использованием Cython – удаление проверок границ и обертывания, предоставление информации о выравнивании массивов – всё ещё применяются.
#cython: language_level=3
"""
This file shows how the to use a BitGenerator to create a distribution.
"""
import numpy as np
cimport numpy as np
cimport cython
from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
from libc.stdint cimport uint16_t, uint64_t
from numpy.random cimport bitgen_t
from numpy.random import PCG64
from numpy.random.c_distributions cimport (
random_standard_uniform_fill, random_standard_uniform_fill_f)
np.import_array()
@cython.boundscheck(False)
@cython.wraparound(False)
def uniforms(Py_ssize_t n):
"""
Create an array of `n` uniformly distributed doubles.
A 'real' distribution would want to process the values into
some non-uniform distribution
"""
cdef Py_ssize_t i
cdef bitgen_t *rng
cdef const char *capsule_name = "BitGenerator"
cdef double[::1] random_values
x = PCG64()
capsule = x.capsule
# Optional check that the capsule if from a BitGenerator
if not PyCapsule_IsValid(capsule, capsule_name):
raise ValueError("Invalid pointer to anon_func_state")
# Cast the pointer
rng = <bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
random_values = np.empty(n, dtype='float64')
with x.lock, nogil:
for i in range(n):
# Call the function
random_values[i] = rng.next_double(rng.state)
randoms = np.asarray(random_values)
return randoms
The BitGenerator также может быть напрямую доступен с использованием членов bitgen_t
struct.
@cython.boundscheck(False)
@cython.wraparound(False)
def uint10_uniforms(Py_ssize_t n):
"""Uniform 10 bit integers stored as 16-bit unsigned integers"""
cdef Py_ssize_t i
cdef bitgen_t *rng
cdef const char *capsule_name = "BitGenerator"
cdef uint16_t[::1] random_values
cdef int bits_remaining
cdef int width = 10
cdef uint64_t buff, mask = 0x3FF
x = PCG64()
capsule = x.capsule
if not PyCapsule_IsValid(capsule, capsule_name):
raise ValueError("Invalid pointer to anon_func_state")
rng = <bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
random_values = np.empty(n, dtype='uint16')
# Best practice is to release GIL and acquire the lock
bits_remaining = 0
with x.lock, nogil:
for i in range(n):
if bits_remaining < width:
buff = rng.next_uint64(rng.state)
random_values[i] = buff & mask
buff >>= width
randoms = np.asarray(random_values)
return randoms
Cython можно использовать для прямого доступа к функциям в
numpy/random/c_distributions.pxd. Это требует линковки с
npyrandom библиотека, расположенная в numpy/random/lib.
def uniforms_ex(bit_generator, Py_ssize_t n, dtype=np.float64):
"""
Create an array of `n` uniformly distributed doubles via a "fill" function.
A 'real' distribution would want to process the values into
some non-uniform distribution
Parameters
----------
bit_generator: BitGenerator instance
n: int
Output vector length
dtype: {str, dtype}, optional
Desired dtype, either 'd' (or 'float64') or 'f' (or 'float32'). The
default dtype value is 'd'
"""
cdef bitgen_t *rng
cdef const char *capsule_name = "BitGenerator"
cdef np.ndarray randoms
capsule = bit_generator.capsule
# Optional check that the capsule if from a BitGenerator
if not PyCapsule_IsValid(capsule, capsule_name):
raise ValueError("Invalid pointer to anon_func_state")
# Cast the pointer
rng = <bitgen_t *> PyCapsule_GetPointer(capsule, capsule_name)
_dtype = np.dtype(dtype)
randoms = np.empty(n, dtype=_dtype)
if _dtype == np.float32:
with bit_generator.lock:
random_standard_uniform_fill_f(rng, n, <float*>np.PyArray_DATA(randoms))
elif _dtype == np.float64:
with bit_generator.lock:
random_standard_uniform_fill(rng, n, <double*>np.PyArray_DATA(randoms))
else:
raise TypeError('Unsupported dtype %r for random' % _dtype)
return randoms
См. Расширение numpy.random через Cython для полных списков этих примеров
и минимального setup.py для сборки c-расширений модулей.
CFFI#
CFFI может использоваться для прямого доступа к функциям в
include/numpy/random/distributions.h. Некоторая «обработка» заголовочного файла требуется:
"""
Use cffi to access any of the underlying C functions from distributions.h
"""
import os
import cffi
import numpy as np
from .parse import parse_distributions_h
ffi = cffi.FFI()
inc_dir = os.path.join(np.get_include(), 'numpy')
# Basic numpy types
ffi.cdef('''
typedef intptr_t npy_intp;
typedef unsigned char npy_bool;
''')
parse_distributions_h(ffi, inc_dir)
После того как заголовок разобран ffi.cdef, функции могут быть доступны непосредственно из _generator разделяемый объект, используя BitGenerator.cffi интерфейс.
lib = ffi.dlopen(np.random._generator.__file__)
# Compare the distributions.h random_standard_normal_fill to
# Generator.standard_random
bit_gen = np.random.PCG64()
rng = np.random.Generator(bit_gen)
state = bit_gen.state
interface = rng.bit_generator.cffi
n = 100
vals_cffi = ffi.new('double[%d]' % n)
lib.random_standard_normal_fill(interface.bit_generator, n, vals_cffi)
# reset the state
bit_gen.state = state
vals = rng.standard_normal(n)
for i in range(n):
assert vals[i] == vals_cffi[i]
Новые генераторы битов#
Generator может использоваться с предоставленными пользователем BitGenerators. Самый простой способ написать новый BitGenerator это изучить pyx файл одного из существующих BitGenerators. Ключевая структура, которая должна быть предоставлена, это
capsule который содержит PyCapsule в указатель на структуру типа
bitgen_t,
typedef struct bitgen {
void *state;
uint64_t (*next_uint64)(void *st);
uint32_t (*next_uint32)(void *st);
double (*next_double)(void *st);
uint64_t (*next_raw)(void *st);
} bitgen_t;
который предоставляет 5 указателей. Первый — это непрозрачный указатель на структуру данных, используемую BitGenerators. Следующие три являются указателями на функции, которые
возвращают следующие 64- и 32-битные беззнаковые целые числа, следующее случайное число с плавающей точкой и
следующее необработанное значение. Эта последняя функция используется для тестирования и поэтому может быть установлена
в функцию следующего 64-битного беззнакового целого числа, если не нужна. Функции внутри
Generator использовать эту структуру как в
bitgen_state->next_uint64(bitgen_state->state)