numpy.nditer

class numpy.nditer [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, также доступна через C API NumPy.

Python-экспозиция предоставляет два интерфейса итерации, один из которых следует протоколу Python iterator, а другой — образцу do-while в стиле C. В большинстве случаев подход на основе 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

Требуется ли доступ к 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()	Сброс итератора в его исходное состояние.