numpy.nditer

class numpy.nditer [source]

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

Параметры:

op : ndarray or sequence of array_like Массив(ы) для итерации. flags : sequence 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_flags : list 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_dtypes : dtype 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_axes : list of list of ints, optional Если указано, это список целых чисел или None для каждого операнда. Список осей для операнда является отображением измерений итератора на измерения операнда. Значение -1 может быть помещено для записей, вызывая то, что эта размерность будет обрабатываться как newaxis. itershape : tuple of ints, optional Желаемая форма итератора. Это позволяет allocate операндам с размером, сопоставленным по оси op, не соответствующим размерности другого операнда, получить значение, не равное 1 для этой размерности. buffersize : int, 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. Если семантика writeback активна, т.е. если x.base.flags.writebackifcopy — True, то выход из итератора разорвёт связь между x и a, и запись в x больше не будет влиять на a. Если семантика writeback неактивна, то x.data всё ещё будет указывать на какую-то часть a.data, и запись в одну из них будет влиять на другую.

Атрибуты:

dtypes : tuple of dtype(s) Типы данных значений, предоставляемых в value. Это может отличаться от типов данных операндов, если включено буферирование. Действительно только до закрытия итератора. finished : bool Закончена или нет итерация по операндам. has_delayed_bufalloc : bool Если True, итератор был создан с флагом delay_bufalloc, и на нём ещё не вызывалась функция reset(). has_index : bool Если True, итератор был создан с флагом c_index или флагом f_index, и свойство index может быть использовано для его получения. has_multi_index : bool Если True, итератор был создан с флагом multi_index, и свойство multi_index может быть использовано для его получения. index Когда использовался флаг c_index или f_index, это свойство предоставляет доступ к индексу. Вызывает ValueError, если доступ осуществляется и has_index равно False. iterationneedsapi : bool Требуется ли доступ к API Python для итерации, например, если один из операндов является массивом объектов. iterindex : int Индекс, соответствующий порядку итерации. itersize : int Размер итератора. itviews Структурированные представление(я) operands в памяти, соответствующие переупорядоченному и оптимизированному шаблону доступа итератора. Действительно только до закрытия итератора. multi_index Когда использовался флаг multi_index, это свойство предоставляет доступ к индексу. Вызывает ValueError, если доступ осуществляется и has_multi_index равно False. ndim : int Размеры итератора. nop : int Количество операндов итератора. operands : tuple of operand(s) operands[Slice] shape : tuple of ints Кортеж формы, форма итератора. value Значение operands на текущей итерации. Обычно это кортеж массивов-скаляров, но если используется флаг external_loop, это кортеж одномерных массивов.

Методы

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