Библиотеки ядра 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): Эта функция эквивалентна встроенной функции Fortran. Возвращает расстояние между x и следующим представимым значением числа с плавающей точкой от x, например, spacing(1) == eps. Spacing для 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 и т. д.

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

Новая версия с 2.0.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.16.1/reference/c-api.coremath.html