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 or sequence of array_like

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

flagssequence of str, optional

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

• 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_flagslist of list of str, optional

Это список флагов для каждого операнда. Как минимум, один из 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 or tuple of dtype(s), optional

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

order{‘C’, ‘F’, ‘A’, ‘K’}, optional

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

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Управляет тем, какие преобразования типов могут произойти при копировании или буферизации. Не рекомендуется устанавливать это значение в «unsafe», так как это может негативно повлиять на накопления.

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

op_axeslist of list of ints, optional

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

itershapetuple of ints, optional

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

buffersizeint, optional

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

Примечания

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

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

Примеры

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

>>> 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.

Атрибуты

dtypestuple of 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

Количество операндов итератора.

operandstuple of operand(s)

operands[Slice]

shapetuple of ints

Кортеж размеров, размеры итератора.

value

Значение operands на текущей итерации. Обычно это кортеж скаляров массивов, но если используется флаг external_loop, это кортеж одномерных массивов.

Методы

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