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 также доступна в API NumPy C.

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.

Атрибуты

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

Требуется ли доступ к Python API для итерации, например, если один из операндов является массивом объектов.

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