NumPy ядровые библиотеки

Новая в версии 1.3.0.

Начиная с numpy 1.3.0, мы работаем над разделением чистого C-кода, «вычислений», от зависимого от Python кода. Цель состоит в двух аспектах: сделать код более чистым и позволить повторное использование кода другими расширениями за пределами numpy (scipy и т.д.).

NumPy ядровая математическая библиотека

Библиотека NumPy ядровых математических функций (‘npymath’) является первым шагом в этом направлении. Эта библиотека содержит большую часть математической функциональности C99, которая может использоваться на платформах, где C99 не поддерживается должным образом. Ядровые математические функции имеют тот же API, что и C99, за исключением префикса npy_.

Доступные функции определены в <numpy/npy_math.h> — пожалуйста, обратитесь к этому заголовочному файлу при возникновении сомнений.

Классификация чисел с плавающей точкой

NPY_NAN: Эта макрос определен для NaN (Not a Number), и гарантированно имеет сброшенный бит знака (‘положительное’ NaN). Соответствующие макросы одинарной и расширенной точности доступны с суффиксом F и L.

NPY_INFINITY: Эта макрос определен для положительной бесконечности. Соответствующие макросы одинарной и расширенной точности доступны с суффиксом F и L.

NPY_PZERO: Этот макрос определен для положительного нуля. Соответствующие макросы одинарной и расширенной точности доступны с суффиксом F и L.

NPY_NZERO: Этот макрос определен для отрицательного нуля (то есть с установленным битом знака). Соответствующие макросы одинарной и расширенной точности доступны с суффиксом F и L.

int npy_isnan(x): Это макрос, эквивалентный C99 isnan: работает для одинарной, двойной и расширенной точности и возвращает ненулевое значение, если x — NaN.

int npy_isfinite(x): Это макрос, эквивалентный C99 isfinite: работает для одинарной, двойной и расширенной точности и возвращает ненулевое значение, если x — не NaN и не бесконечность.

int npy_isinf(x): Это макрос, эквивалентный C99 isinf: работает для одинарной, двойной и расширенной точности и возвращает ненулевое значение, если x — бесконечность (положительная и отрицательная).

int npy_signbit(x): Это макрос, эквивалентный C99 signbit: работает для одинарной, двойной и расширенной точности и возвращает ненулевое значение, если x имеет установленный бит знака (то есть число отрицательное).

double npy_copysign(double x, double y): Эта функция эквивалентна C99 copysign: возвращает x с тем же знаком, что и y. Работает для любых значений, включая inf и nan. Одинарная и расширенная точности доступны с суффиксами f и l.

Новая в версии 1.4.0.

Полезные математические константы

Следующие математические константы доступны в npy_math.h. Одинарная и расширенная точности также доступны путем добавления суффиксов f и l соответственно.

NPY_E: Основание натурального логарифма ( $e$ )

NPY_LOG2E: Логарифм по основанию 2 от постоянной Эйлера ( $\frac{\ln(e)}{\ln(2)}$ )

NPY_LOG10E: Логарифм по основанию 10 от постоянной Эйлера ( $\frac{\ln(e)}{\ln(10)}$ )

NPY_LOGE2: Натуральный логарифм 2 ( $\ln(2)$ )

NPY_LOGE10: Натуральный логарифм 10 ( $\ln(10)$ )

NPY_PI: Пи ( $\pi$ )

NPY_PI_2: Пи, делённое на 2 ( $\frac{\pi}{2}$ )

NPY_PI_4: Пи, делённое на 4 ( $\frac{\pi}{4}$ )

NPY_1_PI: Обратная величина пи ( $\frac{1}{\pi}$ )

NPY_2_PI: Дважды обратная величина пи ( $\frac{2}{\pi}$ )

NPY_EULER

Постоянная Эйлера: $\lim_{n\rightarrow\infty}({\sum_{k=1}^n{\frac{1}{k}}-\ln n})$

Низкоуровневая обработка чисел с плавающей точкой

Эти функции могут быть полезны для точного сравнения чисел с плавающей точкой.

double npy_nextafter(double x, double y): Эта функция эквивалентна C99 nextafter: возвращает следующее представимое значение числа с плавающей точкой от x в направлении y. Одинарная и расширенная точности доступны с суффиксами f и l.

Новая в версии 1.4.0.

double npy_spacing(double x): Эта функция эквивалентна Фортрановской встроенной функции. Возвращает расстояние между x и следующим представимым значением числа с плавающей точкой от x, например, spacing(1) == eps. Для NaN и +/- inf возвращает NaN. Одинарная и расширенная точности доступны с суффиксами f и l.

Новая в версии 1.4.0.

void npy_set_floatstatus_divbyzero(): Установить исключение деления на ноль для чисел с плавающей точкой

