numpy.nditer

class numpy.nditer [source]

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

Параметры:

op : ndarray или последовательность array_like Массив(ы) для итерации. flags : последовательность str, необязательно Флаги для управления поведением итератора. “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 : список списков str, необязательно Это список флагов для каждого операнда. По меньшей мере, один из флагов “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 или кортеж dtype(s), необязательно Требуемый(ые) тип(ы) данных операндов. Если включено копирование или буферизация, данные будут преобразованы в/из их исходных типов. order : {‘C’, ‘F’, ‘A’, ‘K’}, необязательно Управляет порядком итерации. ‘C’ означает порядок C, ‘F’ означает порядок Fortran, ‘A’ означает порядок ‘F’, если все массивы являются Fortran-непрерывными, ‘C’ в противном случае, а ‘K’ означает максимально близкий к порядку, в котором элементы массива появляются в памяти. Это также влияет на порядок элементов в памяти операндов “allocate”, так как они выделяются, чтобы соответствовать порядку итерации. По умолчанию — ‘K’. casting : {‘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 для этой размерности. buffersize : целое число, необязательно При включенной буферизации управляет размером временных буферов. Установите 0 для значения по умолчанию.

Примечания

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

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

    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=[range(x.ndim)+[-1]*y.ndim,
                     [-1]*x.ndim+range(y.ndim),
                     None])

    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])

Атрибуты

dtypes	(кортеж 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	(кортеж операнда(ов)) Массив(ы) для итерации.
shape	(кортеж целых чисел) Кортеж формы, форма итератора.
value	Значение operands на текущей итерации. Обычно это кортеж скаляров массива, но если используется флаг “external_loop”, это кортеж одномерных массивов.

Методы

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