numpy.nditer

classnumpy.nditer(op, flags=None, op_flags=None, op_dtypes=None, order='K', casting='safe', op_axes=None, itershape=None, buffersize=0)[source]

Эффективный многомерный итератор для итерации по массивам. Для начала работы с этим объектом см. вводное руководство по итерации массивов.

Параметры:

opndarray или последовательность array_like

Массив(ы) для итерации.

flagsпоследовательность str, необязательно

Флаги для управления поведением итератора.

buffered включает буферизацию при необходимости.
c_index отслеживает индекс в порядке C.
f_index отслеживает индекс в порядке Fortran.
multi_index отслеживает многомерный индекс или кортеж индексов по одному для каждой размерности итерации.
common_dtype приводит все операнды к общему типу данных с копированием или буферизацией по необходимости.
copy_if_overlap заставляет итератор определять, есть ли перекрытие между операндами чтения и записи, и создавать временные копии по необходимости, чтобы избежать перекрытия. Возможны ложноположительные результаты (необходимое копирование) в некоторых случаях.
delay_bufalloc откладывает выделение буферов до вызова reset(). Позволяет allocate операндам быть инициализированными перед копированием их значений в буферы.
external_loop заставляет values быть одномерными массивами с несколькими значениями вместо нульмерных.
grow_inner позволяет делать размеры массива value больше размера буфера, когда используются как buffered, так и external_loop.
ranged позволяет ограничить итератор поддиапазоном значений iterindex.
refs_ok включает итерацию по типам ссылок, таким как массивы object.
reduce_ok включает итерацию по readwrite операндам, которые транслируются, также известным как операнды сокращения.
zerosize_ok позволяет itersize быть равным нулю.

op_flagsсписок списков str, необязательно

Это список флагов для каждого операнда. По меньшей мере, один из readonly, readwrite, или writeonly должен быть указан.

readonly указывает, что операнд будет только считываться.
readwrite указывает, что операнд будет считываться и записываться.
writeonly указывает, что операнд будет только записываться.
no_broadcast предотвращает трансляцию операнда.
contig принудительно делает данные операнда непрерывными.
aligned принудительно выравнивает данные операнда.
nbo принудительно устанавливает порядок байтов операнда в родной.
copy позволяет создавать временную только для чтения копию, если это необходимо.
updateifcopy позволяет создавать временную копию для чтения и записи, если это необходимо.
allocate заставляет массив выделяться, если он None в параметре op.
no_subtype предотвращает использование подтипа операндом allocate.
arraymask указывает, что этот операнд является маской для выбора элементов при записи в операнды со флагом ‘writemasked’. Итератор это не проверяет, но при записи из буфера обратно в массив, он копирует только те элементы, которые указаны этой маской.
writemasked указывает, что будут записываться только элементы, где выбранный операнд arraymask равен True.
overlap_assume_elementwise может использоваться для обозначения операндов, которые обращаются только в порядке итерации, чтобы разрешить менее консервативное копирование, когда присутствует copy_if_overlap.

op_dtypesdtype или кортеж dtype(s), необязательно

Требуемый тип данных операндов. Если копирование или буферизация включены, данные будут преобразованы в/из их оригинальных типов.

order{‘C’, ‘F’, ‘A’, ‘K’}, необязательно

Управляет порядком итерации. ‘C’ означает порядок C, ‘F’ — Fortran, ‘A’ — порядок ‘F’, если все массивы имеют порядок Fortran, в противном случае — порядок ‘C’, а ‘K’ — как можно ближе к порядку появления элементов массива в памяти. Это также влияет на порядок памяти элементов allocate операндов, поскольку они выделены для совместимости с порядком итерации. По умолчанию — ‘K’.

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, необязательно

Управляет типом преобразования данных при создании копии или буферизации. Установка этого значения в ‘unsafe’ не рекомендуется, так как это может негативно повлиять на аккумулирование.

‘no’ означает, что типы данных не должны преобразовываться совсем.
‘equiv’ означает, что допускаются только изменения порядка байтов.
‘safe’ означает, что допускаются только преобразования, которые могут сохранить значения.
‘same_kind’ означает, что допускаются только безопасные преобразования или преобразования внутри одного вида, например, float64 в float32.
‘unsafe’ означает, что любые преобразования данных могут быть выполнены.

op_axesсписок списков int, необязательно

Если предоставлено, это список int или None для каждого операнда. Список осей для операнда — отображение из размерностей итератора в размерности операнда. Значение -1 может быть помещено для элементов, что приведет к обработке этой размерности как newaxis.

itershapeкортеж int, необязательно

Желаемая форма итератора. Это позволяет allocate операндам с размерностью, отображенной op_axes, не соответствующей размерности другого операнда, получить значение, отличное от 1 для этой размерности.

buffersizeint, необязательно

Когда включена буферизация, контролирует размер временных буферов. Устанавливается в 0 для значения по умолчанию.

Примечания

nditer заменяет flatiter. Реализация итератора за nditer также доступна в NumPy C API.

Python-экспозиция предоставляет два интерфейса итерации, один из которых следует протоколу Python-итератора, а другой — зеркалит шаблон C-стиля do-while. В большинстве случаев предпочтительнее подход на чистом Python, но если вам нужны координаты или индекс итератора, используйте шаблон C-стиля.

Примеры

Вот как мы можем написать функцию iter_add, используя протокол Python-итератора:

>>> def iter_add_py(x, y, out=None):
...     addop = np.add
...     it = np.nditer([x, y, out], [],
...                 [['readonly'], ['readonly'], ['writeonly','allocate']])
...     with it:
...         for (a, b, c) in it:
...             addop(a, b, out=c)
...         return it.operands[2]

Вот та же функция, но в соответствии со стилем C:

>>> def iter_add(x, y, out=None):
...    addop = np.add
...    it = np.nditer([x, y, out], [],
...                [['readonly'], ['readonly'], ['writeonly','allocate']])
...    with it:
...        while not it.finished:
...            addop(it[0], it[1], out=it[2])
...            it.iternext()
...        return it.operands[2]

Вот пример функции внешнего произведения:

>>> def outer_it(x, y, out=None):
...     mulop = np.multiply
...     it = np.nditer([x, y, out], ['external_loop'],
...             [['readonly'], ['readonly'], ['writeonly', 'allocate']],
...             op_axes=[list(range(x.ndim)) + [-1] * y.ndim,
...                      [-1] * x.ndim + list(range(y.ndim)),
...                      None])
...     with it:
...         for (a, b, c) in it:
...             mulop(a, b, out=c)
...         return it.operands[2]

>>> a = np.arange(2)+1
>>> b = np.arange(3)+1
>>> outer_it(a,b)
array([[1, 2, 3],
       [2, 4, 6]])

Вот пример функции, которая действует как ufunc «лямбда»:

>>> def luf(lamdaexpr, *args, **kwargs):
...    '''luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)'''
...    nargs = len(args)
...    op = (kwargs.get('out',None),) + args
...    it = np.nditer(op, ['buffered','external_loop'],
...            [['writeonly','allocate','no_broadcast']] +
...                            [['readonly','nbo','aligned']]*nargs,
...            order=kwargs.get('order','K'),
...            casting=kwargs.get('casting','safe'),
...            buffersize=kwargs.get('buffersize',0))
...    while not it.finished:
...        it[0] = lamdaexpr(*it[1:])
...        it.iternext()
...    return it.operands[0]

>>> a = np.arange(5)
>>> b = np.ones(5)
>>> luf(lambda i,j:i*i + j/2, a, b)
array([  0.5,   1.5,   4.5,   9.5,  16.5])

Если используются флаги операндов "writeonly" или "readwrite", операнды могут быть представлениями исходных данных со флагом WRITEBACKIFCOPY. В этом случае nditer должен использоваться как менеджер контекста или метод nditer.close должен вызываться перед использованием результата. Временные данные будут записаны обратно в исходные данные при вызове функции __exit__, но не раньше:

>>> a = np.arange(6, dtype='i4')[::-2]
>>> with np.nditer(a, [],
...        [['writeonly', 'updateifcopy']],
...        casting='unsafe',
...        op_dtypes=[np.dtype('f4')]) as i:
...    x = i.operands[0]
...    x[:] = [-1, -2, -3]
...    # a still unchanged here
>>> a, x
(array([-1, -2, -3], dtype=int32), array([-1., -2., -3.], dtype=float32))

Важно отметить, что после выхода из итератора висячие ссылки (например, x в примере) могут или не могут совместно использовать данные с исходными данными a. Если семантика записи была активна, т. е. если x.base.flags.writebackifcopy равно True, то выход из итератора разорвёт связь между x и a, запись в x больше не будет влиять на a. Если семантика записи неактивна, тогда x.data по-прежнему будет указывать на какую-то часть a.data, и запись в одну из них будет влиять на другую.

Управление контекстом и метод close появились в версии 1.15.0.

Атрибуты:

dtypesкортеж из типов данных: Типы данных значений, предоставляемых в value. Они могут отличаться от типов данных операндов, если включено буферирование. Действительно только до закрытия итератора.
finishedbool: Указывает, завершена или нет итерация по операндам.
has_delayed_bufallocbool: Если True, итератор был создан с флагом delay_bufalloc, и на нём ещё не вызывалась функция reset().
has_indexbool: Если True, итератор был создан с флагом c_index или флагом f_index, и свойство index может быть использовано для его получения.
has_multi_indexbool: Если True, итератор был создан с флагом multi_index, и свойство multi_index может быть использовано для его получения.
index: Когда использовался флаг c_index или f_index, это свойство предоставляет доступ к индексу. Вызывает ValueError, если обращение осуществляется и has_index равно False.
iterationneedsapibool: Указывает, требует ли итерация доступа к Python API, например, если один из операндов является массивом объектов.
iterindexint: Индекс, соответствующий порядку итерации.
itersizeint: Размер итератора.
itviews: Структурированные представления operands в памяти, соответствующие переупорядоченному и оптимизированному шаблону доступа к итератору. Действительно только до закрытия итератора.
multi_index: Когда использовался флаг multi_index, это свойство предоставляет доступ к индексу. Вызывает ValueError, если доступ осуществляется, и has_multi_index равно False.
ndimint: Размерность итератора.
nopint: Количество операндов итератора.
operandsкортеж из операндов: operands[Slice]
shapeкортеж целых чисел: Кортеж формы, форма итератора.
value: Значение operands на текущей итерации. Обычно это кортеж из скаляров массивов, но если используется флаг external_loop, это кортеж одномерных массивов.

Методы

`close`()	Обработка всех семантик записи для изменяемых операндов.
`copy`()	Получение копии итератора в его текущем состоянии.
`debug_print`()	Вывод текущего состояния экземпляра `nditer` и отладочной информации в stdout.
`enable_external_loop`()	Если "external_loop" не использовался при создании, но желателен, это изменяет итератор, чтобы он вел себя так, как будто флаг был указан.
`iternext`()	Проверка наличия оставшихся итераций и выполнение одной внутренней итерации без возврата результата.
`remove_axis`(i, /)	Удаляет ось `i` из итератора.
`remove_multi_index`()	Если был указан флаг "multi_index", это удаляет его, позволяя оптимизировать внутреннюю структуру итерации.
`reset`()	Сброс итератора в исходное состояние.

© 2005–2024 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/2.0/reference/generated/numpy.nditer.html