Новая в версии 1.6.0.

void npy_set_floatstatus_overflow(): Установить исключение переполнения для чисел с плавающей точкой

Новая в версии 1.6.0.

void npy_set_floatstatus_underflow(): Установить исключение подпорогового значения для чисел с плавающей точкой

Новая в версии 1.6.0.

void npy_set_floatstatus_invalid(): Установить исключение недействительности для чисел с плавающей точкой

Новая в версии 1.6.0.

int npy_get_floatstatus()

Получить состояние чисел с плавающей точкой. Возвращает битовую маску с возможными флагами:

NPY_FPE_DIVIDEBYZERO
NPY_FPE_OVERFLOW
NPY_FPE_UNDERFLOW
NPY_FPE_INVALID

Обратите внимание, что npy_get_floatstatus_barrier предпочтительнее, поскольку предотвращает агрессивную оптимизацию компилятора, которая может переупорядочить вызов относительно кода, устанавливающего состояние, что может привести к неверным результатам.

Новая в версии 1.9.0.

int npy_get_floatstatus_barrier(char*)

Получить состояние чисел с плавающей точкой. Указатель на локальную переменную передаётся, чтобы предотвратить агрессивную оптимизацию компилятора, которая может переупорядочить этот вызов относительно кода, устанавливающего состояние, что может привести к неверным результатам.

Возвращает битовую маску с возможными флагами:

NPY_FPE_DIVIDEBYZERO
NPY_FPE_OVERFLOW
NPY_FPE_UNDERFLOW
NPY_FPE_INVALID

Новая в версии 1.15.0.

int npy_clear_floatstatus()

Очищает состояние чисел с плавающей точкой. Возвращает предыдущую маску состояния.

Обратите внимание, что npy_clear_floatstatus_barrier предпочтительнее, поскольку предотвращает агрессивную оптимизацию компилятора, которая может переупорядочить вызов относительно кода, устанавливающего состояние, что может привести к неверным результатам.

Новая в версии 1.9.0.

int npy_clear_floatstatus_barrier(char*): Очищает состояние чисел с плавающей точкой. Указатель на локальную переменную передаётся, чтобы предотвратить агрессивную оптимизацию компилятора. Возвращает предыдущую маску состояния.

Новая в версии 1.15.0.

Комплексные функции

Новая в версии 1.4.0.

Были добавлены комплексные функции в стиле C99. Их можно использовать, если вы хотите реализовать переносимые C-расширения. Поскольку мы по-прежнему поддерживаем платформы без типа комплексных чисел C99, вам необходимо ограничиться синтаксисом, совместимым с C90, например:

/* a = 1 + 2i \*/
npy_complex a = npy_cpack(1, 2);
npy_complex b;

b = npy_log(a);

Связывание с ядровой математической библиотекой в расширении

Новая в версии 1.4.0.

Для использования ядровой математической библиотеки в собственном расширении, необходимо добавить опции компиляции и линковки npymath к расширению в setup.py:

>>> from numpy.distutils.misc_util import get_info
>>> info = get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=info)

Другими словами, использование info идентично использованию blas_info и аналогичных функций.

Функции полуточной точности

Новая в версии 1.6.0.

Заголовочный файл <numpy/halffloat.h> предоставляет функции для работы со значениями чисел с плавающей точкой IEEE 754-2008 16-битной точности. Хотя этот формат обычно не используется для числовых вычислений, он полезен для хранения значений, требующих чисел с плавающей точкой, но не нуждающихся в высокой точности. Он также может быть использован как учебный инструмент для понимания природы ошибки округления чисел с плавающей точкой.

Как и для других типов, NumPy включает typedef npy_half для 16-битного числа с плавающей точкой. В отличие от большинства других типов, вы не можете использовать его как обычный тип в C, поскольку это typedef для npy_uint16. Например, 1.0 выглядит как 0x3c00 для C, и если вы сравниваете различные отрицательные нули, вы получите -0.0 != 0.0 (0x8000 != 0x0000), что неправильно.

По этим причинам NumPy предоставляет API для работы со значениями npy_half, доступными при включении <numpy/halffloat.h> и подключении к ‘npymath’. Для функций, которые не предоставляются напрямую, таких как арифметические операции, предпочтительный метод заключается в преобразовании в float или double и обратно, как в следующем примере.

npy_half sum(int n, npy_half *array) {
    float ret = 0;
    while(n--) {
        ret += npy_half_to_float(*array++);
    }
    return npy_float_to_half(ret);
}

Ссылки на внешние ресурсы:

NPY_HALF_ZERO: Эта макрокоманда определена как положительный ноль.

NPY_HALF_PZERO: Эта макрокоманда определена как положительный ноль.

