numpy.nditer

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

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

Параметры

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

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

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

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

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 включает итерацию типов ссылок, таких как массивы объектов.
reduce_ok включает итерацию readwrite операндов, которые транслируются, также известные как операнды сокращения.
zerosize_ok позволяет itersize быть равным нулю.

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

Это список флагов для каждого операнда. По крайней мере, один из 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_dtypesтип данных или кортеж типов данных, необязательно

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

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список списков целых чисел, необязательно

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

itershapeкортеж целых чисел, необязательно

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

buffersizeцелое число, необязательно

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

Примечания

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

Python-интерфейс предоставляет два интерфейса итерации, один, который следует протоколу Python-итератора, и другой, который отображает шаблон do-while в стиле C. В большинстве случаев подход на основе 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. Если семантика writeback была активна, т.е. если x.base.flags.writebackifcopy равна True, то выход из итератора разорвёт связь между x и a, запись в x больше не будет записывать в a. Если семантика writeback не активна, то x.data по-прежнему будет указывать на какую-то часть a.data, и запись в одну повлияет на другую.

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

Атрибуты

dtypesкортеж из dtype(s): Типы данных значений, предоставляемых в 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: Требуется ли доступ к API Python для итерации, например, если один из операндов является массивом объектов.
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–2022 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/1.21/reference/generated/numpy.nditer.html