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

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) Требуется ли доступ к Python API для итерации, например, если один из операндов является массивом объектов.
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()	Проверить, есть ли оставшиеся итерации, и выполнить одну внутреннюю итерацию без возврата результата.
next
remove_axis(i)	Удаляет ось i из итератора.
remove_multi_index()	Если был указан флаг «multi_index», это удаляет его, позволяя дальнейшую оптимизацию внутренней структуры итерации.
reset()	Сбросить итератор в его начальное состояние.