numpy.nditer

class numpy.nditer [source]

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

Параметры:

op : ndarray или последовательность array_like Массив(ы) для итерации. flags : последовательность str, необязательно Флаги для управления поведением итератора. “buffered” включает буферизацию при необходимости. “c_index” вызывает отслеживание индекса в порядке C. “f_index” вызывает отслеживание индекса в порядке Fortran. “multi_index” вызывает отслеживание многомерного индекса, или кортежа индексов с по одному для каждой размерности итерации. “common_dtype” вызывает преобразование всех операндов к общему типу данных с копированием или буферизацией по необходимости. “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. 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 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']])
    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	x.next() -> следующее значение или исключение StopIteration
remove_axis(i)	Удаляет ось i из итератора.
remove_multi_index()	Если был указан флаг «multi_index», он удаляет его, что позволяет дальнейшей оптимизации внутренней структуры итерации.
reset()	Сбросить итератор в исходное состояние.