NPY_HALF_NZERO: Эта макрокоманда определена как отрицательный ноль.

NPY_HALF_ONE: Эта макрокоманда определена как 1.0.

NPY_HALF_NEGONE: Эта макрокоманда определена как -1.0.

NPY_HALF_PINF: Эта макрокоманда определена как +бесконечность.

NPY_HALF_NINF: Эта макрокоманда определена как -бесконечность.

NPY_HALF_NAN: Эта макрокоманда определена как значение NaN, гарантированно имеющее сброшенный бит знака.

float npy_half_to_float(npy_half h): Преобразует число с плавающей запятой полуточной точности в число с плавающей запятой одинарной точности.

double npy_half_to_double(npy_half h): Преобразует число с плавающей запятой полуточной точности в число с плавающей запятой двойной точности.

npy_half npy_float_to_half(float f): Преобразует число с плавающей запятой одинарной точности в число с плавающей запятой полуточной точности. Значение округляется до ближайшего представимого значения с полуточной точностью, при равенстве — к ближайшему четному. Если значение слишком мало или слишком велико, будут установлены биты системного потери или переполнения с плавающей запятой.

npy_half npy_double_to_half(double d): Преобразует число с плавающей запятой двойной точности в число с плавающей запятой полуточной точности. Значение округляется до ближайшего представимого значения с полуточной точностью, при равенстве — к ближайшему четному. Если значение слишком мало или слишком велико, будут установлены биты системного потери или переполнения с плавающей запятой.

int npy_half_eq(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 == h2).

int npy_half_ne(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 != h2).

int npy_half_le(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 <= h2).

int npy_half_lt(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 < h2).

int npy_half_ge(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 >= h2).

int npy_half_gt(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности (h1 > h2).

int npy_half_eq_nonan(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности, которые известны как не NaN (h1 == h2). Если значение является NaN, результат неопределён.

int npy_half_lt_nonan(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности, которые известны как не NaN (h1 < h2). Если значение является NaN, результат неопределён.

int npy_half_le_nonan(npy_half h1, npy_half h2): Сравнивает два числа с плавающей запятой полуточной точности, которые известны как не NaN (h1 <= h2). Если значение является NaN, результат неопределён.

int npy_half_iszero(npy_half h): Проверяет, равно ли значение числа с плавающей запятой полуточной точности нулю. Это может быть немного быстрее, чем вызов npy_half_eq(h, NPY_ZERO).

int npy_half_isnan(npy_half h): Проверяет, является ли число с плавающей запятой полуточной точности NaN.

int npy_half_isinf(npy_half h): Проверяет, является ли число с плавающей запятой полуточной точности плюс или минус бесконечностью.

int npy_half_isfinite(npy_half h): Проверяет, является ли число с плавающей запятой полуточной точности конечным (не NaN и не бесконечность).

int npy_half_signbit(npy_half h): Возвращает 1, если h отрицательно, 0 в противном случае.

npy_half npy_half_copysign(npy_half x, npy_half y): Возвращает значение x со значением бита знака, скопированным из y. Работает для любого значения, включая Inf и NaN.

npy_half npy_half_spacing(npy_half h): Это аналогично npy_spacing и npy_spacingf, описанным в разделе о низкоуровневой арифметике с плавающей запятой для чисел с плавающей запятой полуточной точности.

npy_half npy_half_nextafter(npy_half x, npy_half y): Это аналогично npy_nextafter и npy_nextafterf, описанным в разделе о низкоуровневой арифметике с плавающей запятой для чисел с плавающей запятой полуточной точности.

npy_uint16 npy_floatbits_to_halfbits(npy_uint32 f): Функция низкого уровня, которая преобразует число с плавающей запятой одинарной точности 32 бита, хранящееся как uint32, в число с плавающей запятой полуточной точности 16 бит.

npy_uint16 npy_doublebits_to_halfbits(npy_uint64 d): Функция низкого уровня, которая преобразует число с плавающей запятой двойной точности 64 бита, хранящееся как uint64, в число с плавающей запятой полуточной точности 16 бит.

npy_uint32 npy_halfbits_to_floatbits(npy_uint16 h): Функция низкого уровня, которая преобразует число с плавающей запятой полуточной точности 16 бит в число с плавающей запятой одинарной точности 32 бита, хранящееся как uint32.

npy_uint64 npy_halfbits_to_doublebits(npy_uint16 h): Функция низкого уровня, которая преобразует число с плавающей запятой полуточной точности 16 бит в число с плавающей запятой двойной точности 64 бита, хранящееся как uint64.

© 2005–2019 NumPy Developers
Licensed under the 3-clause BSD License.
https://docs.scipy.org/doc/numpy-1.17.0/reference/c-api.coremath.html