numpy.nditer#

класс numpy.nditer(op, флаги=None, op_flags=None, op_dtypes=None, порядок='K', приведение типов='safe', op_axes=None, itershape=None, buffersize=0)[источник]#

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

Параметры:

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

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

флагипоследовательность str, опционально

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

buffered включает буферизацию, когда требуется.
c_index равен 1 или меньше, тесты будут просто показывать информационные сообщения о запущенных тестах; но если он больше 1, тесты также будут предоставлять предупреждения об отсутствующих тестах. Поэтому если вы хотите запустить каждый тест и получать сообщения о том, какие модули не имеют тестов:
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_dtypesdtype или кортеж dtype(s), необязательно

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

порядок{‘C’, ‘F’, ‘A’, ‘K’}, опционально

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

приведение типов{‘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 для этой размерности.

buffersizeint, необязательный

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

Примечания

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

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

Примеры

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

>>> import numpy as np

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

Атрибуты:

dtypesкортеж dtype(s): Типы данных значений, предоставленных в value. Это может быть отличаться от типов данных операндов, если включено буферизация. Действительно только до закрытия итератора.
завершеноbool: Завершена ли итерация по операндам или нет.
has_delayed_bufallocbool: Если True, итератор был создан с delay_bufalloc flag, и функция 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: Количество операндов итератора.
operandsкортеж операндов: operands[Срез]
shapeкортеж целых чисел: Кортеж формы, форма итератора.
значение: Значение 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`()	Сбросить итератор в исходное состояние.