Библиотеки ядра NumPy

Начиная с 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.

npy_isnan(x)

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

npy_isfinite(x)

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

npy_isinf(x)

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

npy_signbit(x)

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

npy_copysign(x, 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})\)

Манипуляции с числами с плавающей запятой низкого уровня

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

doublenpy_nextafter(doublex, doubley)

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

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

doublenpy_spacing(doublex)

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

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

voidnpy_set_floatstatus_divbyzero()

Устанавливает исключение деления на ноль с плавающей запятой

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

voidnpy_set_floatstatus_overflow()

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

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

voidnpy_set_floatstatus_underflow()

Устанавливает исключение подпорогового значения с плавающей запятой

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

voidnpy_set_floatstatus_invalid()

Устанавливает исключение недействительности с плавающей запятой

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

intnpy_get_floatstatus()

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

• NPY_FPE_DIVIDEBYZERO
• NPY_FPE_OVERFLOW
• NPY_FPE_UNDERFLOW
• NPY_FPE_INVALID

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

Добавлено в версии 1.9.0.

intnpy_get_floatstatus_barrier(char*)

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

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

• NPY_FPE_DIVIDEBYZERO
• NPY_FPE_OVERFLOW
• NPY_FPE_UNDERFLOW
• NPY_FPE_INVALID

Добавлено в версии 1.15.0.

intnpy_clear_floatstatus()

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

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

Добавлено в версии 1.9.0.

intnpy_clear_floatstatus_barrier(char*)

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

Добавлено в версии 1.15.0.

Функции для комплексных чисел

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

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

b = npy_log(a);

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

Чтобы использовать библиотеку математических функций ядра в собственном расширении, необходимо добавить опции компиляции и компоновки 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 и т.п.

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

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

Как и для других типов, 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);
}

Внешние ссылки:

• 754-2008 IEEE Standard for Floating-Point Arithmetic
• Статья Википедии о формате чисел с плавающей запятой полуточной точности.
• Поддержка пикселей с плавающей запятой OpenGL Half Float
• Формат изображения OpenEXR.

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, гарантирующего, что бит знака не установлен.

floatnpy_half_to_float(npy_halfh)

Преобразует число с плавающей запятой полуточной точности в число с плавающей запятой одинарной точности.

doublenpy_half_to_double(npy_halfh)

Преобразует число с плавающей запятой полуточной точности в число с плавающей запятой двойной точности.

npy_halfnpy_float_to_half(floatf)

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

npy_halfnpy_double_to_half(doubled)

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

intnpy_half_eq(npy_halfh1, npy_halfh2)

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

intnpy_half_ne(npy_halfh1, npy_halfh2)

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

intnpy_half_le(npy_halfh1, npy_halfh2)

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

intnpy_half_lt(npy_halfh1, npy_halfh2)

Сравнивает два числа с половинной точностью (h1 < h2).

intnpy_half_ge(npy_halfh1, npy_halfh2)

Сравнивает два числа с половинной точностью (h1 >= h2).

intnpy_half_gt(npy_halfh1, npy_halfh2)

Сравнивает два числа с половинной точностью (h1 > h2).

intnpy_half_eq_nonan(npy_halfh1, npy_halfh2)

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

intnpy_half_lt_nonan(npy_halfh1, npy_halfh2)

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

intnpy_half_le_nonan(npy_halfh1, npy_halfh2)

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

intnpy_half_iszero(npy_halfh)

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

intnpy_half_isnan(npy_halfh)

Проверяет, является ли число с половинной точностью NaN.

intnpy_half_isinf(npy_halfh)

Проверяет, является ли число с половинной точностью плюс или минус Inf.

intnpy_half_isfinite(npy_halfh)

Проверяет, является ли число с половинной точностью конечным (не NaN или Inf).

intnpy_half_signbit(npy_halfh)

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

npy_halfnpy_half_copysign(npy_halfx, npy_halfy)

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

npy_halfnpy_half_spacing(npy_halfh)

Это то же самое для чисел с половинной точностью, что и npy_spacing и npy_spacingf, описанные в разделе о низкоуровневых числах с плавающей точкой.

npy_halfnpy_half_nextafter(npy_halfx, npy_halfy)

Это то же самое для чисел с половинной точностью, что и npy_nextafter и npy_nextafterf, описанные в разделе о низкоуровневых числах с плавающей точкой.

npy_uint16npy_floatbits_to_halfbits(npy_uint32f)

Функция низкого уровня, которая преобразует 32-битное число с плавающей точностью одинарной точности, хранящееся как uint32, в 16-битное число с плавающей точностью половинной точности.

npy_uint16npy_doublebits_to_halfbits(npy_uint64d)

Функция низкого уровня, которая преобразует 64-битное число с плавающей точностью двойной точности, хранящееся как uint64, в 16-битное число с плавающей точностью половинной точности.

npy_uint32npy_halfbits_to_floatbits(npy_uint16h)

Функция низкого уровня, которая преобразует 16-битное число с плавающей точностью половинной точности в 32-битное число с плавающей точностью одинарной точности, хранящееся как uint32.

npy_uint64npy_halfbits_to_doublebits(npy_uint16h)

Функция низкого уровня, которая преобразует 16-битное число с плавающей точностью половинной точности в 64-битное число с плавающей точностью двойной точности, хранящееся как uint64.